Declaring how long an object's data lives and how its space is
reclaimed (ADR-0057). Distinct from
lifecycle hooks (beforeInsert / afterUpdate …), which run logic on
writes.
Every object without a lifecycle block is immortal: rows are never
deleted, and on SQLite the file never shrinks. That's correct for business
records — and a guaranteed disk leak for anything append-only.
Rule: any append-only, high-write-rate object (event log, run history,
delivery outbox, ephemeral tokens) MUST declare a lifecycle block.
The platform LifecycleService sweeps declared policies hourly, deletes
expired rows under a system context, and reclaims driver space.
| Class | Contract | Typical use |
|---|---|---|
record |
Business truth — permanent; policies FORBIDDEN | accounts, orders, invoices |
audit |
Compliance ledger — retain → archive → delete | audit trails |
telemetry |
High-frequency log — rotation / short retention | activity streams, run history |
transient |
Ephemeral state — TTL auto-expire | receipts, codes, sessions |
event |
Bus messages — very short TTL (hours) | scheduled fan-out |
import { ObjectSchema, Field } from '@objectstack/spec/data';
// ✅ Telemetry stream: bounded by a rotation window
export const ApiCallLog = ObjectSchema.create({
name: 'api_call_log',
sharingModel: 'private',
lifecycle: {
class: 'telemetry',
retention: { maxAge: '14d' }, // reap past 14 days (created_at)
storage: { strategy: 'rotation', shards: 14, unit: 'day' },
},
fields: {
endpoint: Field.text({}),
status: Field.number({}),
},
});
// ✅ Ephemeral token: TTL on its own expiry field
export const ImportTicket = ObjectSchema.create({
name: 'import_ticket',
sharingModel: 'private',
lifecycle: {
class: 'transient',
ttl: { field: 'expires_at', expireAfter: '1d' }, // reap 1 day after expires_at
},
fields: {
expires_at: Field.datetime({}),
},
});
// ✅ Compliance ledger: hot window, then cold storage
export const ConsentLog = ObjectSchema.create({
name: 'consent_log',
sharingModel: 'private',
lifecycle: {
class: 'audit',
retention: { maxAge: '90d' },
archive: { after: '90d', to: 'archive', keep: '7y' },
},
fields: {
subject: Field.text({}),
},
});
// ✅ MIXED table: terminal history is telemetry, but paused rows are live
// workflow state — `onlyWhen` scopes the age sweep to the declared filter
export const AutomationRun = ObjectSchema.create({
name: 'sys_automation_run',
lifecycle: {
class: 'telemetry',
retention: {
maxAge: '30d',
onlyWhen: { status: { $in: ['completed', 'failed'] } },
},
},
fields: {
status: Field.select(['running', 'paused', 'completed', 'failed'], {}),
},
});Duration literals: <n> + h / d / w / y.
// ❌ Non-record class with no bounding policy — grows forever, exactly the bug
lifecycle: { class: 'telemetry' }
// ❌ archive.after must equal retention.maxAge
lifecycle: { class: 'audit', retention: { maxAge: '90d' }, archive: { after: '30d', to: 'archive' } }
// ❌ onlyWhen + rotation/archive — shard DROPs and the Archiver act on age
// alone and would destroy/move rows the filter protects
lifecycle: {
class: 'telemetry',
retention: { maxAge: '14d', onlyWhen: { status: 'done' } },
storage: { strategy: 'rotation', shards: 14, unit: 'day' },
}- Archive-then-delete is atomic-ish and safe by default: an object
declaring
archiveis never hot-deleted before the copy to the archive datasource succeeded. If no datasource is registered under thearchive.toname, rows are simply retained. - Rotation physically time-shards the table on SQLite (writes hit the current shard, reads go through a view under the object's name, expired shards are DROPped). Other dialects enforce the same window with an age-based reap.
- Separation: registering a datasource named
telemetrymoves everytelemetry/event/auditobject onto it — telemetry bloat can't touch the business DB.
seal makes an audit ledger tamper-evident (ADR-0154): an edit, insert or
delete outside the platform breaks its signed checkpoints. Ten minutes after each created_at
hour, @objectstack/plugin-audit signs its rows into a chained checkpoint
per organization (tenant_id; rows with none share a deployment chain); late
rows get a late checkpoint. Columns enter in clear, valueFields as salted
commitments.
import { ObjectSchema, Field } from '@objectstack/spec/data';
// ✅ The sealer needs declared `id` and `tenant_id`
export const PolicyChangeLog = ObjectSchema.create({
name: 'policy_change_log',
sharingModel: 'private',
lifecycle: { class: 'audit', retention: { maxAge: '1y' }, seal: { valueFields: ['new_value'] } },
fields: {
id: Field.text({}),
tenant_id: Field.lookup('sys_organization', {}), // stamped on insert
new_value: Field.textarea({}),
},
});// ❌ Refused at parse time: id / created_at order the leaves
seal: { valueFields: ['created_at'] }Also refused: seal off class audit, an undeclared valueFields name, and
beside seal any onlyWhen, a ttl not on created_at, or rotation
storage. Not sealed, reported at error hourly: no declared id or
tenant_id (the injected tenant column is organization_id); a password,
secret, formula, summary, image, file, avatar, video or audio
column; no cryptoProvider on AuditPlugin. Not built yet (ADR-0154): a
verifier, so a break is recorded but not reported; expiry (P4), so the sweeper
still deletes sealed rows, which then read as missing.
| Knob | Where | Effect |
|---|---|---|
enabled |
lifecycle settings namespace |
Runtime master switch |
retention_overrides |
settings, tenant-scoped | Per-object window overrides — a regulated tenant sets '2y' while dev keeps days |
quotas / quota_defaults |
settings | Row ceilings; breaches ALERT (never delete beyond declared policy) |
growth_alert_rows |
settings | Per-sweep growth spike alert |
OS_LIFECYCLE_DISABLED=1 |
env | Disables sweeping entirely |
A create/update hook calls ctx.notice('Sent to your manager for approval')
— a sandboxed body or the deprecated inline handler, no capability. The
answer carries it as notice; the console shows it on the save toast. Info
severity: an outcome, never a problem — distinct from validation
warnings. A record:alert banner is page metadata shown whenever the
record's state says so; the notice is for what this save started.
- One message per write, the last call wins; never stored.
- Insert/update dispatches only. A write nobody waits on (batch, seed, import, a nested write) sets nothing.
- Not a non-empty string ⇒ the write refuses; a refused write answers its error, no notice.
- A hook's message is untranslated.
- A flow a record create/update trigger starts sets it with a
save_noticenode (config.message,{{ }}renders); refused in any other flow, and after anapproval/wait. Its message translates underflows.<flow>.notices.<node_id>.messagein the saver's locale. Refused by name in asubflow/mapchild; after one whose child can pause, the flow is not armed (unboundCause: 'notice_after_suspending_subflow').