@endora-commerce/platform 0.100.0

package/dist/packages/package-runtime.js

@@ -0,0 +1,386 @@
+// Installed extension packages — the composition half (feature 080, T031).
+//
+// `loadPackageModuleEntries` is the sibling of `loadOverlayModuleEntries`
+// (`src/overlay/overlay-runtime.ts`) and the second caller of the seam !716
+// built: a composition root appends what it returns to the one
+// `composeModules([...MODULES, ...overlay, ...packages], …)` call, so an
+// installed package receives an ordinary `ModuleContext` and reaches every seam
+// a core module reaches. There is no second registration pass, no second
+// contribution window and no second `runBootHooks()` (D-45).
+//
+// **Discovered at runtime, and the committed registries stay bare core**
+// (D-119, confirmed as D-155). D-104's predicate decides it, and it yields
+// three consistent answers rather than two: an artefact is committed when its
+// content is a fact about *the tree*, and resolved at runtime when it is a fact
+// about *the process*. A workspace-member module package is a fact about the
+// tree (D-149). Which deployment a process is, is a fact about the process
+// (D-104). Which packages are installed in an instance's `node_modules` is a
+// fact about the process too — so it is discovered here, and
+// `composition.generated.ts`, `manifest-index.generated.ts` and both `db/`
+// registries stay a walk of the shared core tree.
+//
+// What discovery can and cannot see is written out in `installed-packages.ts`;
+// read that header before assuming this finds a linked directory (it does not).
+//
+// ## Two things it deliberately does not do
+//
+//  1. **It does not mark a package `overlay: true`.** That flag exempts a
+//     module from the rule that it may decorate only what it registered (issue
+//     #203), and an overlay module earns it from the root it was found under:
+//     the deployment authored the module and owns the decision. A package is a
+//     third party. **D-156 rules it**, and the answer is the one this file
+//     ships: a package's `ctx.di.decorate` over a registration it does not own
+//     is refused like any core module's. The load-bearing half of that ruling
+//     is about the mechanism — `ModuleEntry.overlay` is a per-module boolean
+//     and the condition it feeds is name-unscoped, so setting it from an
+//     instance's declaration would hand a stranger `commandBus` and
+//     `auditLogService` along with whatever it asked for. Any future grant is
+//     keyed by (package, registration name) and refused outright for a name no
+//     module owns; it is never this flag.
+//  2. **It reads a package's schema; it does not configure one.** T033 added
+//     `packageSchemaContributionsUnder` at the bottom of this file: it resolves
+//     `./migrations` and `./backend` and reads them into registry entries and
+//     entity classes. Merging those into the execution order and into the ORM
+//     configuration is `src/db/configured-migrations.ts` and
+//     `src/db/configured-entities.ts` — so the merge has exactly one
+//     implementation, and this file still knows nothing about a database.
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { nodeModulesRootsFor, scanNodeModulesRoots, } from './installed-packages.js';
+import { assertNoModuleIdCollisions, } from '../lifecycle/services/module-id-claims.js';
+/**
+ * The scan, memoised per root list.
+ *
+ * An instance's `node_modules` does not change while the platform runs, and
+ * both `resolvedManifestEntries()` and `loadPackageModuleEntries()` ask the
+ * same question during one boot. Keyed by the roots so a test driving explicit
+ * roots never reads another test's answer.
+ *
+ * There is deliberately no reset seam: a fixture that needs a fresh scan writes
+ * itself under a fresh root, which is what a test asking a different question
+ * has to do anyway.
+ */
+const scans = new Map();
+function scan(roots) {
+    // `\0` because it is the one byte a POSIX path cannot contain, so no two
+    // distinct root lists can key the same entry. Written as the **escape**, not
+    // as the byte: a raw NUL makes git classify the file as binary, and every
+    // diff of it renders as `Binary files differ` — the artefact that would show
+    // the byte is the one the byte switches off (issues #182, #190).
+    const key = roots.join('\0');
+    const cached = scans.get(key);
+    if (cached)
+        return cached;
+    const fresh = scanNodeModulesRoots(roots);
+    scans.set(key, fresh);
+    return fresh;
+}
+/**
+ * The module-id claims of every installed module package under `roots`.
+ *
+ * Exported so the *overlay* seams can be held to one collision rule over one
+ * claimed set (feature 103, FR-004) without a second enumeration of what is
+ * installed: the scan below is memoised per root list, so asking here costs a
+ * map lookup on a boot that has already asked.
+ */
+export function installedPackageModuleIdClaims(roots) {
+    return claimsFor(scan(roots).packages);
+}
+function claimsFor(packages) {
+    return packages.map((installed) => ({
+        id: installed.id,
+        origin: 'package',
+        claimedBy: installed.manifestPath,
+        name: installed.name,
+    }));
+}
+/**
+ * Resolve one of the package's `exports` subpaths, the way anything in the
+ * instance would.
+ *
+ * Rooted at the directory that *holds* the `node_modules` the package was found
+ * under, so Node's own resolver — `exports` map, conditions and all — answers
+ * rather than a hand-rolled read of the map. `null` means the package publishes
+ * no such subpath, which for `./backend` is an ordinary answer (an admin- or
+ * storefront-only module).
+ */
+function resolveSubpath(installed, subpath) {
+    const require = createRequire(join(dirname(installed.foundUnder), 'noop.js'));
+    const specifier = subpath === '.' ? installed.name : `${installed.name}/${subpath}`;
+    try {
+        return require.resolve(specifier);
+    }
+    catch {
+        // Narrow by construction: the only thing inside the `try` is a resolution,
+        // and a resolution either finds a path or the package does not publish one.
+        // Nothing here can reach a port, so nothing here can swallow a
+        // `ModuleDisabledError`.
+        return null;
+    }
+}
+async function importSubpath(installed, subpath) {
+    const resolved = resolveSubpath(installed, subpath);
+    if (resolved === null)
+        return null;
+    return (await import(pathToFileURL(resolved).href));
+}
+function manifestFrom(module) {
+    const named = module['manifest'];
+    if (named !== undefined)
+        return named;
+    const fallback = module['default'];
+    return fallback === undefined ? undefined : fallback;
+}
+/**
+ * Read one package's root export and check that it agrees with `package.json`.
+ *
+ * The id is taken from `endora.id`, because that is the field the platform can
+ * read without importing anything — which is what lets discovery refuse a
+ * collision before a stranger's code has run. The manifest carries the id too,
+ * and a disagreement is refused rather than silently resolved: whichever half
+ * the reader believed, the other one is what some part of the platform would
+ * have used.
+ */
+async function manifestEntryFor(installed) {
+    const module = await importSubpath(installed, '.');
+    if (module === null) {
+        throw new Error(`[packages] ${installed.name} declares endora.id "${installed.id}" but publishes no root ` +
+            `export, so it has no manifest. A module package's "." export is its manifest ` +
+            `(specs/071-modular-packaging/contracts/module-manifest.md). Resolved from ` +
+            `${installed.manifestPath}.`);
+    }
+    const manifest = manifestFrom(module);
+    if (manifest === undefined) {
+        throw new Error(`[packages] the root export of ${installed.name} exports no "manifest", so the module has ` +
+            `no version and no declarations to compose it under. Resolved from ` +
+            `${installed.manifestPath}.`);
+    }
+    if (manifest.id !== installed.id) {
+        throw new Error(`[packages] ${installed.name} disagrees with itself about its module id: its package.json ` +
+            `says endora.id "${installed.id}" and its manifest says "${manifest.id}". The two name ` +
+            `the same thing and the platform reads both — package.json before anything is imported, ` +
+            `the manifest for everything afterwards — so a disagreement makes the module's identity ` +
+            `depend on which half a caller looked at. Fix it at ${installed.manifestPath}.`);
+    }
+    // `exactOptionalPropertyTypes`: an absent key is not `{ hook: undefined }`,
+    // and the lifecycle asks `entry.installHook !== undefined`.
+    const installHook = module['installHook'];
+    const uninstallHook = module['uninstallHook'];
+    const lifecycleParticipant = module['lifecycleParticipant'];
+    const cliCommands = module['cliCommands'];
+    const recentActivity = module['recentActivity'];
+    return {
+        id: installed.id,
+        manifest,
+        filePath: installed.manifestPath,
+        packageName: installed.name,
+        ...(installHook ? { installHook } : {}),
+        ...(uninstallHook ? { uninstallHook } : {}),
+        ...(lifecycleParticipant ? { lifecycleParticipant } : {}),
+        ...(cliCommands ? { cliCommands } : {}),
+        ...(recentActivity ? { recentActivity } : {}),
+    };
+}
+/**
+ * The manifests of every installed module package, refusing an id two of them
+ * claim.
+ *
+ * A package with no `./backend` export still appears here: an admin- or
+ * storefront-only module has permissions, an activation control and i18n
+ * bundles, and dropping the manifest would take all three with it.
+ */
+export async function packageModuleManifestsUnder(roots) {
+    const found = scan(roots);
+    assertNoModuleIdCollisions(claimsFor(found.packages));
+    const out = [];
+    for (const installed of found.packages) {
+        const entry = await manifestEntryFor(installed);
+        if (entry !== null)
+            out.push(entry);
+    }
+    return out;
+}
+/** {@link packageModuleManifestsUnder} over the roots this platform reads. */
+export async function discoverPackageModuleManifests(env = process.env) {
+    return packageModuleManifestsUnder(nodeModulesRootsFor(env));
+}
+/**
+ * The composer entries of every installed module package, against explicit
+ * roots.
+ *
+ * Exported so the loader can be driven over a fixture instance that enters at
+ * the top of the analysis — a `node_modules` tree on disk, enumerated,
+ * `exports`-resolved and imported by the same code the deployment path runs —
+ * rather than by handing the last function a pre-built entry (issue #130).
+ */
+export async function packageModuleEntriesUnder(roots) {
+    const found = scan(roots);
+    assertNoModuleIdCollisions(claimsFor(found.packages));
+    const entries = [];
+    for (const installed of found.packages) {
+        const backend = await importSubpath(installed, 'backend');
+        // No `./backend` export at all is an ordinary answer and is skipped, the
+        // same way an overlay directory with no `backend.ts` is. A `./backend` that
+        // resolves and exports no `registerModule` is a different thing and is
+        // refused: skipping it composes nothing, and the first symptom is a 404
+        // nobody connects to this file.
+        if (backend === null)
+            continue;
+        const registerModule = backend['registerModule'];
+        if (typeof registerModule !== 'function') {
+            throw new Error(`[packages] the "./backend" export of ${installed.name} exports no 'registerModule'. ` +
+                `A module package's backend entry point is what composes it ` +
+                `(specs/071-modular-packaging/contracts/module-manifest.md); remove the export if the ` +
+                `package has no server half. It is not composed as written, and a module that composes ` +
+                `nothing is a 404 with no error behind it. Resolved from ${installed.manifestPath}.`);
+        }
+        const manifestEntry = await manifestEntryFor(installed);
+        if (manifestEntry === null)
+            continue;
+        entries.push({
+            id: installed.id,
+            version: manifestEntry.manifest.version,
+            registerModule: registerModule,
+            // No `overlay: true`. See this file's header — a package is a stranger,
+            // and the decoration exemption is the deployment's alone until something
+            // rules otherwise.
+            //
+            // `installedPackage: true` is the mirror image of that flag and is set
+            // from where this loader found the package, never from anything the
+            // package declares: it is what makes the kernel refuse a *deployment's*
+            // overlay wrapping a registration this package owns (D-176 Q3). Until the
+            // decoration drain landed, that case was refused by accident — the root
+            // composes overlays before packages, so the name was not in the container
+            // yet — and the drain would otherwise have granted a capability the owner
+            // declined.
+            installedPackage: true,
+        });
+    }
+    return entries;
+}
+/**
+ * Every installed module package this platform composes.
+ *
+ * Empty for an instance that installed none, which is every developer checkout
+ * and every test run — and empty is the whole story there: the composition is
+ * byte-for-byte what it was before this loader existed.
+ */
+export async function loadPackageModuleEntries(env = process.env) {
+    return packageModuleEntriesUnder(nodeModulesRootsFor(env));
+}
+function isConstructor(value) {
+    return typeof value === 'function';
+}
+/**
+ * Read a package's `./migrations` export into registry entries.
+ *
+ * Two published shapes are accepted, because the contract's wording ("exports
+ * the migration class array") and the acceptance fixture disagree about which
+ * one it means: a bare array of migration classes, and an array of
+ * `{ name, class }` — MikroORM's own `MigrationObject` shape. Anything else is
+ * **refused rather than skipped**: a migration the host silently drops is a
+ * table that never gets created, and the first symptom is a query error nobody
+ * connects to this file.
+ *
+ * The name is always `cls.name`. A declared `name` that disagrees with it is
+ * refused for the reason `mikro_orm_migrations` gives: the class name is what
+ * is persisted, so the host would record one string and revert by another.
+ */
+function migrationEntriesFrom(installed, exported) {
+    const declared = exported['migrations'] ?? exported['default'];
+    if (!Array.isArray(declared)) {
+        throw new Error(`[packages] the "./migrations" export of ${installed.name} exports no 'migrations' array. ` +
+            `A module package's migrations entry point is the array of its migration classes ` +
+            `(specs/071-modular-packaging/contracts/module-manifest.md); drop the export if the ` +
+            `package ships no schema. Resolved from ${installed.manifestPath}.`);
+    }
+    return declared.map((entry, index) => {
+        const candidate = isConstructor(entry)
+            ? entry
+            : entry?.class;
+        if (!isConstructor(candidate)) {
+            throw new Error(`[packages] entry ${index} of the "./migrations" export of ${installed.name} is neither ` +
+                `a migration class nor a { name, class } pair. Resolved from ${installed.manifestPath}.`);
+        }
+        const declaredName = isConstructor(entry)
+            ? undefined
+            : entry.name;
+        if (typeof declaredName === 'string' && declaredName !== candidate.name) {
+            throw new Error(`[packages] the "./migrations" export of ${installed.name} declares migration ` +
+                `"${declaredName}" for a class named "${candidate.name}". mikro_orm_migrations ` +
+                `persists the class name, so the host would record one string and revert by another. ` +
+                `Resolved from ${installed.manifestPath}.`);
+        }
+        return {
+            moduleId: installed.id,
+            cls: candidate,
+            // Never omitted and never 'core'. The baseline block is a claim about
+            // *our* history (`migration-order.ts`), and an entry that lies about its
+            // origin joins a frozen prefix it has no business in.
+            origin: 'external',
+        };
+    });
+}
+/** Read a package's `./backend` export for the entity classes it declares. */
+function entityClassesFrom(installed, exported) {
+    const declared = exported['entities'];
+    if (declared === undefined)
+        return [];
+    if (!Array.isArray(declared)) {
+        throw new Error(`[packages] the "./backend" export of ${installed.name} exports 'entities' that is not an ` +
+            `array. It is the list of entity classes the host's ORM registers. Resolved from ` +
+            `${installed.manifestPath}.`);
+    }
+    return declared.map((entry, index) => {
+        if (!isConstructor(entry)) {
+            throw new Error(`[packages] entry ${index} of the 'entities' export of ${installed.name} is not a class. ` +
+                `Resolved from ${installed.manifestPath}.`);
+        }
+        return entry;
+    });
+}
+/**
+ * Every installed package's schema contribution, against explicit roots.
+ *
+ * Exported so a test can drive it over a `node_modules` tree on disk — the same
+ * entry point the deployment path takes, enumerated, `exports`-resolved and
+ * imported by the same code — rather than by handing a downstream function a
+ * pre-built entry (issue #130).
+ */
+export async function packageSchemaContributionsUnder(roots) {
+    const found = scan(roots);
+    assertNoModuleIdCollisions(claimsFor(found.packages));
+    const out = [];
+    for (const installed of found.packages) {
+        const migrationsEntry = resolveSubpath(installed, 'migrations');
+        const migrations = migrationsEntry === null
+            ? []
+            : migrationEntriesFrom(installed, (await import(pathToFileURL(migrationsEntry).href)));
+        const backend = await importSubpath(installed, 'backend');
+        // The root export again — the same dynamic import the composer path makes,
+        // so the ESM cache answers it and this costs no second read.
+        const manifestEntry = await manifestEntryFor(installed);
+        out.push({
+            id: installed.id,
+            packageName: installed.name,
+            version: installed.version,
+            migrationsDirectory: migrationsEntry === null ? null : dirname(migrationsEntry),
+            migrations,
+            entities: backend === null ? [] : entityClassesFrom(installed, backend),
+            dependencies: manifestEntry?.manifest.dependencies ?? [],
+        });
+    }
+    return out;
+}
+/**
+ * {@link packageSchemaContributionsUnder} over the roots this platform reads.
+ *
+ * Empty for an instance that installed no module package — every developer
+ * checkout and every test run — and empty means the ORM configuration is what
+ * it was before a package could ship schema at all.
+ */
+export async function discoverPackageSchema(env = process.env) {
+    return packageSchemaContributionsUnder(nodeModulesRootsFor(env));
+}
+//# sourceMappingURL=package-runtime.js.map

package/dist/packages/package-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-runtime.js","sourceRoot":"","sources":["../../src/packages/package-runtime.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,EAAE;AACF,0EAA0E;AAC1E,4EAA4E;AAC5E,+DAA+D;AAC/D,yEAAyE;AACzE,gFAAgF;AAChF,yEAAyE;AACzE,6DAA6D;AAC7D,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,8EAA8E;AAC9E,gFAAgF;AAChF,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,6DAA6D;AAC7D,2EAA2E;AAC3E,kDAAkD;AAClD,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,4CAA4C;AAC5C,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,8EAA8E;AAC9E,+EAA+E;AAC/E,2EAA2E;AAC3E,+EAA+E;AAC/E,8EAA8E;AAC9E,6EAA6E;AAC7E,yEAAyE;AACzE,oEAAoE;AACpE,8EAA8E;AAC9E,+EAA+E;AAC/E,0CAA0C;AAC1C,6EAA6E;AAC7E,gFAAgF;AAChF,8EAA8E;AAC9E,8EAA8E;AAC9E,6DAA6D;AAC7D,qEAAqE;AACrE,0EAA0E;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAIzC,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GAGrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,0BAA0B,GAE3B,MAAM,2CAA2C,CAAC;AA2EnD;;;;;;;;;;;GAWG;AACH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAgC,CAAC;AAEtD,SAAS,IAAI,CAAC,KAAwB;IACpC,yEAAyE;IACzE,6EAA6E;IAC7E,0EAA0E;IAC1E,6EAA6E;IAC7E,iEAAiE;IACjE,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC1C,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtB,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,8BAA8B,CAAC,KAAwB;IACrE,OAAO,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,SAAS,CAAC,QAAqC;IACtD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QAClC,EAAE,EAAE,SAAS,CAAC,EAAE;QAChB,MAAM,EAAE,SAAkB;QAC1B,SAAS,EAAE,SAAS,CAAC,YAAY;QACjC,IAAI,EAAE,SAAS,CAAC,IAAI;KACrB,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,cAAc,CAAC,SAA2B,EAAE,OAAe;IAClE,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;IAC9E,MAAM,SAAS,GAAG,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;IACpF,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,2EAA2E;QAC3E,4EAA4E;QAC5E,+DAA+D;QAC/D,yBAAyB;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,aAAa,CAC1B,SAA2B,EAC3B,OAAe;IAEf,MAAM,QAAQ,GAAG,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACpD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAA4B,CAAC;AACjF,CAAC;AAED,SAAS,YAAY,CAAC,MAA+B;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAuB,CAAC;IACxD,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACnC,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAE,QAA2B,CAAC;AAC3E,CAAC;AAED;;;;;;;;;GASG;AACH,KAAK,UAAU,gBAAgB,CAC7B,SAA2B;IAE3B,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACnD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,cAAc,SAAS,CAAC,IAAI,wBAAwB,SAAS,CAAC,EAAE,0BAA0B;YACxF,+EAA+E;YAC/E,4EAA4E;YAC5E,GAAG,SAAS,CAAC,YAAY,GAAG,CAC/B,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,iCAAiC,SAAS,CAAC,IAAI,4CAA4C;YACzF,oEAAoE;YACpE,GAAG,SAAS,CAAC,YAAY,GAAG,CAC/B,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS,CAAC,EAAE,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,cAAc,SAAS,CAAC,IAAI,+DAA+D;YACzF,mBAAmB,SAAS,CAAC,EAAE,4BAA4B,QAAQ,CAAC,EAAE,kBAAkB;YACxF,yFAAyF;YACzF,yFAAyF;YACzF,sDAAsD,SAAS,CAAC,YAAY,GAAG,CAClF,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAqD,CAAC;IAC9F,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAE/B,CAAC;IACd,MAAM,oBAAoB,GAAG,MAAM,CAAC,sBAAsB,CAE7C,CAAC;IACd,MAAM,WAAW,GAAG,MAAM,CAAC,aAAa,CAAqD,CAAC;IAC9F,MAAM,cAAc,GAAG,MAAM,CAAC,gBAAgB,CAEjC,CAAC;IAEd,OAAO;QACL,EAAE,EAAE,SAAS,CAAC,EAAE;QAChB,QAAQ;QACR,QAAQ,EAAE,SAAS,CAAC,YAAY;QAChC,WAAW,EAAE,SAAS,CAAC,IAAI;QAC3B,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3C,GAAG,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,oBAAoB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzD,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,KAAwB;IAExB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,0BAA0B,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IACtD,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvC,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,KAAK,KAAK,IAAI;YAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,KAAK,UAAU,8BAA8B,CAClD,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,2BAA2B,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAwB;IAExB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,0BAA0B,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtD,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC1D,yEAAyE;QACzE,4EAA4E;QAC5E,uEAAuE;QACvE,wEAAwE;QACxE,gCAAgC;QAChC,IAAI,OAAO,KAAK,IAAI;YAAE,SAAS;QAC/B,MAAM,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACjD,IAAI,OAAO,cAAc,KAAK,UAAU,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,wCAAwC,SAAS,CAAC,IAAI,gCAAgC;gBACpF,6DAA6D;gBAC7D,uFAAuF;gBACvF,wFAAwF;gBACxF,2DAA2D,SAAS,CAAC,YAAY,GAAG,CACvF,CAAC;QACJ,CAAC;QACD,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACxD,IAAI,aAAa,KAAK,IAAI;YAAE,SAAS;QACrC,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,SAAS,CAAC,EAAE;YAChB,OAAO,EAAE,aAAa,CAAC,QAAQ,CAAC,OAAO;YACvC,cAAc,EAAE,cAA+C;YAC/D,wEAAwE;YACxE,yEAAyE;YACzE,mBAAmB;YACnB,EAAE;YACF,uEAAuE;YACvE,oEAAoE;YACpE,wEAAwE;YACxE,0EAA0E;YAC1E,wEAAwE;YACxE,0EAA0E;YAC1E,0EAA0E;YAC1E,YAAY;YACZ,gBAAgB,EAAE,IAAI;SACvB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,yBAAyB,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7D,CAAC;AAsDD,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,oBAAoB,CAC3B,SAA2B,EAC3B,QAAiC;IAEjC,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,2CAA2C,SAAS,CAAC,IAAI,kCAAkC;YACzF,kFAAkF;YAClF,qFAAqF;YACrF,0CAA0C,SAAS,CAAC,YAAY,GAAG,CACtE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACnC,MAAM,SAAS,GAAY,aAAa,CAAC,KAAK,CAAC;YAC7C,CAAC,CAAC,KAAK;YACP,CAAC,CAAE,KAAoC,EAAE,KAAK,CAAC;QACjD,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CACb,oBAAoB,KAAK,oCAAoC,SAAS,CAAC,IAAI,cAAc;gBACvF,+DAA+D,SAAS,CAAC,YAAY,GAAG,CAC3F,CAAC;QACJ,CAAC;QACD,MAAM,YAAY,GAAY,aAAa,CAAC,KAAK,CAAC;YAChD,CAAC,CAAC,SAAS;YACX,CAAC,CAAE,KAA4B,CAAC,IAAI,CAAC;QACvC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YACxE,MAAM,IAAI,KAAK,CACb,2CAA2C,SAAS,CAAC,IAAI,sBAAsB;gBAC7E,IAAI,YAAY,wBAAwB,SAAS,CAAC,IAAI,0BAA0B;gBAChF,sFAAsF;gBACtF,iBAAiB,SAAS,CAAC,YAAY,GAAG,CAC7C,CAAC;QACJ,CAAC;QACD,OAAO;YACL,QAAQ,EAAE,SAAS,CAAC,EAAE;YACtB,GAAG,EAAE,SAA0C;YAC/C,sEAAsE;YACtE,yEAAyE;YACzE,sDAAsD;YACtD,MAAM,EAAE,UAAmB;SAC5B,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED,8EAA8E;AAC9E,SAAS,iBAAiB,CACxB,SAA2B,EAC3B,QAAiC;IAEjC,MAAM,QAAQ,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,wCAAwC,SAAS,CAAC,IAAI,qCAAqC;YACzF,kFAAkF;YAClF,GAAG,SAAS,CAAC,YAAY,GAAG,CAC/B,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACnC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,oBAAoB,KAAK,gCAAgC,SAAS,CAAC,IAAI,mBAAmB;gBACxF,iBAAiB,SAAS,CAAC,YAAY,GAAG,CAC7C,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,KAAwB;IAExB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,0BAA0B,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEtD,MAAM,GAAG,GAAgC,EAAE,CAAC;IAC5C,KAAK,MAAM,SAAS,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACvC,MAAM,eAAe,GAAG,cAAc,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;QAChE,MAAM,UAAU,GACd,eAAe,KAAK,IAAI;YACtB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,oBAAoB,CAClB,SAAS,EACT,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAA4B,CAC/E,CAAC;QACR,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC1D,2EAA2E;QAC3E,6DAA6D;QAC7D,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACxD,GAAG,CAAC,IAAI,CAAC;YACP,EAAE,EAAE,SAAS,CAAC,EAAE;YAChB,WAAW,EAAE,SAAS,CAAC,IAAI;YAC3B,OAAO,EAAE,SAAS,CAAC,OAAO;YAC1B,mBAAmB,EAAE,eAAe,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;YAC/E,UAAU;YACV,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,iBAAiB,CAAC,SAAS,EAAE,OAAO,CAAC;YACvE,YAAY,EAAE,aAAa,EAAE,QAAQ,CAAC,YAAY,IAAI,EAAE;SACzD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAyB,OAAO,CAAC,GAAG;IAEpC,OAAO,+BAA+B,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/tenancy/derived-scope.d.ts

@@ -0,0 +1,43 @@
+import { type TenantContext } from './tenant-context.js';
+/**
+ * Derived-scope helpers for entities with no direct tenant column
+ * (feature 050, research.md §R7):
+ *  - transitively-scoped (e.g. Invoice → Order.organizationId), and
+ *  - rule-scoped (e.g. price_lists targeted via applicationRule),
+ * whose admin queries must intersect the actor's org scope explicitly because the
+ * automatic column filter cannot reach them.
+ */
+/** The org restriction implied by the ambient context, as a discriminated union. */
+export type OrgConstraint = {
+    readonly kind: 'all';
+} | {
+    readonly kind: 'single';
+    readonly organizationId: string | null;
+} | {
+    readonly kind: 'set';
+    readonly organizationIds: readonly string[];
+};
+/** Compute the org constraint from a context (defaults to the ambient one). */
+export declare function orgConstraintFor(ctx?: TenantContext | undefined): OrgConstraint;
+/**
+ * Build a MikroORM `where` fragment that constrains an organization-id field to
+ * the ambient scope, for transitively/rule-scoped entities. `field` is the path
+ * to the org id (e.g. `'order.organizationId'` for Invoice, or `'organizationId'`).
+ * Returns `{}` (no restriction) for platform-admin / system scope.
+ */
+export declare function orgScopeWhere(field: string, ctx?: TenantContext): Record<string, unknown>;
+/**
+ * Whether the ambient scope may act on `organizationId`. Platform-admin/system
+ * see all; a single-org actor only their org; a scoped admin only assigned orgs.
+ * Use to gate writes (inserts) that the column filter cannot reach — respond
+ * indistinguishably from "not found" (FR-008) when this returns false.
+ */
+export declare function isOrgInScope(organizationId: string, ctx?: TenantContext): boolean;
+/**
+ * For rule-scoped entities (price_lists): given the set of organizations a rule
+ * targets, decide whether the ambient scope may see it. Platform-admin/system
+ * see everything; a scoped admin sees a rule only if it targets at least one of
+ * their assigned orgs (or targets no org at all — a channel/global rule).
+ */
+export declare function ruleVisibleForScope(ruleTargetOrgIds: readonly string[], ctx?: TenantContext): boolean;
+//# sourceMappingURL=derived-scope.d.ts.map

package/dist/tenancy/derived-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-scope.d.ts","sourceRoot":"","sources":["../../src/tenancy/derived-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+C,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEtG;;;;;;;GAOG;AAEH,oFAAoF;AACpF,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAE1E,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,aAAa,GAAG,SAA8B,GAAG,aAAa,CAgBnG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzF;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAUjF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,aAAa,GAAG,OAAO,CAarG"}

package/dist/tenancy/derived-scope.js

@@ -0,0 +1,76 @@
+import { getTenantContext, MissingTenantContextError } from './tenant-context.js';
+/** Compute the org constraint from a context (defaults to the ambient one). */
+export function orgConstraintFor(ctx = getTenantContext()) {
+    if (!ctx)
+        throw new MissingTenantContextError('derived-scope');
+    switch (ctx.mode) {
+        case 'all':
+        case 'system':
+            return { kind: 'all' };
+        case 'single-org':
+            // Null since D-178 only where `TenantContext`'s optional field is unset:
+            // a signed-in customer always carries an organisation, because
+            // `customer_accounts.organization_id` is `NOT NULL`. See
+            // `orgFilterCond`'s note in `filters.ts` — same coalesce, same reason it
+            // has no reachable caller.
+            return { kind: 'single', organizationId: ctx.organizationId ?? null };
+        case 'allowed-set':
+            return { kind: 'set', organizationIds: ctx.allowedOrganizationIds ?? [] };
+    }
+}
+/**
+ * Build a MikroORM `where` fragment that constrains an organization-id field to
+ * the ambient scope, for transitively/rule-scoped entities. `field` is the path
+ * to the org id (e.g. `'order.organizationId'` for Invoice, or `'organizationId'`).
+ * Returns `{}` (no restriction) for platform-admin / system scope.
+ */
+export function orgScopeWhere(field, ctx) {
+    const constraint = orgConstraintFor(ctx);
+    switch (constraint.kind) {
+        case 'all':
+            return {};
+        case 'single':
+            return { [field]: constraint.organizationId };
+        case 'set':
+            return { [field]: { $in: [...constraint.organizationIds] } };
+    }
+}
+/**
+ * Whether the ambient scope may act on `organizationId`. Platform-admin/system
+ * see all; a single-org actor only their org; a scoped admin only assigned orgs.
+ * Use to gate writes (inserts) that the column filter cannot reach — respond
+ * indistinguishably from "not found" (FR-008) when this returns false.
+ */
+export function isOrgInScope(organizationId, ctx) {
+    const constraint = orgConstraintFor(ctx);
+    switch (constraint.kind) {
+        case 'all':
+            return true;
+        case 'single':
+            return constraint.organizationId === organizationId;
+        case 'set':
+            return constraint.organizationIds.includes(organizationId);
+    }
+}
+/**
+ * For rule-scoped entities (price_lists): given the set of organizations a rule
+ * targets, decide whether the ambient scope may see it. Platform-admin/system
+ * see everything; a scoped admin sees a rule only if it targets at least one of
+ * their assigned orgs (or targets no org at all — a channel/global rule).
+ */
+export function ruleVisibleForScope(ruleTargetOrgIds, ctx) {
+    const constraint = orgConstraintFor(ctx);
+    switch (constraint.kind) {
+        case 'all':
+            return true;
+        case 'single':
+            return ruleTargetOrgIds.length === 0 || (constraint.organizationId != null && ruleTargetOrgIds.includes(constraint.organizationId));
+        case 'set': {
+            if (ruleTargetOrgIds.length === 0)
+                return true;
+            const allowed = new Set(constraint.organizationIds);
+            return ruleTargetOrgIds.some((id) => allowed.has(id));
+        }
+    }
+}
+//# sourceMappingURL=derived-scope.js.map

package/dist/tenancy/derived-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-scope.js","sourceRoot":"","sources":["../../src/tenancy/derived-scope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAsB,MAAM,qBAAqB,CAAC;AAiBtG,+EAA+E;AAC/E,MAAM,UAAU,gBAAgB,CAAC,MAAiC,gBAAgB,EAAE;IAClF,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,yBAAyB,CAAC,eAAe,CAAC,CAAC;IAC/D,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,QAAQ;YACX,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACzB,KAAK,YAAY;YACf,yEAAyE;YACzE,+DAA+D;YAC/D,yDAAyD;YACzD,yEAAyE;YACzE,2BAA2B;YAC3B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC;QACxE,KAAK,aAAa;YAChB,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,CAAC,sBAAsB,IAAI,EAAE,EAAE,CAAC;IAC9E,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa,EAAE,GAAmB;IAC9D,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACzC,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,KAAK;YACR,OAAO,EAAE,CAAC;QACZ,KAAK,QAAQ;YACX,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,cAAc,EAAE,CAAC;QAChD,KAAK,KAAK;YACR,OAAO,EAAE,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC,eAAe,CAAC,EAAE,EAAE,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,cAAsB,EAAE,GAAmB;IACtE,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACzC,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,KAAK;YACR,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,UAAU,CAAC,cAAc,KAAK,cAAc,CAAC;QACtD,KAAK,KAAK;YACR,OAAO,UAAU,CAAC,eAAe,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,gBAAmC,EAAE,GAAmB;IAC1F,MAAM,UAAU,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACzC,QAAQ,UAAU,CAAC,IAAI,EAAE,CAAC;QACxB,KAAK,KAAK;YACR,OAAO,IAAI,CAAC;QACd,KAAK,QAAQ;YACX,OAAO,gBAAgB,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,cAAc,IAAI,IAAI,IAAI,gBAAgB,CAAC,QAAQ,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC,CAAC;QACtI,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC/C,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;YACpD,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;QACxD,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/tenancy/escape-hatch.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The ONLY sanctioned way to cross organizations (feature 050, FR-005 / FR-013).
+ *
+ * `withSystemScope` / `withOrgScope` are the single greppable tokens for
+ * scope-widening; the CI check forbids any other means (raw `setFilterParams`
+ * / `disableFilter` outside this layer). Every call requires a non-empty
+ * `reason` and emits one audit record so cross-org access is observable.
+ */
+export interface EscapeHatchAuditRecord {
+    readonly scope: 'system' | 'org';
+    readonly reason: string;
+    readonly organizationId?: string;
+}
+export type EscapeHatchAuditSink = (record: EscapeHatchAuditRecord) => void;
+/** Wire the escape hatch to a real audit sink (e.g. AuditLogService). */
+export declare function setEscapeHatchAuditSink(sink: EscapeHatchAuditSink): void;
+/**
+ * Emit one escape-hatch audit record without entering a context.
+ *
+ * The kernel's `enterSystemScope` (feature 072) *starts* an execution that
+ * crosses organisations, where `withSystemScope` widens one that already exists.
+ * Both are cross-org access and both have to be observable, so the entry point
+ * reports through the same sink instead of growing a second, quieter one.
+ */
+export declare function recordEscapeHatchAudit(record: EscapeHatchAuditRecord): void;
+/** Run `fn` crossing ALL organizations (reporting, reconciliation, migrations). */
+export declare function withSystemScope<T>(reason: string, fn: () => Promise<T>): Promise<T>;
+/** Run `fn` pinned to a single organization (e.g. a per-org background job). */
+export declare function withOrgScope<T>(organizationId: string, reason: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=escape-hatch.d.ts.map

package/dist/tenancy/escape-hatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-hatch.d.ts","sourceRoot":"","sources":["../../src/tenancy/escape-hatch.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,KAAK,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;AAmB5E,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAExE;AAQD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI,CAG3E;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAInF;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAIxG"}

package/dist/tenancy/escape-hatch.js

@@ -0,0 +1,50 @@
+import { runWithTenantContext } from './tenant-context.js';
+import { systemTenantContext, orgPinnedTenantContext } from './resolve-tenant-context.js';
+/**
+ * Default sink: one structured line on **stderr**. Composition may replace it
+ * with one that writes to AuditLogService (FR-013).
+ *
+ * stderr and not stdout, since feature 072 (T035): the CLI scripts now open
+ * their scope through `enterSystemScope`, which reports here, and several of
+ * them (`module:install --json` and friends) treat stdout as a machine-readable
+ * data channel. An audit line printed there is not a log entry, it is corrupt
+ * output. Nothing consumes this on stdout — in the server both streams land in
+ * the same log.
+ */
+let auditSink = (record) => {
+    process.stderr.write(`${JSON.stringify({ level: 'info', msg: 'tenant.escape_hatch', ...record })}\n`);
+};
+/** Wire the escape hatch to a real audit sink (e.g. AuditLogService). */
+export function setEscapeHatchAuditSink(sink) {
+    auditSink = sink;
+}
+function requireReason(reason) {
+    if (!reason || reason.trim().length === 0) {
+        throw new Error('withSystemScope/withOrgScope requires a non-empty reason (feature 050, FR-005).');
+    }
+}
+/**
+ * Emit one escape-hatch audit record without entering a context.
+ *
+ * The kernel's `enterSystemScope` (feature 072) *starts* an execution that
+ * crosses organisations, where `withSystemScope` widens one that already exists.
+ * Both are cross-org access and both have to be observable, so the entry point
+ * reports through the same sink instead of growing a second, quieter one.
+ */
+export function recordEscapeHatchAudit(record) {
+    requireReason(record.reason);
+    auditSink(record);
+}
+/** Run `fn` crossing ALL organizations (reporting, reconciliation, migrations). */
+export function withSystemScope(reason, fn) {
+    requireReason(reason);
+    auditSink({ scope: 'system', reason });
+    return runWithTenantContext(systemTenantContext(reason), fn);
+}
+/** Run `fn` pinned to a single organization (e.g. a per-org background job). */
+export function withOrgScope(organizationId, reason, fn) {
+    requireReason(reason);
+    auditSink({ scope: 'org', reason, organizationId });
+    return runWithTenantContext(orgPinnedTenantContext(organizationId, reason), fn);
+}
+//# sourceMappingURL=escape-hatch.js.map

package/dist/tenancy/escape-hatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-hatch.js","sourceRoot":"","sources":["../../src/tenancy/escape-hatch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAmB1F;;;;;;;;;;GAUG;AACH,IAAI,SAAS,GAAyB,CAAC,MAAM,EAAE,EAAE;IAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,EAAE,GAAG,MAAM,EAAE,CAAC,IAAI,CAChF,CAAC;AACJ,CAAC,CAAC;AAEF,yEAAyE;AACzE,MAAM,UAAU,uBAAuB,CAAC,IAA0B;IAChE,SAAS,GAAG,IAAI,CAAC;AACnB,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,iFAAiF,CAAC,CAAC;IACrG,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA8B;IACnE,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAI,MAAc,EAAE,EAAoB;IACrE,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,SAAS,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACvC,OAAO,oBAAoB,CAAC,mBAAmB,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAI,cAAsB,EAAE,MAAc,EAAE,EAAoB;IAC1F,aAAa,CAAC,MAAM,CAAC,CAAC;IACtB,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;IACpD,OAAO,oBAAoB,CAAC,sBAAsB,CAAC,cAAc,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;AAClF,CAAC"}