Skip to content

Commit 6ed361c

Browse files
committed
docs(skills): teach the seed modes the loader runs and that a deleted seed row stays deleted
The objectstack-data seeds reference called upsert the default and said replace deletes every row first. The loader defaults to ignore (create-only) and replace deletes nothing. The reference, its seed eval and the data-modeling seed guide now say so, and teach that a boot or organization replay does not re-insert a seed row a person deleted, with seed-replayer { reseed: true } as the way to restore it. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J8VVAkA4qny8vRgP2NzRgs
1 parent b631573 commit 6ed361c

4 files changed

Lines changed: 50 additions & 20 deletions

File tree

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
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.
6+
7+
Clause-②: no
8+
Metadata-protocol: none

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ customer has since edited.
7171

7272
| Mode | Behavior | Use Case |
7373
|:-----|:---------|:---------|
74-
| `ignore` | **Default.** Create-only: insert a record whose row is missing, leave an existing row exactly as it is | Business and starter data the customer owns once it is loaded |
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 |
7575
| `upsert` | Create if new, 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 |
@@ -153,6 +153,28 @@ check**, so a replayed `insert` dataset duplicates its table on each restart
153153
It is almost never the right mode: leave `mode` unset (create-only), or declare
154154
`upsert` for reference data, with a stable `externalId` instead. `os validate` warns on any `mode: 'insert'` seed.
155155

156+
### A Deleted Seed Row Stays Deleted
157+
158+
Each organization records which seed rows landed in it, by `externalId`, in the
159+
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
162+
is still inserted. A reference to the deleted row from another seed row is left
163+
unwritten rather than reported as an error.
164+
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.
169+
170+
To bring the deleted rows back on purpose, a host or plugin calls the
171+
`seed-replayer` kernel service with `{ reseed: true }`:
172+
173+
```typescript
174+
const replay = ctx.getService('seed-replayer'); // ctx: the plugin's context
175+
await replay(organizationId, { reseed: true }); // inserts every missing seed row
176+
```
177+
156178
---
157179

158180
## Seeds and State Machines

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
{
3535
"id": 4,
3636
"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 — natural-key lookups, CEL values (`close_date: cel`daysFromNow(45)``, `owner_id: cel`os.user.id``), parents first; `columns: { stage: { applyOn: 'create' } }` so an `upsert` replay leaves the job-owned column.",
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.",
3838
"files": [],
3939
"assertions": {
4040
"must_contain": ["defineSeed", "externalId", "upsert", "env:", "daysFromNow", "applyOn: 'create'"],

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

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@
22

33
Object definition and seed data live together — a `*.object.ts` usually
44
pairs with a `*.seed.ts` (fixtures, reference rows, bootstrap data).
5-
`defineSeed()` is type-safe: TypeScript checks every record's field keys
6-
against the object definition.
75

86
> The factory is `defineSeed` — **not** `defineDataset`, which is the
97
> unrelated ADR-0021 analytics semantic layer (`@objectstack/spec/ui`).
@@ -33,7 +31,6 @@ export const statusSeed = defineSeed(Status, {
3331
// Demo data — dev/test only
3432
export const categorySeed = defineSeed(Category, {
3533
externalId: 'slug',
36-
mode: 'upsert',
3734
env: ['dev', 'test'],
3835
records: [
3936
{ slug: 'electronics', name: 'Electronics' },
@@ -49,7 +46,7 @@ export const SeedData = [statusSeed, categorySeed]; // parents first
4946
|:------|:--------|:--------|
5047
| `object` | derived | Auto-set from `objectDef.name` — never write manually |
5148
| `externalId` | `'name'` | Stable business key used for upsert / update lookup |
52-
| `mode` | `'upsert'` | Import strategy (see below) |
49+
| `mode` | `'ignore'` | Import strategy (see below) |
5350
| `columns` | — | Per-column write policy, keyed by field: `{ FIELD: { applyOn: 'create' } }` (below) |
5451
| `env` | `['prod','dev','test']` | Environments where the seed loads |
5552
| `records` | — | `Partial<Record<keyof object.fields, unknown>>[]` |
@@ -60,27 +57,31 @@ Full Zod shape: `node_modules/@objectstack/spec/src/data/seed.zod.ts`.
6057

6158
| Mode | Behavior | Use for |
6259
|:-----|:---------|:--------|
63-
| `upsert` (default) | Update by `externalId`, insert if missing. Idempotent. | Reference data, bootstrap rows |
64-
| `insert` | Insert all; fail on duplicate `externalId`. | Append-only / audit tables |
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 |
62+
| `insert` | Insert every record, no match: duplicates on each replay. | Rows loaded once |
6563
| `update` | Update only existing rows; never create. | Patching existing config |
66-
| `ignore` | Insert; silently skip duplicates. | Additive bootstrap |
67-
| `replace` ⚠️ | Delete everything, then insert. **Data loss.** | Cache / lookup tables only — never user data |
64+
| `replace` ⚠️ | Insert with no match; deletes nothing, the caller clears the table. | Cache / lookup tables only |
65+
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.
6869

6970
### Columns the app owns after the first load — `columns.FIELD.applyOn`
7071

71-
A seed is replayed (every dev-server boot, every re-publish) and an `upsert`
72-
replay re-asserts every column on the row it matched — right for master data,
73-
wrong for a column a job or an admin advances after the first load. Declare it
72+
An `upsert` replay re-asserts every column on the row it matched — wrong for
73+
a column a job or an admin advances after the first load. Declare it
7474
`applyOn: 'create'`: written when the seed creates the row, left as the row
75-
holds it on every replay (an `update` dataset never writes it; `insert` /
76-
`ignore` / `replace` never update a matched row, so nothing changes there).
75+
holds it on every replay (`update` never writes it; no other mode updates a
76+
matched row).
7777
Each key must be a field of the object or an injected system column —
7878
`defineSeed` refuses one that is not. Same values and meaning as an import
7979
mapping entry's `applyOn` (objectstack-api).
8080

8181
```typescript
8282
defineSeed(Invoice, {
8383
externalId: 'number',
84+
mode: 'upsert',
8485
columns: { status: { applyOn: 'create' } }, // the payment job owns it after the first seed
8586
records: [{ number: 'INV-001', status: 'draft', amount: 1200 }],
8687
});
@@ -147,17 +148,16 @@ Stdlib in seed context: `now()`, `today()`, `daysFromNow(n)`, `daysAgo(n)`,
147148
`isBlank(v)`, `coalesce(v, fallback)`. Scope: `os.user`, `os.org`, `os.env`.
148149
See **objectstack-formula** for the full contract.
149150

150-
**Determinism gate:** two consecutive `os build` runs with no source
151-
changes must produce byte-identical `dist/objectstack.json`. CEL + pinned
152-
`now` is what guarantees that — using `Date.now()` will fail CI.
151+
**Determinism gate:** two `os build` runs with no source change must
152+
produce byte-identical `dist/objectstack.json`.
153153

154154
### Seed best practices
155155

156156
| Practice | Why |
157157
|:---------|:----|
158158
| Always use `defineSeed()`, never `SeedSchema.parse()` | Lose compile-time field checking otherwise |
159159
| Prefer natural keys (`code` / `email` / `slug`) | Portable across environments |
160-
| Default to `upsert` | Idempotent re-runs |
160+
| Leave `mode` unset; `upsert` only for reference data | Replays keep customer edits |
161161
| Scope demo data with `env: ['dev','test']` | Keep noise out of prod |
162162
| Order seeds parent → child in the exported array | References resolve at load time |
163-
| Use `replace` only on cache/lookup tables, with comments | Data-loss footgun |
163+
| `replace` only on cache tables the caller clears | It never deletes: duplicates otherwise |

0 commit comments

Comments
 (0)