@astram/engine 0.1.4 → 0.2.0

package/dist/decorators/object-type.decorator.d.ts

@@ -24,7 +24,7 @@
  * `undefined` keys and break `deepStrictEqual`).
  */
 import 'reflect-metadata';
-import type { AccessDeclaration, FieldType, IdentityRole, JunctionSpec, ObjectType as ObjectTypeContract, PkStrategy, TrustedSource } from '../types.js';
+import type { AccessDeclaration, FieldType, IdentityRole, JunctionSpec, ObjectType as ObjectTypeContract, PkStrategy, ReadScope, TrustedSource } from '../types.js';
 /**
  * Class-level options for `@ObjectType`. Mirrors the top-level {@link ObjectType}
  * shape EXCEPT `primaryKey` (declared separately via `@PrimaryKey`) and `fields`
@@ -45,6 +45,12 @@ export interface ObjectTypeOptions {
      * absent/contradictory declaration at boot. See {@link AccessDeclaration}.
      */
     readonly access: AccessDeclaration;
+    /**
+     * OPTIONAL read-scope declaration (ADR-0027) — how LIST/GET reads are walled to the
+     * caller's reachable subtree, DECOUPLED from the write path. Reflected with the SAME
+     * omit-when-absent discipline as `junctions`/`extensible`. See {@link ReadScope}.
+     */
+    readonly readScope?: ReadScope;
 }
 /** Per-member options for `@Field` (the field's `key` is read from the member name). */
 export interface FieldOptions {

package/dist/decorators/object-type.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"object-type.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/object-type.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,iBAAiB,EAEjB,SAAS,EACT,YAAY,EACZ,YAAY,EAKZ,UAAU,IAAI,kBAAkB,EAChC,UAAU,EACV,aAAa,EACd,MAAM,aAAa,CAAC;AAarB;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAI3C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAW,SAAQ,kBAAkB;CAAG;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAQ3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,kBAAkB,CAqCnE"}
+{"version":3,"file":"object-type.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/object-type.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EACV,iBAAiB,EAEjB,SAAS,EACT,YAAY,EACZ,YAAY,EAKZ,UAAU,IAAI,kBAAkB,EAChC,UAAU,EACV,SAAS,EACT,aAAa,EACd,MAAM,aAAa,CAAC;AAarB;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC;AAI3C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAW,SAAQ,kBAAkB;CAAG;AAEzD;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,iBAAiB,CAQ3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,cAAc,CAIlE;AAqBD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,QAAQ,GAAG,kBAAkB,CAwCnE"}

package/dist/decorators/object-type.decorator.js

@@ -142,5 +142,9 @@ function reflectObjectType(cls) {
     // registry's `validate` (chokepoint 1) is what rejects the absence at boot.
     if (opts.access !== undefined)
         out.access = opts.access;
+    // `readScope` (ADR-0027) reflected AS-IS with the omit-when-absent discipline — a
+    // type without it omits the key (matching the literal), so `deepStrictEqual` holds.
+    if (opts.readScope !== undefined)
+        out.readScope = opts.readScope;
     return out;
 }

package/dist/index.d.ts

@@ -15,7 +15,8 @@
  *    the `TableRegistry`, and the ports. Exported so the framework + integration
  *    tests can compose the engine directly; NOT for feature code.
  */
-export type { RecordEngine, AccessDeclaration, FieldSpec, FieldType, TrustedSource, IdentityRole, PkStrategy, JunctionSpec, RecordInput, RecordId, RecordView, ListQuery, RecordPage, Principal, } from './types.js';
+export type { RecordEngine, AccessDeclaration, FieldSpec, FieldType, TrustedSource, IdentityRole, PkStrategy, JunctionSpec, RecordInput, RecordId, RecordView, ListQuery, RecordPage, Principal, ReadScope, } from './types.js';
+export { READ_SCOPE_NODES_TOKEN } from './types.js';
 export { EngineError, CapabilityNotSupportedError, RegistrationError, AuthorizationDeniedError, ValidationError, EngineUnavailableError, } from './errors.js';
 export { ObjectType, Field, PrimaryKey, reflectObjectType, type ObjectTypeOptions, type FieldOptions, type PrimaryKeyOptions, } from './decorators/object-type.decorator.js';
 export { AccessBundle, reflectAccessBundle, type AccessBundleOptions, type AccessBundlePermission, type AccessBundleSpec, } from './decorators/access-bundle.decorator.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAC;AAO/C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,GACpB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC1F,YAAY,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,SAAS,EACT,SAAS,EACT,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,UAAU,EACV,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,GACV,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,WAAW,EACX,2BAA2B,EAC3B,iBAAiB,EACjB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,aAAa,CAAC;AAiBrB,OAAO,EACL,UAAU,EACV,KAAK,EACL,UAAU,EACV,iBAAiB,EACjB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,iBAAiB,GACvB,MAAM,uCAAuC,CAAC;AAO/C,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,GACtB,MAAM,yCAAyC,CAAC;AAEjD,OAAO,EACL,YAAY,EACZ,aAAa,EACb,wBAAwB,EACxB,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,eAAe,GACrB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,OAAO,EACP,WAAW,EACX,cAAc,EACd,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EACL,cAAc,EACd,YAAY,EACZ,KAAK,sBAAsB,EAC3B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,GACpB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC1F,YAAY,EACV,OAAO,EACP,UAAU,EACV,YAAY,EACZ,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -17,7 +17,12 @@
  *    tests can compose the engine directly; NOT for feature code.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MariaDbAuditSink = exports.MariaDbUnitOfWork = exports.SERVICE_ACCOUNT_RESOLVER = exports.BoundRecords = exports.RecordsService = exports.RecordEngineImpl = exports.requireRole = exports.columnForRole = exports.tenantColumnOf = exports.ownerColumn = exports.isOwned = exports.uuidPkColumn = exports.columnOf = exports.TableRegistry = exports.ENGINE_ALL_ACCESS_BUNDLES = exports.ENGINE_ALL_REGISTRATIONS = exports.RECORD_ENGINE = exports.EngineModule = exports.reflectAccessBundle = exports.AccessBundle = exports.reflectObjectType = exports.PrimaryKey = exports.Field = exports.ObjectType = exports.EngineUnavailableError = exports.ValidationError = exports.AuthorizationDeniedError = exports.RegistrationError = exports.CapabilityNotSupportedError = exports.EngineError = void 0;
+exports.MariaDbAuditSink = exports.MariaDbUnitOfWork = exports.SERVICE_ACCOUNT_RESOLVER = exports.BoundRecords = exports.RecordsService = exports.RecordEngineImpl = exports.requireRole = exports.columnForRole = exports.tenantColumnOf = exports.ownerColumn = exports.isOwned = exports.uuidPkColumn = exports.columnOf = exports.TableRegistry = exports.ENGINE_ALL_ACCESS_BUNDLES = exports.ENGINE_ALL_REGISTRATIONS = exports.RECORD_ENGINE = exports.EngineModule = exports.reflectAccessBundle = exports.AccessBundle = exports.reflectObjectType = exports.PrimaryKey = exports.Field = exports.ObjectType = exports.EngineUnavailableError = exports.ValidationError = exports.AuthorizationDeniedError = exports.RegistrationError = exports.CapabilityNotSupportedError = exports.EngineError = exports.READ_SCOPE_NODES_TOKEN = void 0;
+// The read-scope subtree-id placeholder token (ADR-0027) — a `subtreeSubquery` template
+// uses it; the engine expands it to a `?`-list. Exported so per-type declarations can
+// reference the canonical token (rather than a stringly-typed duplicate).
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "READ_SCOPE_NODES_TOKEN", { enumerable: true, get: function () { return types_js_1.READ_SCOPE_NODES_TOKEN; } });
 var errors_js_1 = require("./errors.js");
 Object.defineProperty(exports, "EngineError", { enumerable: true, get: function () { return errors_js_1.EngineError; } });
 Object.defineProperty(exports, "CapabilityNotSupportedError", { enumerable: true, get: function () { return errors_js_1.CapabilityNotSupportedError; } });

package/dist/module/engine.module.d.ts

@@ -22,7 +22,7 @@ import type { QueryFn } from '../ports.js';
 import { RECORD_ENGINE } from './tokens.js';
 import { type EngineDbConfig } from '../adapters/mariadb-unit-of-work.js';
 import { type AuditSinkConfig } from '../adapters/mariadb-audit-sink.js';
-import type { ObjectType } from '../types.js';
+import type { ObjectType, Principal } from '../types.js';
 import { type AccessBundleSpec } from '../decorators/access-bundle.decorator.js';
 /**
  * Input accepted by `forFeature` / `forRoot({registrations})`: either a plain
@@ -67,6 +67,19 @@ export interface EngineModuleOptions {
      * the engine never imports guard; this is the injection seam.
      */
     readonly onRecordDeleted?: (query: QueryFn, typeKey: string, recordId: string, tenantId: string) => Promise<void>;
+    /**
+     * OPTIONAL record-level LIST SCOPE (design §8.3, Invariant #8). The consumer wires guard's
+     * framework-constructed `buildListScopeFn(inputs)` here — the engine's `list()` ANDs the
+     * returned SAFE parameterized WHERE fragment into BOTH the data SELECT and the COUNT (the
+     * in-query visible-set filter). ADR-0003: the engine never imports guard; this is the
+     * injection seam, exactly like `onRecordDeleted`. Absent ⇒ today's bare-tenant behavior.
+     * A throw PROPAGATES (fail-closed). It runs only AFTER the coarse object-type gate allows
+     * the read — it narrows rows within an allowed list, never substitutes for the gate.
+     */
+    readonly listScope?: (reg: ObjectType, actor: Principal, action: string) => Promise<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
 }
 export declare class EngineModule {
     /**

package/dist/module/engine.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.module.d.ts","sourceRoot":"","sources":["../../src/module/engine.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,aAAa,EAKnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAuC,OAAO,EAAE,MAAM,aAAa,CAAC;AAIhF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC7F,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0CAA0C,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,CAAC;AAMpD;;;;2EAI2E;AAC3E,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB;;;;qCAIqC;AACrC,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;+CAI+C;AAC/C,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAmC7E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B;iFAC6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAYD,qBACa,YAAY;IACvB;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CACf,aAAa,EAAE,SAAS,eAAe,EAAE,EACzC,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,QAAQ,CAAC,EAAE,CAAA;KAAE,GAClE,aAAa;IAMhB;2FACuF;IACvF,MAAM,CAAC,aAAa,IAAI,IAAI;IAK5B,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa;CAgG5D"}
+{"version":3,"file":"engine.module.d.ts","sourceRoot":"","sources":["../../src/module/engine.module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,aAAa,EAKnB,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAuC,OAAO,EAAE,MAAM,aAAa,CAAC;AAIhF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC7F,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,0CAA0C,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,QAAQ,CAAC;AAMpD;;;;2EAI2E;AAC3E,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB;;;;qCAIqC;AACrC,eAAO,MAAM,wBAAwB,eAAqC,CAAC;AAE3E;;;;+CAI+C;AAC/C,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAmC7E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAC;IAC5B;iFAC6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3D;AAYD,qBACa,YAAY;IACvB;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CACf,aAAa,EAAE,SAAS,eAAe,EAAE,EACzC,IAAI,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,SAAS,CAAC,gBAAgB,GAAG,QAAQ,CAAC,EAAE,CAAA;KAAE,GAClE,aAAa;IAMhB;2FACuF;IACvF,MAAM,CAAC,aAAa,IAAI,IAAI;IAK5B,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,mBAAmB,GAAG,aAAa;CAiG5D"}

package/dist/module/engine.module.js

@@ -181,6 +181,7 @@ let EngineModule = EngineModule_1 = class EngineModule {
                     audit,
                     ...(options.nowMs ? { nowMs: options.nowMs } : {}),
                     ...(options.onRecordDeleted ? { onRecordDeleted: options.onRecordDeleted } : {}),
+                    ...(options.listScope ? { listScope: options.listScope } : {}),
                 };
                 return new record_engine_js_1.RecordEngineImpl(deps);
             },

package/dist/pipe/record-engine.d.ts

@@ -15,7 +15,7 @@
  */
 import type { TableRegistry } from '../registry.js';
 import type { AuditPort, DecisionPort, UnitOfWork, QueryFn } from '../ports.js';
-import type { ListQuery, Principal, RecordEngine, RecordId, RecordInput, RecordPage, RecordView } from '../types.js';
+import type { ListQuery, Principal, RecordEngine, RecordId, RecordInput, RecordPage, RecordView, ObjectType } from '../types.js';
 export interface RecordEngineDeps {
     readonly registry: TableRegistry;
     readonly uow: UnitOfWork;
@@ -45,6 +45,25 @@ export interface RecordEngineDeps {
      * store error) prevents leaving the record deleted with orphaned grants (fail-closed).
      */
     readonly onRecordDeleted?: (query: QueryFn, typeKey: string, recordId: string, tenantId: string) => Promise<void>;
+    /**
+     * OPTIONAL record-level LIST SCOPE (design §8.3, the list-scoping engine). When present,
+     * list() ANDs the returned SAFE parameterized WHERE fragment into BOTH the data SELECT and
+     * the COUNT — the in-query visible-set filter (Invariant #8). The CONSUMER wires guard's
+     * framework-constructed `buildListScopeFn` here (ADR-0003: the engine never imports guard —
+     * this is the injection seam, exactly like `onRecordDeleted`). Absent ⇒ today's bare-tenant
+     * behavior (back-compat until wired). Returns `{ sql, params }`: the fragment ANDed into the
+     * WHERE. A throw PROPAGATES (fail-closed — the list read fails, never returns unscoped rows).
+     *
+     * ⛔ SCOPE RUNS AFTER THE GATE: list() calls the coarse object-type gate (gateRead → decide())
+     * FIRST; the scope narrows rows WITHIN an already-allowed object-type list and NEVER substitutes
+     * for the gate. This ordering is load-bearing: a ROOT actor's scope is root-unbounded (no tenant
+     * clause, `(TRUE)` union) — the ONLY thing preventing root from reading every tenant's data-plane
+     * rows is that gateRead DENIES root on a data-plane type before any scope is built.
+     */
+    readonly listScope?: (reg: ObjectType, actor: Principal, action: string) => Promise<{
+        sql: string;
+        params: readonly unknown[];
+    }>;
 }
 export declare class RecordEngineImpl implements RecordEngine {
     private readonly registry;
@@ -53,6 +72,7 @@ export declare class RecordEngineImpl implements RecordEngine {
     private readonly audit;
     private readonly now;
     private readonly onRecordDeleted;
+    private readonly listScope;
     /** The FIXED write-stage order. Built once; identical for every write. */
     private readonly writeStages;
     constructor(deps: RecordEngineDeps);
@@ -68,5 +88,35 @@ export declare class RecordEngineImpl implements RecordEngine {
     list(typeKey: string, query: ListQuery, actor: Principal): Promise<RecordPage>;
     /** The physical column of a `tenantId`-trusted field, if the table has one. */
     private tenantColumn;
+    /**
+     * The set of tenant nodes a non-root actor's reads are bounded to (ADR-0027): its
+     * active-scope subtree (active node + descendants), resolved once at login and cached on
+     * the principal (`scopeSubtreeNodeIds`). The engine's built-in tenant clause emits
+     * `tenant_col IN (these)` — the SAME set the tenant gate + list-scope use, so the three
+     * agree (no self-node collapse of the subtree). FAIL-SAFE + non-widening: a malformed or
+     * absent subtree falls back to just the actor's home node (`[actor.tenantId]`) — exactly
+     * today's flat self-tenant isolation; NEVER an empty set (which would hide all own rows).
+     */
+    private tenantScopeNodes;
+    /**
+     * The read-scope predicate for a type's LIST/GET reads (ADR-0027, Task 4.1) — the wall
+     * that filters a `system` type's rows to the caller's reachable subtree, DECOUPLED from
+     * the write path (`readScope` NEVER stamps a write). Shared by list() AND get() so both
+     * apply the SAME wall. Returns `null` when there is nothing to AND:
+     *  - the type declares no `readScope`, OR
+     *  - the actor is ROOT (`isRoot === true`, strict) — root spans all, no clause.
+     * Otherwise ANDs, over the actor's subtree nodes (`tenantScopeNodes` — the SAME set the
+     * tenant clause + list-scope use, so the three agree):
+     *  - `nodeColumn`      → `` `<column>` IN (?, ...) `` — subtree ids `?`-bound.
+     *  - `subtreeSubquery` → `` `<pkColumn>` IN (<subquerySql, :nodes → IN (?, ...)>) `` — the
+     *    FIXED framework template with the subtree ids `?`-bound at `:nodes`.
+     *
+     * INJECTION-FREE BY CONSTRUCTION: the ONLY dynamic values are the `?`-bound subtree node
+     * ids; every identifier is a compile-time constant (the type's own column, or the fixed
+     * template). No node value is ever interpolated into the SQL string. FAIL-CLOSED: an
+     * empty subtree (shouldn't happen — `tenantScopeNodes` never returns empty) would still
+     * emit `IN ()`, which matches nothing (deny), never a widening clause.
+     */
+    private readScopeClause;
 }
 //# sourceMappingURL=record-engine.d.ts.map

package/dist/pipe/record-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record-engine.d.ts","sourceRoot":"","sources":["../../src/pipe/record-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EAEX,MAAM,aAAa,CAAC;AAWrB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAOlB;IACd,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;gBAEnC,IAAI,EAAE,gBAAgB;YAwBpB,QAAQ;IAsChB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMhF,MAAM,CACV,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC;IAIV,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;YAM9D,QAAQ;IAiCtB,OAAO,CAAC,SAAS;IAIjB,mEAAmE;IACnE,OAAO,CAAC,OAAO;IAiBT,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA8DhF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAyEpF,+EAA+E;IAC/E,OAAO,CAAC,YAAY;CAIrB"}
+{"version":3,"file":"record-engine.d.ts","sourceRoot":"","sources":["../../src/pipe/record-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,KAAK,EACV,SAAS,EACT,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,UAAU,EACV,UAAU,EACX,MAAM,aAAa,CAAC;AAYrB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CACzB,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CACnB,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;KAAE,CAAC,CAAC;CAC3D;AAED,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAOlB;IACd,OAAO,CAAC,QAAQ,CAAC,SAAS,CAMZ;IACd,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmB;gBAEnC,IAAI,EAAE,gBAAgB;YAyBpB,QAAQ;IAsChB,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMhF,MAAM,CACV,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,SAAS,GACf,OAAO,CAAC,IAAI,CAAC;IAIV,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;YAM9D,QAAQ;IAiCtB,OAAO,CAAC,SAAS;IAIjB,mEAAmE;IACnE,OAAO,CAAC,OAAO;IAiBT,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA4EhF,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAsHpF,+EAA+E;IAC/E,OAAO,CAAC,YAAY;IAKpB;;;;;;;;OAQG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,eAAe;CAmBxB"}

package/dist/pipe/record-engine.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RecordEngineImpl = void 0;
 const errors_js_1 = require("../errors.js");
 const registry_js_1 = require("../registry.js");
+const types_js_1 = require("../types.js");
 const context_js_1 = require("./context.js");
 const fetch_owner_js_1 = require("./stages/fetch-owner.js");
 const permission_gate_js_1 = require("./stages/permission-gate.js");
@@ -34,6 +35,7 @@ class RecordEngineImpl {
     audit;
     now;
     onRecordDeleted;
+    listScope;
     /** The FIXED write-stage order. Built once; identical for every write. */
     writeStages;
     constructor(deps) {
@@ -43,6 +45,7 @@ class RecordEngineImpl {
         this.audit = deps.audit;
         this.now = deps.nowMs ?? (() => Date.now());
         this.onRecordDeleted = deps.onRecordDeleted;
+        this.listScope = deps.listScope;
         // permission-gate + audit are ALWAYS present, in this order — no skip flag.
         // fetch-owner runs FIRST (before the gate) so an OWNED update/delete's existing-row
         // owner is available to decide() as context.attributes.ownerId (core owner baseline).
@@ -166,11 +169,24 @@ class RecordEngineImpl {
                 where = pk.columns.map((c) => `\`${c}\` = ?`).join(' AND ');
                 params = pk.columns.map((c) => id[c]);
             }
-            // Tenant scoping: if the table has a tenant column, constrain to the actor's tenant.
+            // Tenant scoping: if the table has a tenant column, constrain to the actor's reachable
+            // subtree (ADR-0027 — active node + descendants), NOT just the self-node. ROOT spans all
+            // tenants — only a STRICT `=== true` isRoot counts (fail-closed). Fail-safe to the
+            // self-node if the subtree is malformed/absent (non-widening).
             const tenantCol = this.tenantColumn(reg);
-            if (tenantCol) {
-                where += ` AND \`${tenantCol}\` = ?`;
-                params = [...params, actor.tenantId];
+            if (tenantCol && actor.isRoot !== true) {
+                const nodes = this.tenantScopeNodes(actor);
+                where += ` AND \`${tenantCol}\` IN (${nodes.map(() => '?').join(', ')})`;
+                params = [...params, ...nodes];
+            }
+            // Read-scope wall (ADR-0027, Task 4.1): for a type declaring `readScope` (the identity
+            // `system` types with no tenant column), a NON-ROOT read is bounded to the caller's
+            // reachable subtree. ANDs AFTER the tenant clause (which won't fire for these system
+            // types); root gets NO clause (spans all). Injection-free — only `?`-bound node ids.
+            const scope = this.readScopeClause(reg, actor);
+            if (scope) {
+                where += ` AND ${scope.sql}`;
+                params = [...params, ...scope.params];
             }
             if ((0, registry_js_1.isOwned)(reg)) {
                 // OWNED read — FETCH-THEN-GATE. Core's owner baseline needs the row's owner,
@@ -206,10 +222,39 @@ class RecordEngineImpl {
             const clauses = [];
             const params = [];
             // Mandatory tenant scoping when the table is tenant-owned (cross-tenant safety).
+            // ROOT spans all tenants — but only a STRICT `=== true` isRoot counts (fail-closed):
+            // a truthy-non-boolean must never bypass the tenant boundary.
+            // SUBTREE-AWARE (ADR-0027): a non-root actor is bounded to its reachable subtree
+            // (active node + descendants), NOT just the self-node — `tenant_col IN (?, ...)` over
+            // `actor.scopeSubtreeNodeIds` (the SAME cached set the tenant gate + list-scope use).
+            // Fail-safe to `[actor.tenantId]` (self-node) if the subtree is malformed/absent.
+            //
+            // ⛔ ONE-AUTHORITY (Invariant #3, §10bis.5): this built-in clause is the FAIL-SAFE for
+            // when the list-scope engine is NOT wired (pre-Phase-3 / a consumer without it). When
+            // `listScope` IS wired, the list-scope FRAGMENT is the single source of the tenant
+            // boundary — it already emits `tenant_col = ?` / `IN (subtree)` for non-root AND ORs in
+            // the cross-tenant grant reach (§10bis.5). Emitting BOTH here would AND this narrower
+            // own-subtree filter over the fragment and KILL every cross-tenant-granted row before the
+            // fragment's widening can include it (the exact divergence the list≡decide gate caught).
+            // So when `listScope` is present we DEFER the tenant bound entirely to the fragment — one
+            // authority, no double-filter. (readScope system-types are unaffected: they have no
+            // tenant column, so this clause never fired for them anyway; their wall is `readScope`.)
             const tenantCol = this.tenantColumn(reg);
-            if (tenantCol) {
-                clauses.push(`\`${tenantCol}\` = ?`);
-                params.push(actor.tenantId);
+            if (tenantCol && actor.isRoot !== true && !this.listScope) {
+                const nodes = this.tenantScopeNodes(actor);
+                clauses.push(`\`${tenantCol}\` IN (${nodes.map(() => '?').join(', ')})`);
+                params.push(...nodes);
+            }
+            // Read-scope wall (ADR-0027, Task 4.1): a type declaring `readScope` (the identity
+            // `system` types with no tenant column) has its NON-ROOT reads bounded to the caller's
+            // reachable subtree. ANDed AFTER the tenant clause (which won't fire for these system
+            // types) into BOTH the data SELECT and the COUNT (shared clauses/params ⇒ consistent
+            // by construction). Root gets NO clause (spans all). Injection-free — only `?`-bound
+            // node ids; identifiers are the type's own column or a fixed framework template.
+            const readScope = this.readScopeClause(reg, actor);
+            if (readScope) {
+                clauses.push(readScope.sql);
+                params.push(...readScope.params);
             }
             // Equality filters on registered field columns only (unknown keys rejected).
             // The COLUMN comes from a whitelisted field-key lookup; the VALUE is a bound
@@ -238,6 +283,20 @@ class RecordEngineImpl {
                 }
                 clauses.push(`(${ors.join(' OR ')})`);
             }
+            // Record-level list scope (§8.3): AND the framework-computed visible-set fragment into
+            // BOTH the data SELECT and the COUNT (via the shared clauses/params — so `total` and
+            // `rows` stay consistent BY CONSTRUCTION). Runs only AFTER the coarse object-type gate
+            // (gateRead, at the TOP of list()) has allowed the read — the scope narrows rows WITHIN
+            // an allowed object-type list; it NEVER substitutes for the gate (the root/data-plane
+            // leak-guard). A scope-fn throw PROPAGATES (fail-closed — the read fails; we never fall
+            // back to unscoped rows). An empty `sql` is simply not ANDed (no fabricated widening).
+            if (this.listScope) {
+                const scope = await this.listScope(reg, actor, 'read');
+                if (scope.sql) {
+                    clauses.push(scope.sql);
+                    params.push(...scope.params);
+                }
+            }
             const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
             // Sort: resolve `sortBy` to a column the SAME whitelisted way as where-keys
             // (unknown key → throw). The direction is an enum-checked literal (only 'desc'
@@ -265,6 +324,55 @@ class RecordEngineImpl {
         const f = reg.fields.find((x) => x.trusted === 'tenantId');
         return f ? (0, registry_js_1.columnOf)(f) : null;
     }
+    /**
+     * The set of tenant nodes a non-root actor's reads are bounded to (ADR-0027): its
+     * active-scope subtree (active node + descendants), resolved once at login and cached on
+     * the principal (`scopeSubtreeNodeIds`). The engine's built-in tenant clause emits
+     * `tenant_col IN (these)` — the SAME set the tenant gate + list-scope use, so the three
+     * agree (no self-node collapse of the subtree). FAIL-SAFE + non-widening: a malformed or
+     * absent subtree falls back to just the actor's home node (`[actor.tenantId]`) — exactly
+     * today's flat self-tenant isolation; NEVER an empty set (which would hide all own rows).
+     */
+    tenantScopeNodes(actor) {
+        const subtree = actor.scopeSubtreeNodeIds;
+        return Array.isArray(subtree) && subtree.length > 0 ? subtree : [actor.tenantId];
+    }
+    /**
+     * The read-scope predicate for a type's LIST/GET reads (ADR-0027, Task 4.1) — the wall
+     * that filters a `system` type's rows to the caller's reachable subtree, DECOUPLED from
+     * the write path (`readScope` NEVER stamps a write). Shared by list() AND get() so both
+     * apply the SAME wall. Returns `null` when there is nothing to AND:
+     *  - the type declares no `readScope`, OR
+     *  - the actor is ROOT (`isRoot === true`, strict) — root spans all, no clause.
+     * Otherwise ANDs, over the actor's subtree nodes (`tenantScopeNodes` — the SAME set the
+     * tenant clause + list-scope use, so the three agree):
+     *  - `nodeColumn`      → `` `<column>` IN (?, ...) `` — subtree ids `?`-bound.
+     *  - `subtreeSubquery` → `` `<pkColumn>` IN (<subquerySql, :nodes → IN (?, ...)>) `` — the
+     *    FIXED framework template with the subtree ids `?`-bound at `:nodes`.
+     *
+     * INJECTION-FREE BY CONSTRUCTION: the ONLY dynamic values are the `?`-bound subtree node
+     * ids; every identifier is a compile-time constant (the type's own column, or the fixed
+     * template). No node value is ever interpolated into the SQL string. FAIL-CLOSED: an
+     * empty subtree (shouldn't happen — `tenantScopeNodes` never returns empty) would still
+     * emit `IN ()`, which matches nothing (deny), never a widening clause.
+     */
+    readScopeClause(reg, actor) {
+        const rs = reg.readScope;
+        if (!rs || actor.isRoot === true)
+            return null;
+        const nodes = this.tenantScopeNodes(actor);
+        const placeholders = nodes.map(() => '?').join(', ');
+        if (rs.kind === 'nodeColumn') {
+            return { sql: `\`${rs.column}\` IN (${placeholders})`, params: [...nodes] };
+        }
+        // subtreeSubquery: expand the FIXED template's `:nodes` token to a `?`-list. The
+        // template's identifiers are constants; only the node ids are `?`-bound (below).
+        const expanded = rs.subquerySql.replace(types_js_1.READ_SCOPE_NODES_TOKEN, placeholders);
+        return {
+            sql: `\`${rs.pkColumn}\` IN (${expanded})`,
+            params: [...nodes],
+        };
+    }
 }
 exports.RecordEngineImpl = RecordEngineImpl;
 /**

package/dist/types.d.ts

@@ -98,6 +98,43 @@ export interface AccessDeclaration {
      */
     readonly plane: CapabilityPlane;
 }
+/**
+ * How a type's LIST/GET reads are scoped to the caller's reachable subtree (ADR-0027) —
+ * DECOUPLED from `trusted:'tenantId'` (which stamps WRITES via derive-write-context).
+ * `readScope` filters READS ONLY; it has ZERO write effect (a create still stamps only the
+ * `trusted` fields). Absent ⇒ no subtree read-scope (today's behavior — the tenant clause,
+ * if the type has a `trusted:'tenantId'` column, still applies; a `system` type with no
+ * such column then returns unscoped, which is why the identity `system` types declare a
+ * `readScope` to wall themselves). Applied by the engine AFTER the tenant clause, for
+ * NON-ROOT actors only (root spans all).
+ *
+ * Two forms:
+ *  - `nodeColumn` — rows whose `<column>` is IN the caller's subtree node ids
+ *    (`` `<column>` IN (?, ...) ``). Use when the type's own row carries the node itself
+ *    (e.g. `company.c_uuid`, `company_membership.cm_company_uuid`).
+ *  - `subtreeSubquery` — rows whose PK is IN a membership-derived subquery over the
+ *    caller's subtree. The `subquerySql` is a FIXED, FRAMEWORK-AUTHORED template per type
+ *    (NEVER client SQL): every identifier is a compile-time constant, and the ONLY dynamic,
+ *    `?`-bound values are the subtree node ids — injected via the `:nodes` placeholder the
+ *    engine expands to `IN (?, ?, ...)`. This is injection-free BY CONSTRUCTION (no value
+ *    is ever interpolated into the SQL string).
+ */
+export type ReadScope = {
+    readonly kind: 'nodeColumn';
+    readonly column: string;
+} | {
+    readonly kind: 'subtreeSubquery';
+    /** The type's OWN PK column to test membership of. */
+    readonly pkColumn: string;
+    /**
+     * A FIXED framework template containing the `:nodes` placeholder (expanded by the
+     * engine to `IN (?, ?, ...)` with the subtree ids `?`-bound). NOT client SQL —
+     * identifiers are constants; the ONLY dynamic values are the bound node ids.
+     */
+    readonly subquerySql: string;
+};
+/** The token a `subtreeSubquery` template uses for the engine-expanded subtree id list. */
+export declare const READ_SCOPE_NODES_TOKEN = ":nodes";
 /** Primary-key strategy for a registered table. */
 export type PkStrategy = {
     readonly kind: 'uuid';
@@ -137,6 +174,13 @@ export interface ObjectType {
      * fails (chokepoint 1). See {@link AccessDeclaration}.
      */
     readonly access: AccessDeclaration;
+    /**
+     * OPTIONAL read-scope declaration (ADR-0027) — how LIST/GET reads are filtered to the
+     * caller's reachable subtree, DECOUPLED from the write path. See {@link ReadScope}.
+     * Absent ⇒ no subtree read-scope (the tenant clause, if any, still applies). Has ZERO
+     * write effect.
+     */
+    readonly readScope?: ReadScope;
 }
 /** Input to a create/update — field keys → values (+ optional junction refs). */
 export interface RecordInput {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -13,3 +13,6 @@
  * surface.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.READ_SCOPE_NODES_TOKEN = void 0;
+/** The token a `subtreeSubquery` template uses for the engine-expanded subtree id list. */
+exports.READ_SCOPE_NODES_TOKEN = ':nodes';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/engine",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Astram framework — the paved road. ONE unbypassable write pipe (resolve-schema → permission gate → derive-write-context → validate → compute → write → junction-sync → audit → emit-event) over real physical tables, that every feature's CRUD flows through. Feature code receives ONLY the RecordEngine facade — never a raw pool/DataSource/QueryRunner (the physical wall). Security-gate + audit are mandatory stages. Missing capability → a typed CapabilityNotSupportedError (the gap-flag STOP). Builds on @astram/core (metadata contract, decide(), audit) + @astram/guard (decision authority).",
   "type": "commonjs",
@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "mariadb": "^3.4.0",
-    "@astram/core": "1.1.0"
+    "@astram/core": "1.2.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",