Skip to content

Commit b739914

Browse files
committed
docs(skills): scope the deleted-seed-row rule to the loads that keep the record
The landed-keys rule holds only where AppPlugin runs the load for a known organization. The seed guide now names the loads that keep no record (a publish, a package install or upgrade, the marketplace fallback replayer, a load with no organization or no sys_seed_landed_key), and the seeds reference scopes its sentence the same way and says again when a seed replays. Its two long table rows are trimmed under 120 bytes, the externalId row names every keyed mode, and the seed eval's demo dataset declares upsert so applyOn 'create' is live. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J8VVAkA4qny8vRgP2NzRgs
1 parent 6ed361c commit b739914

4 files changed

Lines changed: 27 additions & 17 deletions

File tree

‎.changeset/skills-data-seed-modes-landed-keys.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
'@objectstack/skills': patch
33
---
44

5-
docs(skills): the objectstack-data seeds reference now teaches the seed modes the loader runs: `ignore` is the default (create-only), `replace` deletes nothing (it inserts into a table the caller cleared), and `insert` duplicates on each replay. It also says that a boot or organization replay does not re-insert a seed row a person deleted, and that `seed-replayer` with `{ reseed: true }` restores it. The data-modeling seed guide teaches the same rule.
5+
docs(skills): the objectstack-data seeds reference now teaches the seed modes the loader runs: `ignore` is the default (create-only), `replace` deletes nothing (it inserts into a table the caller cleared), and `insert` duplicates on each replay. It also says that AppPlugin's boot and organization replays do not re-insert a seed row a person deleted (a publish or package install keeps no record, so the row comes back there), and that `seed-replayer` with `{ reseed: true }` restores it. The data-modeling seed guide teaches the same rule and names the loads that keep no record.
66

77
Clause-②: no
88
Metadata-protocol: none

‎content/docs/data-modeling/seed-data.mdx‎

Lines changed: 18 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,8 +71,8 @@ customer has since edited.
7171

7272
| Mode | Behavior | Use Case |
7373
|:-----|:---------|:---------|
74-
| `ignore` | **Default.** Create-only: insert a record whose row is missing (unless a person [deleted it](#a-deleted-seed-row-stays-deleted)), leave an existing row exactly as it is | Business and starter data the customer owns once it is loaded |
75-
| `upsert` | Create if new, and on **every** replay write each declared column back onto the matched row | Reference data the package must keep current |
74+
| `ignore` | **Default.** Create-only: insert a record whose row is missing (a boot or organization replay skips one a person [deleted](#a-deleted-seed-row-stays-deleted)), leave an existing row exactly as it is | Business and starter data the customer owns once it is loaded |
75+
| `upsert` | Create if new (a boot or organization replay skips one a person [deleted](#a-deleted-seed-row-stays-deleted)), and on **every** replay write each declared column back onto the matched row | Reference data the package must keep current |
7676
| `insert` | Insert **every** record unconditionally — no existing-row check, so it **duplicates the table on each replay boot** ([#3434](https://github.com/objectstack-ai/objectstack/issues/3434)). Rarely what you want | Append-only rows loaded exactly once (never re-run) |
7777
| `update` | Update only, skip if not found | Migration patches on existing rows |
7878
| `replace` | Insert without checking for an existing match — the seed loader does **not** delete anything itself; the target table must already be empty (or cleared by the caller) | Cache / lookup tables rebuilt from an already-truncated table |
@@ -157,15 +157,25 @@ It is almost never the right mode: leave `mode` unset (create-only), or declare
157157

158158
Each organization records which seed rows landed in it, by `externalId`, in the
159159
platform object `sys_seed_landed_key`. When a person deletes a seeded row, the
160-
next replay does not insert it again: an `ignore` or `upsert` dataset inserts a
161-
missing row only if its key never landed in that organization. A row an upgrade adds to the seed has never landed, so it
160+
next boot or organization replay does not insert it again: an `ignore` or
161+
`upsert` dataset inserts a missing row only if its key never landed in that
162+
organization. A row an upgrade adds to the seed has never landed, so it
162163
is still inserted. A reference to the deleted row from another seed row is left
163164
unwritten rather than reported as an error.
164165

165-
The record is honoured by the boot seed (`objectstack serve`, `os start`, so
166-
every restart and upgrade), the per-organization replay, and the dev hot
167-
reload. A row deleted before your runtime had this rule comes back once, on the
168-
first replay after the upgrade, and stays deleted from then on.
166+
The record is kept and honoured only where AppPlugin runs the load for a known
167+
organization: the single-tenant boot seed (`objectstack serve`, `os start`, on
168+
every restart; a multi-tenant boot seeds through the per-organization replay
169+
instead), the per-organization replay (`seed-replayer`), and the dev hot reload.
170+
A seed publish, a package install or upgrade (`os package install`, the
171+
marketplace install, its heal and its sample-data reseed) keep no record, so a
172+
deleted row comes back on those. So do a load with no organization, a
173+
composition that does not register `sys_seed_landed_key`
174+
(`@objectstack/platform-objects`), and the marketplace's fallback
175+
`seed-replayer`, which it registers when no app has seed data.
176+
177+
A row deleted before your runtime had this rule comes back once, on the first
178+
replay after the upgrade, and stays deleted from then on.
169179

170180
To bring the deleted rows back on purpose, a host or plugin calls the
171181
`seed-replayer` kernel service with `{ reseed: true }`:

‎skills/objectstack-data/evals/hooks-security-seeds-datasources.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@
3333
},
3434
{
3535
"id": 4,
36-
"prompt": "Seed the `country` table for every environment; add demo `opportunity` rows (dev/test only) closing 45 days after install, owned by the installer. A nightly job advances `stage`; a seed replay must not reset it.",
37-
"expected_output": "`defineSeed(Country, { externalId: 'code', mode: 'upsert', records })` for reference data; `defineSeed(Opportunity, { env: ['dev', 'test'], ... })` for demo rows with no `mode` (the `ignore` default never writes a matched row, so a replay leaves `stage`) — natural-key lookups, CEL values (`close_date: cel`daysFromNow(45)``, `owner_id: cel`os.user.id``), parents first; on an `upsert` dataset, `columns: { stage: { applyOn: 'create' } }` leaves the job-owned column.",
36+
"prompt": "Seed the `country` table for every environment; add demo `opportunity` rows (dev/test only) closing 45 days after install, owned by the installer, and refreshed from the seed on every replay except `stage`: a nightly job advances it, and a replay must not reset it.",
37+
"expected_output": "`defineSeed(Country, { externalId: 'code', mode: 'upsert', records })` for reference data; `defineSeed(Opportunity, { mode: 'upsert', env: ['dev', 'test'], ... })` for the refreshed demo rows — natural-key lookups, CEL values (`close_date: cel`daysFromNow(45)``, `owner_id: cel`os.user.id``), parents first; `columns: { stage: { applyOn: 'create' } }` so the `upsert` replay leaves the job-owned column (the `ignore` default would refresh nothing).",
3838
"files": [],
3939
"assertions": {
4040
"must_contain": ["defineSeed", "externalId", "upsert", "env:", "daysFromNow", "applyOn: 'create'"],

‎skills/objectstack-data/references/seeds.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ export const SeedData = [statusSeed, categorySeed]; // parents first
4545
| Field | Default | Purpose |
4646
|:------|:--------|:--------|
4747
| `object` | derived | Auto-set from `objectDef.name` — never write manually |
48-
| `externalId` | `'name'` | Stable business key used for upsert / update lookup |
48+
| `externalId` | `'name'` | Stable business key every keyed mode matches on |
4949
| `mode` | `'ignore'` | Import strategy (see below) |
5050
| `columns` | — | Per-column write policy, keyed by field: `{ FIELD: { applyOn: 'create' } }` (below) |
5151
| `env` | `['prod','dev','test']` | Environments where the seed loads |
@@ -57,15 +57,15 @@ Full Zod shape: `node_modules/@objectstack/spec/src/data/seed.zod.ts`.
5757

5858
| Mode | Behavior | Use for |
5959
|:-----|:---------|:--------|
60-
| `ignore` (default) | Create-only: insert a missing row, leave a matched row as is. | Data the customer owns once loaded |
61-
| `upsert` | Insert if missing; every replay writes the declared columns back. | Reference data the package keeps current |
60+
| `ignore` (default) | Create-only: insert a missing row, leave a matched row as is. | Data the customer owns |
61+
| `upsert` | Insert if missing; every replay writes declared columns back. | Reference data kept current |
6262
| `insert` | Insert every record, no match: duplicates on each replay. | Rows loaded once |
6363
| `update` | Update only existing rows; never create. | Patching existing config |
6464
| `replace` ⚠️ | Insert with no match; deletes nothing, the caller clears the table. | Cache / lookup tables only |
6565

66-
A boot or organization replay does not re-insert a keyed row a person deleted
67-
(landed keys are recorded per organization); `seed-replayer` with
68-
`{ reseed: true }` restores it.
66+
A seed replays on each boot, install and re-publish. AppPlugin's boot and organization
67+
replays (not a publish or package install) do not re-insert a keyed row a
68+
person deleted; `seed-replayer` with `{ reseed: true }` restores it.
6969

7070
### Columns the app owns after the first load — `columns.FIELD.applyOn`
7171

0 commit comments

Comments
 (0)