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 108 distinct sites across 20 packages, and knowing three of those behaviours gives no hint that the other hundred-and-four 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#isSystemObjectName, packages/mcp/src/mcp-http-tools.ts#isSystemObject — 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#enforceAuth), and neither can an action body (packages/runtime/src/domains/actions.ts#handleActionsRequest). 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 (packages/spec/src/kernel/execution-context.zod.ts#isSystem), 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 — 17 of the 108 sites.

4. Approvals, reports, attachments, comments, knowledge

5. Actions, metadata plane, provenance, the organization wall

6. Reads that only carry the flag onward

Not behaviours: these four sites read the flag solely to copy it into another context or envelope. They are listed because the census counts them, and because a reader tracing where elevation travels needs them.

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 (packages/services/service-automation/src/runtime-identity.ts#stampSystemInsertOwner, 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 (packages/plugins/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 no longer skipped — the rough edge is closed, and it is recorded here rather than deleted. This entry used to describe "configured but inert": nine installed sharing rules, matching records, correct positions — and sys_record_share empty, repaired only by a re-evaluation or a restart. The reading that made it a rough edge rather than a defect was that the boot backfill eventually fixes it, so the behaviour was correct and merely undiscoverable; #6783 shipped an INFO notice on that reasoning.

   That reading did not survive contact with a runtime write. An approval node's write-back is a system write — lockRecord: true means only a platform write can land while the record is locked — and it happens long after boot, so no backfill was coming: a manager approved a request and the teammate who depended on the criteria rule status == "approved" could not see it at all. The maintainer ruled on 2026-08-31 (#13533) that the skip was a bug, because a sharing rule's declared semantics is a published promise and isSystem names the operator, never a consequence that need not happen. Both materialisation skips and the notice that announced them are gone; row 31 is now the afterDelete skip alone, which survives on the separate ground that another subscriber delivers that payload.

   ⚠️ The observability half of that reading is worth keeping in mind independently: the only signal a builder ever had was one INFO line, and nothing in the docs or the tests said "after approval, when does the team see it?". A compensating path that exists but that nobody can be expected to know about is not a compensating path.

3. Strict write observability is inert under elevation. Row 22: 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 35 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#applySystemFields 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 108 read sites in 20 packages. Splitting it is a breaking contract change across all of them. (The ruling was taken when the census read 80 sites in 18 packages; the count has grown, which strengthens rather than weakens the argument.)
• 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 — and the census is a committed instrument rather than someone's afternoon:

node scripts/isystem-census.mjs          # the summary below
node scripts/isystem-census.mjs --json   # every site, its kind and its package

Every number below marked ✅, plus the four sentences elsewhere on this page that restate the same figures (the opening headline, the plugin-sharing share, the #4707 ruling quote), is generated, never hand-maintained. pnpm gen:system-context-census (node scripts/check-system-context-census.mjs --fix) re-derives the census and rewrites every declared count that has drifted from it — the exact computation the check below already runs, applied as a write instead of a comparison. ⛔ Never hand-retype one of these digits. Two branches each independently — and correctly, for their own tree — bumping the same sentence to the same number is exactly how this page once went silently wrong: the edits are textually identical, git merges them clean with no conflict, and the merged total is neither side's number (#16919). Run the generator instead, against the tree you actually want counted, and it fails loudly rather than writing a partial page if a sentence no longer parses. --fix still cannot add or drop a row — a site that arrived or vanished is a human's editorial call, same as always — it only keeps the aggregate counts in lockstep with whatever rows exist.

⛔ Not a grep. A text scan is where a census starts and it cannot be where one ends: it returns prose inside comments and strings, the three unrelated metadata fields, and the isSystemObject / isSystemObjectName / isSystemLedgerObject name helpers. Worse, it loses real sites — a regex pass over this same corpus silently dropped 6 reads in packages/plugins/plugin-reports/src/report-service.ts to a quoting desync and 11 more to (ctx?.session as any)?.isSystem casts. So the census walks the TypeScript AST and classifies each appearance of the identifier by where the parser puts it: a read (a table row here), a declaration, an object-literal or type key (a producer, not a behaviour), or something else.

Corpus: tracked .ts / .tsx / .mts / .cts under packages/ and examples/, excluding dist/. A file counts as a test when its path carries .test. / .spec. or a tests/ / __tests__/ / qa/ segment. Every number below was produced by that run. The CI column says which of them a check still holds equal to the census on every pull request:

The six rows marked — are a dated decomposition, not a live claim: they were measured on 2026-08-29 at ca1965f2b5 and CI does not re-derive them. They count raw text over the whole corpus — every line, identifier appearance, object-literal key and prose mention of the string isSystem under packages/ and examples/, tests included — which is a different population from the one this page certifies, and it churns for reasons that have nothing to do with elevation: a test that mentions the flag, a seed object carrying isSystem: true, a comment. Enforcing them made this page's own pull request un-landable, because CI scores a merge with main and the merge queue re-derives that merge against a newer main on every attempt: three unrelated merges moved these six numbers eight times in one night, while the census population — 109 sites in 20 packages across 45 files — did not move once. They are kept because they are how you get from a raw grep to 109, which is the whole argument of this section; they are unenforced because a count of lines in test files certifies nothing. ⛔ Do not re-add them to DECLARED_COUNTS — a self-test case in the gate refuses that by name. Re-measure them with node scripts/isystem-census.mjs when you want them current, and move the date.

What the enforced declarations row counts. Not the four field declarations above — those are four distinct fields that happen to share a name, and only the first is elevation. This row counts every position where the parser puts the identifier in a declaring slot: those four, plus the structural type literals that restate ExecutionContext.isSystem's shape inline rather than importing it ({ isSystem: true; tenantId?: string }, context?: { isSystem?: boolean }, and the get isSystem() accessor on the engine's context wrapper). A restatement is a producer's declaration of the shape it will build, never a read, so a new one moves this count and moves nothing else on this page — the census's read population, the anchored rows above, and the packages and files totals all stay where they are. The most recent arrival is the scoped seed context threaded into the org-admin permission-set lookup in packages/plugins/plugin-security/src/auto-org-admin-grant.ts, so that read resolves against the granting organization's own catalog row rather than an organization-less one (#11670). ⛔ Cited as a FILE deliberately, with no #symbol: this page's symbol anchors name the enclosing declaration of an elevation read, and a declaration of the shape is not one — so there is no symbol here for a row to name, and inventing one would put a name on the page that no rename could ever red.

Counting by hand is what made the previous edition wrong in two independent ways, so both are worth naming. Its headline said "80 distinct sites across 18 packages" while its own tables anchored 77 — the number never matched the page it described. And a grep -c for anchor-shaped text over the previous edition answered 64, because it counted lines carrying an anchor, not anchors: that page's real anchor population was 111 once continuation anchors and range ends are counted. Decompose a text count before comparing it to anything.

What CI holds, and why it is the population and not just the anchors

A line-number anchor rots on every unrelated edit to the same file, silently: re-resolving all 111 anchors of the edition before last found 101 pointing at a line that no longer held what the row named, while only 10 were still correct — and 41 of them named a basename that matches two files, so they could not be placed without reading the row's Package column. Neither failure is reachable from this edition: it carries no line numbers at all, and it spells every path in full from the repository root. Each anchor is packages/…/file.ts#symbol, resolved by the shared symbol-anchor resolver (scripts/symbol-anchors.mjs) against that file's own declaration sites — the same resolver, and the same registration shape, that holds docs/adr/**. Renaming a symbol is now a loud red instead of a silent misdirection.

⚠️ The precision that costs, priced here rather than buried. A symbol anchor cannot say WHICH read inside a function it means, and 9 of the 45 anchored files hold more than one read inside a single symbol. So the population check runs per file at symbol granularity: every file the census finds a read in must be anchored, and the set of symbols this page cites into that file must equal the set of symbols the census finds reads in. Two consequences, and the second one is a hole:

• Delete a whole symbol and this page reds — the anchor stops resolving and the symbol set stops matching, in the same run.
• Delete one of several reads inside a symbol that keeps at least one, and the symbol set does not move, so it may not red. The previous edition's line numbers did close this one: both reads lost in the last drift lived inside callerContext() helpers that still exist under the same names. Closing it again means a span-aware resolver and per-read disambiguation in those nine files; that is its own card, and it is deliberately not folded in here.

Resolving anchors is nevertheless the second check, not the first. ⭐ A gate that only checks what the page already says can never find what the page failed to say. Re-resolving every anchor of the edition before last would have passed while it was missing 32 sites and its headline was 29 too low. So the load-bearing direction runs census → page: every elevation read in the code must be anchored here, and a site that vanishes from the code takes the census total with it — the site, package and file counts above are census-derived — which is what makes a row describing a protection that no longer exists fail.

Four checks run, in scripts/check-system-context-census.mjs:

A new read of ExecutionContext.isSystem belongs in this table in the same PR that introduces it — CI will say so if it is not.

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 31 is skipping