feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 6 commits into from
Sep 2, 2026
+703 −32
Merged

feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3) #14354

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b8a1d86
wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness
claude Sep 2, 2026
d4ecf12
test: pairing gate for ADR-0130 D1+D3
claude Sep 2, 2026
249a781
chore: error-code vocabulary row + changeset for ADR-0130 D1+D3
claude Sep 2, 2026
12a9b4b
chore: census re-anchor + test type fix
claude Sep 2, 2026
f539d35
Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…
claude Sep 2, 2026
bf980cc
merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…
claude Sep 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .changeset/adr-0130-install-gate-co-ownership.md
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
*"are these co-owners within one artifact?"*. Everything inside one release
artifact is built, versioned, downloaded and installed as one atomic act by
one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
`RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
from **different** artifacts sharing a namespace are still refused with the
existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
Namespace exclusivity has been proxying for *"no two packages define the same
object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
now refuses, **at install time and ahead of any DDL**, a package whose object
name is already owned by a co-owner from the same artifact —
`ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
object. Without it, two co-owning packages defining `crm_account` would reach
the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).
22 changes: 11 additions & 11 deletions content/docs/permissions/system-context.mdx
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
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:459` is **schema-side column
`packages/objectql/src/registry.ts:464` 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`.
Expand Down
30 changes: 22 additions & 8 deletions packages/objectql/src/artifact-packages.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
return err;
}

/**
* The id one artifact package is keyed by.
*
* `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
* on `manifest.id || manifest.name`, so an empty-string `id` falls back to
* `name` there. Every seam that has to name a package — this module's ordering
* map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
* through THIS function, so none of them can order or admit a package under a
* key the registry never stores it by.
*
* @returns The package id, or `undefined` when the manifest carries neither a
* usable `id` nor a usable `name`.
*/
export function artifactPackageId(manifest: unknown): string | undefined {
const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
|| (manifest as { name?: unknown } | null | undefined)?.name;
return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
/** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
// header: the schema is a gate here, and a parsed clone carries defaults
// and drops undeclared keys the singular-`manifest` branch keeps.
const manifest = (entry as { manifest?: unknown }).manifest;
// `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
// package on `manifest.id || manifest.name`, so an empty-string `id` falls
// back to `name` there — this seam must agree on what the id IS, or the
// sorter would order a package under a key the registry never stores it by.
const id = (manifest as { id?: unknown; name?: unknown }).id
|| (manifest as { name?: unknown }).name;

if (typeof id !== 'string' || id === '') {
const id = artifactPackageId(manifest);

if (id === undefined) {
throw refuse(
'INVALID_ARTIFACT_PACKAGE_ENTRY',
`Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down
13 changes: 9 additions & 4 deletions packages/objectql/src/engine.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
* Key: Package ≠ App. The manifest is the package. The apps[] array inside
* the manifest contains UI navigation definitions (AppSchema).
*/
registerApp(manifest: any) {
registerApp(manifest: any, scope?: ArtifactInstallScope) {
const id = manifest.id || manifest.name;
const namespace = manifest.namespace as string | undefined;
this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
}
}

// 1. Register the Package (manifest + lifecycle state)
this._registry.installPackage(manifest);
// 1. Register the Package (manifest + lifecycle state).
// [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
// the load path that read the artifact. It is what lets the install gate
// tell a CO-OWNER (another package from this same artifact) from a
// stranger — the question D1 corrected the gate to ask. Absent for every
// single-package caller, where the gate behaves exactly as before (D7).
this._registry.installPackage(manifest, undefined, scope);
this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

// 2. Register owned objects
Expand Down
20 changes: 18 additions & 2 deletions packages/objectql/src/plugin.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
return Promise.resolve();
}

// [ADR-0130 D1] The artifact's own package list, handed to every
// install in it. This is the whole of how the install gate learns
// "same artifact": co-ownership is proven by joint delivery, and this
// load path is the only place that holds the delivery. ⛔ No owner field
// on the manifest (D8) and nothing persisted — the claim cannot outlive,
// or drift from, the artifact that IS the claim.
//
// A single-`manifest` artifact yields a one-element list whose only
// member is the installing package itself, which the gate excludes
// anyway: that path stays bit-identical (D7).
const scope = {
packageIds: ordered
.map((m) => artifactPackageId(m))
.filter((id): id is string => id !== undefined),
};

for (const manifest of ordered) {
ql.registerApp(manifest);
ql.registerApp(manifest, scope);
ctx.logger.debug('Manifest registered via manifest service', {
id: manifest.id || manifest.name
});
Expand Down
Loading
Loading
, 'i'); if (__m === '*' || __re.test(location.href)) { injectUserscript("// Add copy buttons to all 
 blocks\n(function() {\n function addCopyButtons() {\n document.querySelectorAll('pre code').forEach(function(codeBlock) {\n if (codeBlock.parentElement.hasAttribute('data-copy-added')) return;\n codeBlock.parentElement.setAttribute('data-copy-added', 'true');\n \n var btn = document.createElement('button');\n btn.textContent = 'Copy';\n btn.style.cssText = 'position:absolute;top:4px;right:4px;padding:2px 8px;font-size:11px;background:#4ecdc4;border:none;border-radius:4px;color:#1a1a2e;cursor:pointer;opacity:0.7;transition:opacity 0.2s;';\n btn.onmouseover = function() { this.style.opacity = '1'; };\n btn.onmouseout = function() { this.style.opacity = '0.7'; };\n btn.onclick = function() {\n navigator.clipboard.writeText(codeBlock.textContent).then(function() {\n btn.textContent = 'Copied!';\n setTimeout(function() { btn.textContent = 'Copy'; }, 1500);\n });\n };\n codeBlock.parentElement.style.position = 'relative';\n codeBlock.parentElement.appendChild(btn);\n });\n }\n \n addCopyButtons();\n \n // Re-run on dynamic content\n var observer = new MutationObserver(addCopyButtons);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Add Copy Buttons to Code Blocks");
}
} catch(__e) { console.warn('[Userscript:Add Copy Buttons to Code Blocks]', __e); }
})();
(function(){
try {
var __m = "github.com";
var __re = new RegExp('^' + "github\\.com" + '

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Force GitHub README to respect dark mode\n(function() {\n var style = document.createElement('style');\n style.textContent = '\n .markdown-body {\n color-scheme: dark light;\n }\n .markdown-body pre { background: #161b22 !important; }\n .markdown-body code { background: rgba(110, 118, 129, 0.4) !important; }\n .markdown-body table th, .markdown-body table td { border-color: #30363d !important; }\n .markdown-body img { background: #0d1117; }\n .markdown-body blockquote { border-left-color: #8b949e; }\n .markdown-body hr { border-color: #30363d; }\n ';\n document.head.appendChild(style);\n})();", "GitHub Dark Mode README Fix");
}
} catch(__e) { console.warn('[Userscript:GitHub Dark Mode README Fix]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Highlight search terms from Google/DuckDuckGo/Bing referrer\n(function() {\n var ref = document.referrer;\n var terms = [];\n \n if (ref.includes('google.com') || ref.includes('duckduckgo.com') || ref.includes('bing.com')) {\n var url = new URL(ref);\n var q = url.searchParams.get('q') || url.searchParams.get('p');\n if (q) {\n terms = q.split(/\\s+/).filter(function(t) { return t.length > 2; });\n }\n }\n \n if (terms.length === 0) return;\n \n var style = document.createElement('style');\n style.textContent = '.userscript-highlight { background: #fbbf24; color: #1a1a2e; padding: 1px 3px; border-radius: 2px; }';\n document.head.appendChild(style);\n \n function highlight(node) {\n if (node.nodeType === 3) { // text node\n var text = node.textContent;\n var found = false;\n terms.forEach(function(term) {\n var regex = new RegExp('(' + term.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\') + ')', 'gi');\n if (regex.test(text)) {\n found = true;\n var frag = document.createDocumentFragment();\n var parts = text.split(regex);\n parts.forEach(function(part, i) {\n if (i % 2 === 0) {\n frag.appendChild(document.createTextNode(part));\n } else {\n var span = document.createElement('span');\n span.className = 'userscript-highlight';\n span.textContent = part;\n frag.appendChild(span);\n }\n });\n node.parentNode.replaceChild(frag, node);\n }\n });\n } else if (node.nodeType === 1 && node.childNodes) { // element\n var skipTags = ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SELECT'];\n if (!skipTags.includes(node.tagName)) {\n Array.from(node.childNodes).forEach(highlight);\n }\n }\n }\n \n highlight(document.body);\n \n // Re-highlight on dynamic content\n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1 || node.nodeType === 3) highlight(node);\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Highlight Search Terms");
}
} catch(__e) { console.warn('[Userscript:Highlight Search Terms]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Strip utm_, fbclid, gclid, etc. from all links on page\n(function() {\n var trackingParams = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content',\n 'fbclid', 'gclid', 'dclid', 'msclkid', 'yclid',\n 'ref', 'ref_src', 'source', 'medium', 'campaign'];\n \n function cleanUrl(url) {\n try {\n var u = new URL(url, window.location.origin);\n var changed = false;\n trackingParams.forEach(function(p) {\n if (u.searchParams.has(p)) {\n u.searchParams.delete(p);\n changed = true;\n }\n });\n return changed ? u.toString() : url;\n } catch (e) {\n return url;\n }\n }\n \n function cleanLinks() {\n document.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n \n cleanLinks();\n \n var observer = new MutationObserver(function(mutations) {\n mutations.forEach(function(m) {\n m.addedNodes.forEach(function(node) {\n if (node.nodeType === 1) {\n if (node.tagName === 'A') cleanLinks();\n node.querySelectorAll('a[href]').forEach(function(a) {\n var clean = cleanUrl(a.href);\n if (clean !== a.href) a.href = clean;\n });\n }\n });\n });\n });\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "Remove Tracking Parameters from Links");
}
} catch(__e) { console.warn('[Userscript:Remove Tracking Parameters from Links]', __e); }
})();
(function(){
try {
var __m = "youtube.com";
var __re = new RegExp('^' + "youtube\\.com" + '

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Auto-enable theater mode on YouTube\n(function() {\n function tryTheater() {\n var btn = document.querySelector('button[aria-label=\"Theater mode\"], ytd-player #player button[title=\"Theater mode\"]');\n if (btn && !btn.classList.contains('activated')) {\n btn.click();\n }\n }\n \n // Try immediately\n tryTheater();\n \n // Try after navigation (SPA)\n var lastUrl = location.href;\n setInterval(function() {\n if (location.href !== lastUrl) {\n lastUrl = location.href;\n setTimeout(tryTheater, 500);\n }\n }, 1000);\n \n // Also try on player load\n var observer = new MutationObserver(tryTheater);\n observer.observe(document.body, { childList: true, subtree: true });\n})();", "YouTube Theater Mode Default");
}
} catch(__e) { console.warn('[Userscript:YouTube Theater Mode Default]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Remove or un-stick sticky/fixed headers that block content\n(function() {\n function unstick() {\n document.querySelectorAll('header, nav, [role=\"banner\"], .header, .navbar, .sticky, .fixed-top, [style*=\"position: fixed\"], [style*=\"position:sticky\"]').forEach(function(el) {\n if (el.style.position === 'fixed' || el.style.position === 'sticky' || \n getComputedStyle(el).position === 'fixed' || getComputedStyle(el).position === 'sticky') {\n el.style.position = 'static';\n el.style.top = 'auto';\n el.style.zIndex = 'auto';\n }\n });\n }\n \n unstick();\n \n var observer = new MutationObserver(unstick);\n observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['style', 'class'] });\n})();", "Kill Sticky Headers");
}
} catch(__e) { console.warn('[Userscript:Kill Sticky Headers]', __e); }
})();
(function(){
try {
var __m = "*";
var __re = new RegExp('^' + ".*" + '

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading

, 'i');
if (__m === '*' || __re.test(location.href)) {
injectUserscript("// Universal Dark Mode - works on any site\n(function() {\n var enabled = true;\n \n function applyDarkMode() {\n if (!enabled) return;\n \n // Create style element if it doesn't exist\n var style = document.getElementById('universal-dark-mode-style');\n if (!style) {\n style = document.createElement('style');\n style.id = 'universal-dark-mode-style';\n document.head.appendChild(style);\n }\n \n // Dark mode CSS - inverts colors but preserves images/video\n style.textContent = '\n /* Invert everything except media */\n html {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #1a1a2e !important;\n }\n \n /* Restore images, videos, iframes, canvas */\n img, video, iframe, canvas, svg, picture, [style*=\"background-image\"] {\n filter: invert(1) hue-rotate(180deg) !important;\n }\n \n /* Preserve specific elements that should not be inverted */\n .no-dark-mode, .no-dark-mode *,\n [data-theme=\"light\"], [data-theme=\"light\"],\n .ace_editor, .ace_editor *,\n .CodeMirror, .CodeMirror *,\n .monaco-editor, .monaco-editor *,\n .markdown-body pre, .markdown-body pre *,\n .highlight, .highlight *,\n pre code, pre code * {\n filter: none !important;\n }\n \n /* Fix common UI elements */\n .modal, .popup, .dropdown-menu, .tooltip, .popover {\n filter: invert(1) hue-rotate(180deg) !important;\n background: #2d2d44 !important;\n border-color: #444 !important;\n }\n \n /* Scrollbars */\n ::-webkit-scrollbar { background: #1a1a2e !important; }\n ::-webkit-scrollbar-thumb { background: #444 !important; }\n ::-webkit-scrollbar-thumb:hover { background: #555 !important; }\n \n /* Selection */\n ::selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ::-moz-selection { background: #4ecdc4 !important; color: #1a1a2e !important; }\n ';\n }\n \n function removeDarkMode() {\n var style = document.getElementById('universal-dark-mode-style');\n if (style) style.remove();\n }\n \n // Toggle with Alt+Shift+D\n document.addEventListener('keydown', function(e) {\n if (e.altKey && e.shiftKey && e.key === 'D') {\n e.preventDefault();\n enabled = !enabled;\n if (enabled) {\n applyDarkMode();\n console.log('[Universal Dark Mode] Enabled');\n } else {\n removeDarkMode();\n console.log('[Universal Dark Mode] Disabled');\n }\n }\n });\n \n // Apply on load\n applyDarkMode();\n \n // Re-apply on dynamic content\n var observer = new MutationObserver(function(mutations) {\n if (enabled && !document.getElementById('universal-dark-mode-style')) {\n applyDarkMode();\n }\n });\n observer.observe(document.head, { childList: true });\n \n console.log('[Universal Dark Mode] Loaded - Press Alt+Shift+D to toggle');\n})();", "Universal Dark Mode");
}
} catch(__e) { console.warn('[Userscript:Universal Dark Mode]', __e); }
})();
})();

Skip to content
feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)#14354

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

 Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and
privacy statement. We’ll occasionally send you account related emails.

Already on GitHub?
Sign in
to your account

 Merged

hotlong
merged 6 commits into

from

Sep 2, 2026

+703

−32

 Merged


feat(objectql): admit same-artifact co-owners at the install gate, and refuse two of them defining one object name (ADR-0130 D1+D3)
#14354
Show file tree
Hide file tree
 Changes from all commits
Commits

Show all changes


6 commits


Select commit
Hold shift + click to select a range
b8a1d86

wip: ADR-0130 D1+D3 install gate co-ownership + object-name uniqueness


claude Sep 2, 2026
d4ecf12

test: pairing gate for ADR-0130 D1+D3


claude Sep 2, 2026
249a781

chore: error-code vocabulary row + changeset for ADR-0130 D1+D3


claude Sep 2, 2026
12a9b4b

chore: census re-anchor + test type fix


claude Sep 2, 2026
f539d35

Merge remote-tracking branch 'origin/main' into claude/issue-14163-in…


claude Sep 2, 2026
bf980cc

merge: origin/main into ADR-0130 D1+D3 branch, census regenerated fro…


claude Sep 2, 2026

File filter

Filter by extension
Filter by extension
Conversations

Failed to load comments. 
Loading
Jump to

Jump to file


Failed to load files. 
Loading
 Diff view

 Diff view


47 changes: 47 additions & 0 deletions
.changeset/adr-0130-install-gate-co-ownership.md

View file


Open in desktop

Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
---
"@objectstack/objectql": minor
"@objectstack/runtime": patch
---

feat(objectql): admit same-artifact co-owners at the namespace gate, and refuse two of them defining one object name (#14163)

ADR-0130 **D1 + D3**, landed as the single change D3 specifies as a machine
constraint. Neither half may ship alone, in either order.

- **D1 — the gate's question is corrected.** `SchemaRegistry.installPackage`'s
 ADR-0048 namespace gate asked *"is this the same package id?"*; it now asks
 *"are these co-owners within one artifact?"*. Everything inside one release
 artifact is built, versioned, downloaded and installed as one atomic act by
 one publisher, and ADR-0130 D1 makes that joint delivery the ownership proof.
 `RESERVED_NAMESPACES` / `isShareableNamespace` are unchanged, and two packages
 from **different** artifacts sharing a namespace are still refused with the
 existing `NamespaceConflictError`.
- **D3 — the guarantee the gate was silently carrying is now checked directly.**
 Namespace exclusivity has been proxying for *"no two packages define the same
 object name"* (ADR-0048 §3.2 grounds it on exactly that). So `installPackage`
 now refuses, **at install time and ahead of any DDL**, a package whose object
 name is already owned by a co-owner from the same artifact —
 `ArtifactObjectNameConflictError`, an ADR-0112 envelope (`code:
 'DUPLICATE_ARTIFACT_OBJECT_NAME'`, `status: 422`) naming both packages and the
 object. Without it, two co-owning packages defining `crm_account` would reach
 the DB as a duplicate `CREATE TABLE` or — driver-dependent — one silently
 overwriting the other's table definition.

**How the gate learns "same artifact".** An optional third argument on
`installPackage` (`ArtifactInstallScope`, the artifact's own package-id list),
threaded from the ADR-0130 D4/D5 load path through `ObjectQL.registerApp`. ⛔ No
owner/publisher field on the manifest — ADR-0130 D8 defers that deliberately,
and nothing is persisted, so a co-ownership claim cannot outlive or drift from
the artifact that IS the claim.

**Not a compatibility break** (#14122 §6.2): the new refusal can only reject a
configuration that would have failed at the DB anyway, and it rejects it earlier
and more legibly. Every caller that installs one package —
`protocol.installPackage`, `POST /packages`, a bare `registerApp` — passes no
scope, so both halves are structurally no-ops there; a single-`manifest`
artifact passes a one-element scope whose only member is the installing package,
which the gate excludes anyway (D7's bit-identity pin covers it).

`@objectstack/runtime` carries the classification row for the new error code in
the dispatcher error-code vocabulary (verdict `boot-refusal`: the refusal cannot
be raised by either HTTP install site, which pass no artifact scope).

22 changes: 11 additions & 11 deletions
content/docs/permissions/system-context.mdx

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -109,18 +109,18 @@ that silently does not happen.

| # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
|:--|:---|:---|:---|:---|
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10981` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11149` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9777` |
| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:10986` |
| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11154` |
| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:9782` |
| 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9814`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5735` |
| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:9819`, `readonly-strict-errors.ts:66` |
| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5740` |
| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3604`, `:3614`, `:3641` |
| 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
| 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6433` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11742` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11671` |
| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6438` |
| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:11747` |
| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:11676` |

### 3. Sharing (`plugin-sharing`)

Expand DownExpand Up@@ -180,7 +180,7 @@ a reader tracing where elevation travels needs them.
| # | Site | Package | What it does |
|:--|:---|:---|:---|
| 62 | `objectql/src/engine.ts:3411` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
| 63 | `objectql/src/engine.ts:14091` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 63 | `objectql/src/engine.ts:14096` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
| 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
| 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |

Expand All@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
|:---|:---|:---|
| "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1909` (rationale at `:1819`–`1821`, #3760), `flow.zod.ts:685` |
| "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9760`–`9777` |
| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:9765`–`9782` |
| "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1516` (#3493 / #6640) |
| "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
| "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:286` |
Expand DownExpand Up@@ -235,7 +235,7 @@ should recognise it instead of re-deriving it.
 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:459` is **schema-side column
 `packages/objectql/src/registry.ts:464` 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`.
Expand Down

30 changes: 22 additions & 8 deletions
packages/objectql/src/artifact-packages.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -117,6 +117,25 @@ function refuse(code: string, message: string): ArtifactPackageError {
 return err;
}

/**
 * The id one artifact package is keyed by.
 *
 * `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed package
 * on `manifest.id || manifest.name`, so an empty-string `id` falls back to
 * `name` there. Every seam that has to name a package — this module's ordering
 * map, and the install gate's co-ownership set (ADR-0130 D1) — reads the id
 * through THIS function, so none of them can order or admit a package under a
 * key the registry never stores it by.
 *
 * @returns The package id, or `undefined` when the manifest carries neither a
 * usable `id` nor a usable `name`.
 */
export function artifactPackageId(manifest: unknown): string | undefined {
 const id = (manifest as { id?: unknown; name?: unknown } | null | undefined)?.id
 || (manifest as { name?: unknown } | null | undefined)?.name;
 return typeof id === 'string' && id !== '' ? id : undefined;
}

/** The ordering-relevant projection of one artifact package. */
interface ArtifactPackageNode extends OrderablePlugin {
 /** The caller's ORIGINAL manifest body — never a parsed clone. */
Expand DownExpand Up@@ -186,14 +205,9 @@ export function resolveArtifactPackageOrder(artifact: unknown): unknown[] {
 // header: the schema is a gate here, and a parsed clone carries defaults
 // and drops undeclared keys the singular-`manifest` branch keeps.
 const manifest = (entry as { manifest?: unknown }).manifest;
 // `||`, not `??`, on purpose: `ObjectQL.registerApp` keys the installed
 // package on `manifest.id || manifest.name`, so an empty-string `id` falls
 // back to `name` there — this seam must agree on what the id IS, or the
 // sorter would order a package under a key the registry never stores it by.
 const id = (manifest as { id?: unknown; name?: unknown }).id
 || (manifest as { name?: unknown }).name;

 if (typeof id !== 'string' || id === '') {
 const id = artifactPackageId(manifest);

 if (id === undefined) {
 throw refuse(
 'INVALID_ARTIFACT_PACKAGE_ENTRY',
 `Release artifact \`packages[${index}]\` carries a manifest with no usable `
Expand Down

13 changes: 9 additions & 4 deletions
packages/objectql/src/engine.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -169,7 +169,7 @@ import {
 SECRET_MASK,
} from './secret-fields.js';
import { pluralToSingular, ExternalWriteForbiddenError } from '@objectstack/spec/shared';
import { SchemaRegistry, computeFQN } from './registry.js';
import { SchemaRegistry, computeFQN, type ArtifactInstallScope } from './registry.js';
import { expandSearchToFilter } from './search-filter.js';
import { isSearchCompanionRequested, stripSearchCompanion } from './search-companion.js';
import { ExpressionEngine } from '@objectstack/formula';
Expand DownExpand Up@@ -4773,7 +4773,7 @@ export class ObjectQL implements IObjectQLEngine {
 * Key: Package ≠ App. The manifest is the package. The apps[] array inside
 * the manifest contains UI navigation definitions (AppSchema).
 */
 registerApp(manifest: any) {
 registerApp(manifest: any, scope?: ArtifactInstallScope) {
 const id = manifest.id || manifest.name;
 const namespace = manifest.namespace as string | undefined;
 this.invalidateSummaryIndex(); // new objects may add/change summary fields
Expand All@@ -4796,8 +4796,13 @@ export class ObjectQL implements IObjectQLEngine {
 }
 }

 // 1. Register the Package (manifest + lifecycle state)
 this._registry.installPackage(manifest);
 // 1. Register the Package (manifest + lifecycle state).
 // [ADR-0130 D1/D3] `scope` is the artifact's own package list, passed by
 // the load path that read the artifact. It is what lets the install gate
 // tell a CO-OWNER (another package from this same artifact) from a
 // stranger — the question D1 corrected the gate to ask. Absent for every
 // single-package caller, where the gate behaves exactly as before (D7).
 this._registry.installPackage(manifest, undefined, scope);
 this.logger.debug('Installed Package', { id: manifest.id, name: manifest.name, namespace });

 // 2. Register owned objects
Expand Down

20 changes: 18 additions & 2 deletions
packages/objectql/src/plugin.ts

View file


Open in desktop

Original file line numberDiff line numberDiff line change
Expand Up@@ -4,7 +4,7 @@ import { ObjectQL } from './engine.js';
import { assembleMetadataProtocol } from '@objectstack/metadata-protocol';
import type { MetadataAuthoringChannel } from '@objectstack/metadata-protocol';
import { Plugin, PluginContext } from '@objectstack/core';
import { resolveArtifactPackageOrder } from './artifact-packages.js';
import { resolveArtifactPackageOrder, artifactPackageId } from './artifact-packages.js';
import { applyConversionsToStoredItem } from '@objectstack/spec';
import { StorageNameMapping } from '@objectstack/spec/system';
import { LifecycleService } from './lifecycle/lifecycle-service.js';
Expand DownExpand Up@@ -433,8 +433,24 @@ export class ObjectQLPlugin implements Plugin {
 return Promise.resolve();
 }

 // [ADR-0130 D1] The artifact's own package list, handed to every
 // install in it. This is the whole of how the install gate learns
 // "same artifact": co-ownership is proven by joint delivery, and this
 // load path is the only place that holds the delivery. ⛔ No owner field
 // on the manifest (D8) and nothing persisted — the claim cannot outlive,
 // or drift from, the artifact that IS the claim.
 //
 // A single-`manifest` artifact yields a one-element list whose only
 // member is the installing package itself, which the gate excludes
 // anyway: that path stays bit-identical (D7).
 const scope = {
 packageIds: ordered
 .map((m) => artifactPackageId(m))
 .filter((id): id is string => id !== undefined),
 };

 for (const manifest of ordered) {
 ql.registerApp(manifest);
 ql.registerApp(manifest, scope);
 ctx.logger.debug('Manifest registered via manifest service', {
 id: manifest.id || manifest.name
 });
Expand Down
Loading
Loading