feat(devx,datasource,automation): gate undeclared workspace imports in published src (#10062) (#12942)

* wip(devx): seed the undeclared-workspace-import gate (#10062)

* feat(devx): gate undeclared workspace imports in published src (#10062)

* chore(changeset): declare the dependency-graph and export changes (#10062)

* feat(devx): declare the gate's watch hints so a dispatch brief can name it (#10062)

* docs(devx): state the type-only row's evidence as measured (#10062)

* fix(datasource): keep the guarded optional driver arms undeclared, ledger them instead (#10062)

* fix(devx): record the service-datasource driver-memory declaration's new field in the census ledger (#10062)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: Elon Musk

.changeset/declared-workspace-imports-gate.md

@@ -0,0 +1,59 @@
+---
+"@objectstack/metadata-core": minor
+"@objectstack/objectql": patch
+"@objectstack/service-automation": patch
+"@objectstack/service-datasource": patch
+---
+
+feat(devx,datasource,automation): published `src/**` may only import workspace packages it declares (#10062)
+
+A package's non-test `src/**` was free to import any workspace package,
+declared or not, and nothing checked it. The class was filed with one member
+and a mitigation — the import was type-only, so nothing reached the emitted
+JavaScript and rollup-plugin-dts inlined the declaration rather than naming an
+unresolvable module. It grew to four members with no signal, and one of them
+killed the mitigation: `service-automation/src/flow-precedence.ts` **value**
+imports from `@objectstack/objectql`, which it does not declare, and because
+the shared tsup config externalises only `dependencies`/`peerDependencies`, the
+bundler answered by inlining objectql's implementation into
+`service-automation/dist/index.js` — a second copy of another package's code,
+kept correct by build configuration alone.
+
+`pnpm check:undeclared-dep-imports` is the gate, and the per-member fixes here
+are decided one at a time rather than by a uniform policy — declaring makes a
+coupling real and installable, routing it away removes it, and the two are not
+interchangeable:
+
+* **`@objectstack/service-datasource`** now declares `@objectstack/driver-sql`
+  and `@objectstack/driver-memory` as **dependencies**. Both are loaded through
+  an *unguarded* `await import(...)` on the postgres, mysql, sqlite and memory
+  arms, so a consumer reaching one of those paths needed a package it was never
+  told to install, and would have met `ERR_MODULE_NOT_FOUND` rather than a
+  diagnosis. The three *guarded* driver arms — `@objectstack/driver-sqlite-wasm`,
+  `@objectstack/driver-mongodb`, `@objectstack/driver-turso` — are deliberately
+  left undeclared: each load sits in a `try`/`catch` that answers an absent
+  package with the fault, the consequence and the install command, and each
+  rides as an optional install. Declaring them would install them (turso drags
+  `@libsql/client`'s native bindings) and, measured on this branch, takes a live
+  assertion out of the tree: `default-datasource-driver-factory.test.ts` reaches
+  the missing-package arm with no stub precisely because the package does not
+  resolve from here.
+* **`@objectstack/metadata-core`** now owns the ADR-0029 D9.6 provenance pair,
+  `isCodeArtifactBody` and `isTenantAuthored`, sunk out of
+  `@objectstack/objectql`'s registry by the same criterion as the write-verb
+  dispatch predicates and the audit governance table beside them: a second layer
+  needs the answer and the reverse import would either close a cycle or make the
+  consumer depend on the whole data engine for one predicate. `objectql`
+  re-exports `isCodeArtifactBody` from its original path, so its public API is
+  unchanged; `service-automation` imports it from `metadata-core`, which it
+  already declared, and its bundle no longer carries a copy of objectql's code.
+
+Two members stay recorded rather than remediated, because the tree already
+carries the decision not to declare them together with its reason
+(`@objectstack/runtime` → `@objectstack/driver-turso`, whose bare `import()` is
+a host-replaceable default thunk under #6268; `@objectstack/rest` →
+`@objectstack/objectql`, whose absence must degrade to `501 NOT_IMPLEMENTED`
+rather than fail module load). Their ledger rows carry mechanical evidence and
+go red the moment that evidence stops holding — in particular, a `type-only`
+row reds on the day its import becomes a value import, which is exactly the
+transition nothing caught the first time.

.github/workflows/lint.yml

@@ -390,6 +390,27 @@ jobs:
           node scripts/check-comment-mask-adoption.mjs --self-test
           node scripts/check-comment-mask-adoption.mjs
 
+      # A package's published `src/**` may only import workspace packages its own
+      # manifest DECLARES (#10062). The class was filed with one member and a
+      # mitigation — "type-only, so nothing lands in the emitted JavaScript" —
+      # and grew to four with no signal, one of them a VALUE import whose
+      # implementation the bundler then INLINED into a second package's dist.
+      # Both halves of the mitigation are now ledger EVIDENCE instead of prose:
+      # a `type-only` row reds the moment its import stops being type-only.
+      # Node builtins plus the shared comment mask only — no node_modules, so a
+      # reviewer can run it in place. Its `--self-test` runs FIRST: the
+      # production run over a fixed tree is green by construction, so it cannot
+      # tell a working matcher from a dead one, and the specifier FLOOR is the
+      # other half (a dead matcher finds nothing, and nothing is what success
+      # looks like — so it refuses with exit 2 rather than passing).
+      # Invoked as `node` rather than through a `pnpm check:*` alias: see the
+      # GATE INVOCATION IDIOM note at the top of this file.
+      # Scans ~2k non-test src files across 78 workspace packages, no spawns; ~1s.
+      - name: Published src imports only declared workspace deps
+        run: |
+          node scripts/check-undeclared-dep-imports.mjs --self-test
+          node scripts/check-undeclared-dep-imports.mjs
+
       # The bash-3.2 floor, over every shell file the repo ships (#12221).
       # `/usr/bin/env bash` is bash 3.2.57 on macOS -- Apple ships no bash 4+,
       # for licensing reasons -- and THIS RUNNER IS BASH 5, where every construct

package.json

@@ -124,6 +124,7 @@
     "check:test-source-alias": "node scripts/check-test-source-alias.mjs --self-test && node scripts/check-test-source-alias.mjs",
     "check:refd-timer-probe": "node scripts/check-refd-timer-probe.mjs --self-test && node scripts/check-refd-timer-probe.mjs",
     "check:type-source-resolution": "node scripts/check-type-source-resolution.mjs --self-test && node scripts/check-type-source-resolution.mjs",
+    "check:undeclared-dep-imports": "node scripts/check-undeclared-dep-imports.mjs --self-test && node scripts/check-undeclared-dep-imports.mjs",
     "check:published-files": "node scripts/check-published-files.mjs --self-test && node scripts/check-published-files.mjs",
     "check:published-readme-exports": "node scripts/check-published-readme-exports.mjs --self-test && node scripts/check-published-readme-exports.mjs",
     "check:published-readme-links": "node scripts/check-published-readme-links.mjs --self-test && node scripts/check-published-readme-links.mjs",

packages/metadata-core/src/code-artifact-provenance.ts

@@ -0,0 +1,61 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * "Does a code package ship this name?" — the ADR-0029 D9.6 provenance test.
+ *
+ * [#10062] Sunk here from `@objectstack/objectql`'s registry by the same
+ * criterion as the write-verb dispatch predicates and the audit governance
+ * table above it in `index.ts`: a second layer needs the answer, and the
+ * reverse import would either close a cycle or make the consumer depend on the
+ * whole data engine for one predicate.
+ *
+ * The second layer is `@objectstack/service-automation`'s ADR-0048 flow
+ * precedence, which asks exactly this question to decide which contender for a
+ * flow name wins. It reached it by importing `@objectstack/objectql` directly —
+ * a package it does not declare — and because the shared tsup config
+ * externalises only `dependencies`/`peerDependencies`, the bundler INLINED
+ * objectql's implementation into `service-automation/dist/index.js`: a second
+ * copy of another package's code, kept correct by build configuration alone.
+ * `@objectstack/metadata-core` is the package both sides already declare and it
+ * depends on neither, so the answer now has one home and one implementation.
+ *
+ * `objectql` re-exports `isCodeArtifactBody` from `registry.ts`, so its public
+ * API is unchanged.
+ */
+
+/**
+ * Is this registered item a TENANT-authored overlay rather than a code-shipped
+ * artifact? (ADR-0010 `_provenance`: `'package'` for loader-introduced items,
+ * `'org'` for tenant-authored.)
+ *
+ * `_packageId !== 'sys_metadata'` alone cannot answer it. That sentinel marks
+ * one thing only — an overlay row bound to no package. A row that IS bound to
+ * one is keyed by its real package id on BOTH sides that register it: the save
+ * path (#4636 PR1) and the boot-time rehydration of `sys_metadata` (#4636 PR2).
+ * Either way the key is `app.<slug>`, which is exactly what every code-shipped
+ * item carries too, so the sentinel test cannot tell them apart. A tenant's own
+ * overlay came back from a kernel rebuild looking like a code
+ * artifact, and the protocol's overlay gate refused the next write to it with
+ * `not_overridable` — an app the user had just built through Studio/AI became
+ * permanently un-editable at the first kernel rebuild (cloud#970). Provenance is
+ * the axis that actually distinguishes the two, so ask it.
+ */
+export function isTenantAuthored(item: unknown): boolean {
+  return (item as { _provenance?: unknown } | null | undefined)?._provenance === 'org';
+}
+
+/**
+ * [ADR-0029 D9.6] Is this registered body a CODE-shipped artifact?
+ *
+ * The exact test `SchemaRegistry.getArtifactItem` has always applied, factored
+ * out so the object branch and the D9.8 hydration discriminator
+ * (`SchemaRegistry.getPackagedObjectOwner`) cannot drift into two different
+ * answers to one question — "does a code package ship this name?". Truthy
+ * `_packageId`, not the `'sys_metadata'` rehydration sentinel, and not tenant
+ * provenance.
+ */
+export function isCodeArtifactBody(item: unknown): boolean {
+  const it = item as { _packageId?: unknown } | null | undefined;
+  if (!it || !it._packageId || it._packageId === 'sys_metadata') return false;
+  return !isTenantAuthored(it);
+}

packages/metadata-core/src/index.ts

@@ -49,6 +49,17 @@ export * from './engine-findone-predicate.js';
 // reporting two.
 export * from './audit-field-governance.js';
 
+// [#10062] The ADR-0029 D9.6 provenance pair, sunk here from
+// `@objectstack/objectql`'s registry by the same criterion as everything above:
+// `@objectstack/service-automation` needs the same "does a code package ship
+// this name?" answer for ADR-0048 flow precedence, and was reaching it by
+// importing objectql — a package it does not declare, so the bundler inlined a
+// copy of objectql's implementation into service-automation's dist. Both sides
+// already declare THIS package, and it depends on neither. `objectql`
+// re-exports `isCodeArtifactBody` from `registry.ts`, so its public API is
+// unchanged.
+export * from './code-artifact-provenance.js';
+
 // [#6562] The served-document injection/strip pair over the injected-system-
 // column definition tables, sunk here by the same criterion and for the same
 // cycle as the governance table above. The DEFINITION tables themselves and the

packages/objectql/src/registry.ts

@@ -16,6 +16,15 @@ import {
   // from one place. Re-exported below under its original name.
   ITEM_KEY_DISCRIMINATORS,
   readDiscriminatorValue as discriminatorValue,
+  // [#10062] The ADR-0029 D9.6 provenance pair, sunk into metadata-core for the
+  // same reason as the table above: `@objectstack/service-automation`'s flow
+  // precedence asks the same question ("does a code package ship this name?")
+  // and reached it by importing this package, which it does not declare — so
+  // the bundler inlined a copy of this implementation into ITS dist. Both names
+  // keep their original spelling here, and `isCodeArtifactBody` is re-exported
+  // below, so this package's public API is unchanged.
+  isCodeArtifactBody,
+  isTenantAuthored,
 } from '@objectstack/metadata-core';
 // [#8460] `scalarOverridesPackagedBase` is the #8284 comparison, imported rather
 // than re-spelled: the object FOLD asks the same question one layer down (has
@@ -1144,42 +1153,13 @@ export class NamespaceConflictError extends Error {
   }
 }
 
-/**
- * Is this registered item a TENANT-authored overlay rather than a code-shipped
- * artifact? (ADR-0010 `_provenance`: `'package'` for loader-introduced items,
- * `'org'` for tenant-authored.)
- *
- * `_packageId !== 'sys_metadata'` alone cannot answer it. That sentinel marks
- * one thing only — an overlay row bound to no package. A row that IS bound to
- * one is keyed by its real package id on BOTH sides that register it: the save
- * path (#4636 PR1) and the boot-time rehydration of `sys_metadata` (#4636 PR2).
- * Either way the key is `app.<slug>`, which is exactly what every code-shipped
- * item carries too, so the sentinel test cannot tell them apart. A tenant's own
- * overlay came back from a kernel rebuild looking like a code
- * artifact, and the protocol's overlay gate refused the next write to it with
- * `not_overridable` — an app the user had just built through Studio/AI became
- * permanently un-editable at the first kernel rebuild (cloud#970). Provenance is
- * the axis that actually distinguishes the two, so ask it.
- */
-function isTenantAuthored(item: unknown): boolean {
-  return (item as { _provenance?: unknown } | null | undefined)?._provenance === 'org';
-}
-
-/**
- * [ADR-0029 D9.6] Is this registered body a CODE-shipped artifact?
- *
- * The exact test {@link SchemaRegistry.getArtifactItem} has always applied,
- * factored out so the object branch and the D9.8 hydration discriminator
- * ({@link SchemaRegistry.getPackagedObjectOwner}) cannot drift into two
- * different answers to one question — "does a code package ship this name?".
- * Truthy `_packageId`, not the `'sys_metadata'` rehydration sentinel, and not
- * tenant provenance.
- */
-export function isCodeArtifactBody(item: unknown): boolean {
-  const it = item as { _packageId?: unknown } | null | undefined;
-  if (!it || !it._packageId || it._packageId === 'sys_metadata') return false;
-  return !isTenantAuthored(it);
-}
+// [#10062] `isTenantAuthored` and `isCodeArtifactBody` used to be defined here.
+// They now live in `@objectstack/metadata-core`
+// (`code-artifact-provenance.ts`), imported at the top of this file and
+// re-exported immediately below, so every caller's spelling — including
+// `@objectstack/objectql`'s own public export — is unchanged. Their full
+// rationale moved with them.
+export { isCodeArtifactBody };
 
 // ============================================================================
 // i18n bundles — metadata types whose identity is (name, <discriminator>)

packages/services/service-automation/src/flow-precedence.ts

@@ -45,7 +45,14 @@
 // larger change, and ADR-0048 does not ask for it — the ADR's answer for this
 // case is a precedence plus a warning, both of which are here.
 
-import { isCodeArtifactBody } from '@objectstack/objectql';
+// [#10062] From `@objectstack/metadata-core`, which this package DECLARES —
+// not from `@objectstack/objectql`, which it does not. The predicate is the
+// same one (it was sunk into metadata-core and objectql re-exports it), but the
+// import used to be an undeclared workspace dependency, and because the shared
+// tsup config externalises only `dependencies`/`peerDependencies` the bundler
+// answered it by inlining objectql's implementation into this package's dist.
+// `pnpm check:undeclared-dep-imports` is the gate over that class.
+import { isCodeArtifactBody } from '@objectstack/metadata-core';
 import type { FlowContender, FlowShadowingRecord } from './engine.js';
 
 /** One flow name's resolved winner, plus the receipt when it displaced others. */

packages/services/service-datasource/package.json

@@ -27,14 +27,14 @@
   },
   "dependencies": {
     "@objectstack/core": "workspace:*",
+    "@objectstack/driver-memory": "workspace:*",
+    "@objectstack/driver-sql": "workspace:*",
     "@objectstack/spec": "workspace:*",
     "@objectstack/types": "workspace:*",
     "pg-connection-string": "^2.14.0"
   },
   "devDependencies": {
-    "@objectstack/driver-memory": "workspace:*",
     "@objectstack/driver-mongodb": "workspace:*",
-    "@objectstack/driver-sql": "workspace:*",
     "@objectstack/driver-sqlite-wasm": "workspace:*",
     "@objectstack/metadata-core": "workspace:*",
     "@objectstack/plugin-hono-server": "workspace:*",