System Context (isSystem)

ExecutionContext.isSystem is the platform's one elevation flag. Setting it on a write or read means "this operation is the engine acting on its own behalf" — the seed loader replaying package fixtures, a plugin's boot reconciler, a service self-write, a migration.

This page is the authority for what that flag actually does. It exists because the flag is not one concept: it is a single boolean read at 80 distinct sites across 18 packages, and knowing three of those behaviours gives no hint that the other seventy-seven exist. Every documented app-side bug traced to isSystem had the same shape — the metadata was complete and correct, and the gap was observable only by querying the resulting rows.

Which isSystem this page is about

Four unrelated declarations share the identifier. This page documents only the first. The others are ordinary metadata fields on a stored document and have nothing to do with elevation.

The collision is a genuine hazard rather than a naming nit: Object.isSystem changes an object's default sharing, and ExecutionContext.isSystem changes whether sharing grants are materialised — so a search for "isSystem sharing" returns both, and they are unrelated decisions.

A fifth, closely-spelled family — isSystemObjectName() / isSystemObject() in packages/runtime/src/action-execution.ts:53, packages/mcp/src/mcp-http-tools.ts:178 — keys on the sys_ name prefix, not on any flag.

How the flag is set

isSystem is server-constructed and never client-supplied. Inbound HTTP cannot set it (packages/rest/src/rest-server.ts:2079, :2096), and neither can an action body (packages/runtime/src/domains/actions.ts:122). It is written by internal callers only, as an option on the engine call:

await engine.insert('crm_account', row, { context: { isSystem: true } });

Its parse-time default is false (execution-context.zod.ts:233), so an absent context is never elevated.

The table

Grouped by lane. Every row cites the site that reads the flag. "What you lose" is the part that costs app-side bugs — it is the protection or the side effect that silently does not happen.

1. Authorization and scoping

2. Write pipeline and data integrity

3. Sharing (plugin-sharing)

The largest single consumer — 19 of the 80 sites.

4. Approvals, reports, attachments, comments, knowledge

5. Actions, metadata plane, provenance

What isSystem does not do

Just as costly as the list above. Each of these is a separate switch, and assuming isSystem covers it is a documented source of bugs.

Known rough edges

Recorded rather than smoothed over, because a reader who hits one of these should recognise it instead of re-deriving it.

1. The owner_id gap has two independent compensations and no shared mechanism. Row 2 is a real gap; the platform repairs it twice, in unrelated places — inline for automation flow writes (runtime-identity.ts:279, whose own comment states the reason: "the security middleware that stamps it short-circuits on isSystem — so the writer fills it here"), and as a boot-time sweep for seeded rows (plugin-security/src/claim-seed-ownership.ts). Any third system write path gets neither. If you add one, stamp ownership yourself.

2. Sharing materialisation is skipped silently. Row 22 produces "configured but inert": nine installed sharing rules, matching records, correct positions — and sys_record_share empty, with nothing logged. The boot backfill does eventually fix it, so the behaviour is not wrong; it is undiscoverable. An INFO line for exactly this case is queued as #6783 and is not shipped at the time of writing — do not read this row as already observable.

3. Strict write observability is inert under elevation. Row 17: a caller that asked to be told loudly about dropped fields is told nothing, because nothing was dropped. The two facts are indistinguishable from the outside.

4. revoke() skips its own conflict guard. Row 26 is correct for the rule evaluator and surprising for anything else: a system caller can delete a rule-materialised grant that the next reconcile silently restores.

5. applySystemFields does not read this flag. It is named as if it did. packages/objectql/src/registry.ts:307 is schema-side column provisioning — which columns an object carries — and consumes ExecutionContext.isSystem zero times. The write-time ownership behaviour people attribute to it is row 2, in plugin-security.

Decision on record: the flag is deliberately not being split

Maintainer ruling, #4707, 2026-08-06. Recorded here at the ruling's own request, so the proposal stops being re-opened.

Ownership injection, readonly bypass and sharing materialisation are independent decisions, and a seed loader plausibly wants the first two but not the third. The concept is nevertheless staying as one boolean:

• Shipped semantics. isSystem is a published contract with 80 read sites in 18 packages. Splitting it is a breaking contract change across all of them.
• No business pull. No app has asked for the combinations a split would enable; the observed need was to understand the flag, which is what this page serves.
• Combinatorics are worse for AI authors, not better. Three independent switches are eight states, most of them untested and several of them incoherent (grant materialisation without ownership). One flag plus this table is judged more mistake-proof at authoring time than a surface where a wrong combination is expressible and silently valid.

The trade-off accepted with that ruling is that elevation stays coarse: you cannot ask for the ownership behaviour without also taking the sharing behaviour. Where a narrower need exists, the platform answers it with a separate, explicit option next to isSystem — skipTriggers, preserveAudit, skipStateMachine, runAs — rather than by subdividing the flag. That is the pattern to follow for any new narrow exemption.

Maintaining this table

The table's value is exhaustiveness, so it is built by census, not by recall. To re-verify after a change:

grep -rn "isSystem" --include="*.ts" --include="*.tsx" packages examples \
  | grep -v node_modules | grep -v "/dist/"

Classify each hit into: a consumer of ExecutionContext.isSystem (a table row), a producer (isSystem: true on a call — not a behaviour), one of the three unrelated metadata fields, a sys_-prefix name helper, or a declaration. As of this page's census on main: 1179 total occurrences — 588 in tests, 591 in sources; of the source occurrences, 16 declarations, 240 producers and 121 consumers. Of the 121 consumers, 80 are behaviour-bearing reads of the elevation flag (the rows above), 12 read one of the unrelated metadata isSystem fields, 11 are sys_-prefix name helpers, 5 only propagate the flag onward, and 13 are generated i18n, form declarations or schema prose.

A new read of ExecutionContext.isSystem belongs in this table in the same PR that introduces it.

Related

• Authorization Architecture — the six-gate enforcement chain this flag short-circuits
• Security & Access Control — the readonly write strip and its exemptions
• State Machine — skipStateMachine, preserveAudit, treatAsHistorical
• Sharing Rules — what row 22 is skipping