@weaveintel/realm 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @weaveintel/realm
+
+**One default for everyone, a private copy for anyone — resolved correctly, with a paper trail.**
+
+## Why it exists
+
+Ship a piece of configuration once — a prompt, a guardrail, a skill — and in a multi-tenant product
+you immediately want three things that fight each other:
+
+1. a **global default** everyone gets out of the box,
+2. the ability for one customer to **tweak their own copy** without touching anybody else's, and
+3. a way, later, to tell whether that tweak has **drifted** from the default it was based on — so a
+   product update never silently clobbers a customer's edits, and never leaves them stuck on a stale one.
+
+`@weaveintel/realm` gives you exactly that, and the drift check is the same three-way (base / yours /
+theirs) comparison git uses for a merge — just applied to configuration. It runs identically on SQLite
+and Postgres, and builds on the tenant tree from `@weaveintel/identity`.
+
+## The mental model
+
+- A **global** record is the shared default.
+- A tenant can **customize** — that makes a private copy (copy-on-write) that remembers where it came from.
+- A tenant can **share** its copy down its part of the org tree, so a parent company's choice flows to
+  its subsidiaries.
+- When someone asks for a config, resolution picks the **nearest owner**: your own copy beats a parent's
+  shared copy, which beats the global default.
+
+## Quickstart
+
+```ts
+import { createInMemoryRealmStore, createRealmResolver } from '@weaveintel/realm';
+import { createInMemoryTenantHierarchy, } from '@weaveintel/identity';
+import { buildRealmContext } from '@weaveintel/realm';
+
+const store = createInMemoryRealmStore();        // or the SQL-backed store (SQLite/Postgres)
+const resolver = createRealmResolver({ store });
+
+// 1) The product publishes a global default.
+await store.publishGlobal('assistant.general', { template: 'You are a helpful assistant.' });
+
+// 2) A tenant customizes their own copy.
+const org = createInMemoryTenantHierarchy();
+const acme = await org.create({ id: 'acme', name: 'Acme' });
+const ctx = await buildRealmContext(org, 'acme');
+await store.customize('assistant.general', ctx, { template: 'You are Acme’s in-house assistant.' });
+
+// 3) Resolution gives each caller the right one, and says where it came from.
+const forAcme = await resolver.resolve('assistant.general', ctx);
+forAcme.template          // 'You are Acme’s in-house assistant.'
+forAcme.realmProvenance   // { kind: 'own_override', drift: 'in_sync' }
+
+const forSomeoneElse = await resolver.resolve('assistant.general', await buildRealmContext(org, 'other'));
+forSomeoneElse.realmProvenance.kind  // 'global'  — untouched tenants still get the default
+```
+
+### Provenance — every resolved record says where it came from
+
+- `{ kind: 'global' }` — the shared default.
+- `{ kind: 'native', ownerTenantId }` — a record this tenant authored from scratch (no global equivalent).
+- `{ kind: 'own_override', ownerTenantId, drift }` — this tenant's own edited copy (+ its drift state).
+- `{ kind: 'inherited', fromTenantId, distance }` — a parent/ancestor's shared copy, `distance` levels up.
+
+Stamp it into your run traces and you can always answer *"which prompt version produced this output for
+this tenant?"*.
+
+### Drift — has a customization gone stale, or diverged?
+
+`drift` on an override is one of:
+
+| drift | meaning |
+|---|---|
+| `in_sync` | your copy is unchanged and the default is unchanged — identical |
+| `customized` | you edited it; the default hasn't moved — your change is the only difference |
+| `stale` | you didn't touch it; the default moved on — safe to refresh in one click |
+| `diverged` | both changed — needs a real look (a merge) |
+
+This is the exact same signal for two problems: *"a tenant customized a built-in"* and *"a package update
+changed a default a tenant was using."*
+
+### Sharing down the tree
+
+```ts
+const edit = await store.customize('brand.tone', parentCtx, { tone: 'formal' });
+await store.setShareMode(edit.id, 'subtree'); // now every subsidiary inherits it (unless they have their own)
+```
+
+`private` (default) keeps it to yourself, `children` shares to direct children only, `subtree` shares to
+your whole branch. A parent's *private* copy stays invisible to children — privacy hides the customization,
+never the concept.
+
+## Backing it with a real database
+
+The SQL store speaks to any client with a `query(text, params) → { rows }` method — a `pg.Pool` fits
+directly; for SQLite, wrap `better-sqlite3` in a few lines. The visibility rule (who may see which copy)
+is one WHERE clause — no recursive SQL — so SQLite and Postgres behave identically (proven by the same
+conformance test running against both).
+
+```ts
+import { createSqlRealmStore } from '@weaveintel/realm';
+import pg from 'pg';
+const store = createSqlRealmStore({ client: new pg.Pool({ connectionString: process.env.DATABASE_URL }), dialect: 'postgres' });
+```
+
+## License
+
+MIT.

package/dist/context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Realm context — "who is asking, and where do they sit in the tenant tree?"
+ *
+ * Resolution needs the asking tenant's lineage (itself + its ancestors, each with a depth) so it can
+ * pick the *nearest* owner of a config and decide what a parent has chosen to share downward. That
+ * lineage comes straight from the Phase 0 tenant hierarchy (`@weaveintel/identity`).
+ */
+import type { TenantHierarchyStore } from '@weaveintel/identity';
+/** One tenant on the lineage from root to the asking tenant. */
+export interface LineageNode {
+    readonly tenantId: string;
+    /** Depth in the tree — roots are 0, deeper is larger. */
+    readonly depth: number;
+}
+/**
+ * The asking tenant's position. `lineage` runs root → … → self (self is the last element). A "system"
+ * / global caller has `tenantId: null` and an empty lineage — it sees only global records.
+ */
+export interface RealmContext {
+    readonly tenantId: string | null;
+    readonly depth: number;
+    /** root → self; ancestors are all but the last. */
+    readonly lineage: readonly LineageNode[];
+}
+/** The global/system context — sees only global records, no tenant overrides. */
+export declare const GLOBAL_CONTEXT: RealmContext;
+/** Immediate parent tenant id, or null at a root. */
+export declare function parentTenantId(ctx: RealmContext): string | null;
+/** Ancestor tenant ids ABOVE the immediate parent (grandparent → root). */
+export declare function strictGrandAncestorIds(ctx: RealmContext): string[];
+/** Depth of a given owner tenant id within this context's lineage, or undefined if not an ancestor/self. */
+export declare function ownerDepth(ctx: RealmContext, ownerTenantId: string | null): number | undefined;
+/**
+ * Build a context from the tenant hierarchy: fetch the tenant and its ancestors, ordered root → self.
+ * Pass `null` for the global/system caller.
+ */
+export declare function buildRealmContext(hierarchy: TenantHierarchyStore, tenantId: string | null): Promise<RealmContext>;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;CAC1C;AAED,iFAAiF;AACjF,eAAO,MAAM,cAAc,EAAE,YAAyD,CAAC;AAEvF,qDAAqD;AACrD,wBAAgB,cAAc,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAE/D;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,EAAE,CAElE;AAED,4GAA4G;AAC5G,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAG9F;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,oBAAoB,EAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC,YAAY,CAAC,CAUvB"}

package/dist/context.js

@@ -0,0 +1,34 @@
+/** The global/system context — sees only global records, no tenant overrides. */
+export const GLOBAL_CONTEXT = { tenantId: null, depth: -1, lineage: [] };
+/** Immediate parent tenant id, or null at a root. */
+export function parentTenantId(ctx) {
+    return ctx.lineage.length >= 2 ? ctx.lineage[ctx.lineage.length - 2].tenantId : null;
+}
+/** Ancestor tenant ids ABOVE the immediate parent (grandparent → root). */
+export function strictGrandAncestorIds(ctx) {
+    return ctx.lineage.slice(0, Math.max(0, ctx.lineage.length - 2)).map((n) => n.tenantId);
+}
+/** Depth of a given owner tenant id within this context's lineage, or undefined if not an ancestor/self. */
+export function ownerDepth(ctx, ownerTenantId) {
+    if (ownerTenantId == null)
+        return undefined; // global
+    return ctx.lineage.find((n) => n.tenantId === ownerTenantId)?.depth;
+}
+/**
+ * Build a context from the tenant hierarchy: fetch the tenant and its ancestors, ordered root → self.
+ * Pass `null` for the global/system caller.
+ */
+export async function buildRealmContext(hierarchy, tenantId) {
+    if (tenantId == null)
+        return GLOBAL_CONTEXT;
+    const self = await hierarchy.get(tenantId);
+    if (!self)
+        throw new Error(`buildRealmContext: tenant ${JSON.stringify(tenantId)} not found.`);
+    const ancestors = await hierarchy.ancestors(tenantId); // root → parent
+    const lineage = [
+        ...ancestors.map((a) => ({ tenantId: a.id, depth: a.depth })),
+        { tenantId: self.id, depth: self.depth },
+    ];
+    return { tenantId, depth: self.depth, lineage };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AA4BA,iFAAiF;AACjF,MAAM,CAAC,MAAM,cAAc,GAAiB,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;AAEvF,qDAAqD;AACrD,MAAM,UAAU,cAAc,CAAC,GAAiB;IAC9C,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;AACxF,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,sBAAsB,CAAC,GAAiB;IACtD,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;AAC1F,CAAC;AAED,4GAA4G;AAC5G,MAAM,UAAU,UAAU,CAAC,GAAiB,EAAE,aAA4B;IACxE,IAAI,aAAa,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC,CAAC,SAAS;IACtD,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,aAAa,CAAC,EAAE,KAAK,CAAC;AACtE,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,SAA+B,EAC/B,QAAuB;IAEvB,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,cAAc,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;IAC/F,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB;IACvE,MAAM,OAAO,GAAkB;QAC7B,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;QAC7D,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE;KACzC,CAAC;IACF,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @weaveintel/realm — resolve the effective configuration for a tenant across a global→tenant
+ * hierarchy, with provenance and git-style drift. Phase 1 of the tenancy realm design.
+ */
+export * from './realm-record.js';
+export * from './context.js';
+export * from './resolve.js';
+export * from './realm-store.js';
+export * from './realm-store-sql.js';
+export * from './realm-contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA;;;GAGG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: MIT
+/**
+ * @weaveintel/realm — resolve the effective configuration for a tenant across a global→tenant
+ * hierarchy, with provenance and git-style drift. Phase 1 of the tenancy realm design.
+ */
+export * from './realm-record.js';
+export * from './context.js';
+export * from './resolve.js';
+export * from './realm-store.js';
+export * from './realm-store-sql.js';
+export * from './realm-contract.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B;;;GAGG;AACH,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC"}

package/dist/realm-contract.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Conformance contract for any `RealmConfigStore` + the resolver on top of it. Framework-agnostic:
+ * returns pass/fail results. The in-memory store and the SQL store (SQLite + Postgres) all run this
+ * exact suite. Contexts are supplied by the caller (built from a tenant tree) so the store stays
+ * decoupled from identity.
+ */
+import { type RealmConfigStore } from './realm-store.js';
+import type { RealmContext } from './context.js';
+export interface ContractCheck {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly error?: string;
+}
+export declare function realmContractPassed(r: ContractCheck[]): boolean;
+/**
+ * The fixed tenant tree the contract resolves against:
+ *   acme (root, d0) → emea (d1) → uk (d2)
+ *   acme → apac (d1)
+ * Contexts are hand-built so no identity dependency is needed.
+ */
+export declare const CTX: {
+    global: RealmContext;
+    acme: RealmContext;
+    emea: RealmContext;
+    uk: RealmContext;
+    apac: RealmContext;
+};
+export interface RealmContractOptions {
+    readonly makeStore: () => Promise<RealmConfigStore> | RealmConfigStore;
+    readonly cleanup?: (s: RealmConfigStore) => Promise<void> | void;
+}
+export declare function runRealmContract(opts: RealmContractOptions): Promise<ContractCheck[]>;
+//# sourceMappingURL=realm-contract.d.ts.map

package/dist/realm-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-contract.d.ts","sourceRoot":"","sources":["../src/realm-contract.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AACH,OAAO,EAAqC,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC5F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAGjD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AACD,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,OAAO,CAE/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,GAAG;YACwC,YAAY;UACiB,YAAY;UAK1F,YAAY;QAKZ,YAAY;UAKZ,YAAY;CAClB,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;IACvE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAClE;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAgK3F"}

package/dist/realm-contract.js

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Conformance contract for any `RealmConfigStore` + the resolver on top of it. Framework-agnostic:
+ * returns pass/fail results. The in-memory store and the SQL store (SQLite + Postgres) all run this
+ * exact suite. Contexts are supplied by the caller (built from a tenant tree) so the store stays
+ * decoupled from identity.
+ */
+import { createRealmResolver } from './realm-store.js';
+import { driftState } from './realm-record.js';
+export function realmContractPassed(r) {
+    return r.length > 0 && r.every((x) => x.ok);
+}
+/**
+ * The fixed tenant tree the contract resolves against:
+ *   acme (root, d0) → emea (d1) → uk (d2)
+ *   acme → apac (d1)
+ * Contexts are hand-built so no identity dependency is needed.
+ */
+export const CTX = {
+    global: { tenantId: null, depth: -1, lineage: [] },
+    acme: { tenantId: 'acme', depth: 0, lineage: [{ tenantId: 'acme', depth: 0 }] },
+    emea: {
+        tenantId: 'emea',
+        depth: 1,
+        lineage: [{ tenantId: 'acme', depth: 0 }, { tenantId: 'emea', depth: 1 }],
+    },
+    uk: {
+        tenantId: 'uk',
+        depth: 2,
+        lineage: [{ tenantId: 'acme', depth: 0 }, { tenantId: 'emea', depth: 1 }, { tenantId: 'uk', depth: 2 }],
+    },
+    apac: {
+        tenantId: 'apac',
+        depth: 1,
+        lineage: [{ tenantId: 'acme', depth: 0 }, { tenantId: 'apac', depth: 1 }],
+    },
+};
+export async function runRealmContract(opts) {
+    const results = [];
+    const check = async (name, fn) => {
+        let s;
+        try {
+            s = await opts.makeStore();
+            await fn(s);
+            results.push({ name, ok: true });
+        }
+        catch (e) {
+            results.push({ name, ok: false, error: e instanceof Error ? `${e.name}: ${e.message}` : String(e) });
+        }
+        finally {
+            if (s && opts.cleanup)
+                await opts.cleanup(s);
+        }
+    };
+    const eq = (a, b, m) => {
+        if (JSON.stringify(a) !== JSON.stringify(b))
+            throw new Error(`${m} — expected ${JSON.stringify(b)}, got ${JSON.stringify(a)}`);
+    };
+    const rejects = async (fn, m) => {
+        try {
+            await fn();
+        }
+        catch {
+            return;
+        }
+        throw new Error(`${m} — did not throw`);
+    };
+    // ── global-only world (single-org / community): everyone gets the default ────────────────────────
+    await check('global default resolves for every tenant when nobody has customized', async (s) => {
+        await s.publishGlobal('assistant.general', { template: 'You are helpful.' });
+        const r = createRealmResolver({ store: s });
+        for (const ctx of [CTX.global, CTX.acme, CTX.emea, CTX.uk]) {
+            const eff = await r.resolve('assistant.general', ctx);
+            eq([eff?.['template'], eff?.realmProvenance.kind], ['You are helpful.', 'global'], `resolve for ${ctx.tenantId}`);
+        }
+    });
+    // ── own override wins over global, only for its owner ────────────────────────────────────────────
+    await check("a tenant's own customization wins for it — and nobody else sees it", async (s) => {
+        await s.publishGlobal('assistant.general', { template: 'GLOBAL' });
+        await s.customize('assistant.general', CTX.uk, { template: 'UK EDIT' });
+        const r = createRealmResolver({ store: s });
+        eq((await r.resolve('assistant.general', CTX.uk))?.['template'], 'UK EDIT', 'uk sees its edit');
+        eq((await r.resolve('assistant.general', CTX.uk))?.realmProvenance.kind, 'own_override', 'provenance own_override');
+        eq((await r.resolve('assistant.general', CTX.emea))?.['template'], 'GLOBAL', 'sibling/parent still global');
+        eq((await r.resolve('assistant.general', CTX.apac))?.['template'], 'GLOBAL', 'unrelated tenant still global');
+    });
+    // ── nearest owner wins, and privacy hides the parent's copy ──────────────────────────────────────
+    await check('nearest owner wins; a parent PRIVATE override is invisible to children', async (s) => {
+        await s.publishGlobal('k', { v: 'GLOBAL' });
+        await s.customize('k', CTX.emea, { v: 'EMEA EDIT' }); // private by default
+        const r = createRealmResolver({ store: s });
+        // uk is emea's child, but emea's edit is private → uk falls through to global.
+        eq((await r.resolve('k', CTX.uk))?.['v'], 'GLOBAL', 'private parent override hidden → global');
+        eq((await r.resolve('k', CTX.emea))?.['v'], 'EMEA EDIT', 'emea sees its own');
+    });
+    await check("a parent's SHARED override is inherited by descendants (nearest wins over global)", async (s) => {
+        await s.publishGlobal('k', { v: 'GLOBAL' });
+        const emeaEdit = await s.customize('k', CTX.emea, { v: 'EMEA SHARED' });
+        await s.setShareMode(emeaEdit.id, 'subtree');
+        const r = createRealmResolver({ store: s });
+        const uk = await r.resolve('k', CTX.uk);
+        eq(uk?.['v'], 'EMEA SHARED', 'uk inherits the shared parent override');
+        eq(uk?.realmProvenance.kind, 'inherited', 'provenance inherited');
+        eq((uk?.realmProvenance).distance, 1, 'distance = 1 level up');
+        // apac is not under emea → still global.
+        eq((await r.resolve('k', CTX.apac))?.['v'], 'GLOBAL', 'cousin unaffected');
+    });
+    await check("'children' share reaches only direct children, not grandchildren", async (s) => {
+        await s.publishGlobal('k', { v: 'GLOBAL' });
+        const acmeEdit = await s.customize('k', CTX.acme, { v: 'ACME CHILDREN' });
+        await s.setShareMode(acmeEdit.id, 'children');
+        const r = createRealmResolver({ store: s });
+        eq((await r.resolve('k', CTX.emea))?.['v'], 'ACME CHILDREN', 'direct child inherits');
+        eq((await r.resolve('k', CTX.uk))?.['v'], 'GLOBAL', 'grandchild does NOT (children-only)');
+    });
+    // ── own override closer than a shared ancestor override ──────────────────────────────────────────
+    await check('own override beats an inherited shared override', async (s) => {
+        await s.publishGlobal('k', { v: 'GLOBAL' });
+        const acmeEdit = await s.customize('k', CTX.acme, { v: 'ACME' });
+        await s.setShareMode(acmeEdit.id, 'subtree');
+        await s.customize('k', CTX.uk, { v: 'UK' });
+        const r = createRealmResolver({ store: s });
+        eq((await r.resolve('k', CTX.uk))?.['v'], 'UK', "uk's own beats acme's shared");
+        eq((await r.resolve('k', CTX.emea))?.['v'], 'ACME', 'emea (no own) inherits acme shared');
+    });
+    // ── native records (no global equivalent) ────────────────────────────────────────────────────────
+    await check('a tenant-native record (no global) resolves as native', async (s) => {
+        await s.putNative('tenant.only', 'uk', { v: 'UK ONLY' });
+        const r = createRealmResolver({ store: s });
+        eq((await r.resolve('tenant.only', CTX.uk))?.realmProvenance.kind, 'native', 'native provenance');
+        eq(await r.resolve('tenant.only', CTX.apac), null, 'invisible to others (no global)');
+    });
+    // ── drift (Base / Local / Remote) ────────────────────────────────────────────────────────────────
+    await check('drift: in_sync → customized → stale → diverged', async (s) => {
+        await s.publishGlobal('k', { v: 'V1' }); // base
+        await s.customize('k', CTX.uk, { v: 'V1' }); // fork with identical content → in_sync
+        const r = createRealmResolver({ store: s });
+        const prov = async () => (await r.resolve('k', CTX.uk)).realmProvenance.drift;
+        eq(await prov(), 'in_sync', 'fork identical to base');
+        await s.customize('k', CTX.uk, { v: 'V1-uk' }); // local edit
+        eq(await prov(), 'customized', 'local edit, source unchanged');
+        await s.customize('k', CTX.uk, { v: 'V1' }); // revert local to base
+        await s.publishGlobal('k', { v: 'V2' }); // source moves on
+        eq(await prov(), 'stale', 'local unchanged, source moved');
+        await s.customize('k', CTX.uk, { v: 'V2-uk' }); // and now local edits too
+        eq(await prov(), 'diverged', 'both changed');
+    });
+    await check('listEffective returns exactly one record per logical key', async (s) => {
+        await s.publishGlobal('a', { v: 'A' });
+        await s.publishGlobal('b', { v: 'B' });
+        await s.customize('a', CTX.uk, { v: 'A-uk' });
+        const r = createRealmResolver({ store: s });
+        const eff = await r.listEffective(CTX.uk);
+        eq(eff.map((e) => e.logicalKey), ['a', 'b'], 'one per key, sorted');
+        eq(eff.map((e) => e.realmProvenance.kind), ['own_override', 'global'], 'a=own, b=global');
+    });
+    // ── negative ─────────────────────────────────────────────────────────────────────────────────────
+    await check('customize with nothing to fork throws', async (s) => {
+        await rejects(() => s.customize('missing.key', CTX.uk, { v: 'x' }), 'no base');
+    });
+    await check('global caller sees only global records', async (s) => {
+        await s.publishGlobal('k', { v: 'G' });
+        await s.putNative('k2', 'uk', { v: 'UK' });
+        const r = createRealmResolver({ store: s });
+        eq((await r.resolve('k', CTX.global))?.['v'], 'G', 'global visible');
+        eq(await r.resolve('k2', CTX.global), null, 'tenant-native invisible to global');
+    });
+    // ── security / isolation ─────────────────────────────────────────────────────────────────────────
+    await check('SECURITY: sibling tenants cannot read each other’s private overrides', async (s) => {
+        await s.publishGlobal('secret.prompt', { v: 'GLOBAL' });
+        await s.customize('secret.prompt', CTX.emea, { v: 'EMEA CONFIDENTIAL' });
+        await s.customize('secret.prompt', CTX.apac, { v: 'APAC CONFIDENTIAL' });
+        const r = createRealmResolver({ store: s });
+        eq((await r.resolve('secret.prompt', CTX.emea))?.['v'], 'EMEA CONFIDENTIAL', 'emea sees own');
+        eq((await r.resolve('secret.prompt', CTX.apac))?.['v'], 'APAC CONFIDENTIAL', 'apac sees own');
+        // Neither leaks to the other; a child of emea never sees apac's, and vice-versa.
+        eq((await r.resolve('secret.prompt', CTX.uk))?.['v'], 'GLOBAL', "emea's child sees neither sibling's secret");
+        const visForApac = await s.listVisible(CTX.apac, ['secret.prompt']);
+        eq(visForApac.some((x) => x.v === 'EMEA CONFIDENTIAL'), false, 'apac candidate set excludes emea secret');
+    });
+    await check('drift helper matches the state table', () => {
+        eq(driftState('B', 'B', 'B'), 'in_sync', 'in_sync');
+        eq(driftState('B', 'L', 'B'), 'customized', 'customized');
+        eq(driftState('B', 'B', 'R'), 'stale', 'stale');
+        eq(driftState('B', 'L', 'R'), 'diverged', 'diverged');
+        eq(driftState(null, 'L', 'R'), 'not_a_fork', 'no base');
+        return Promise.resolve();
+    });
+    return results;
+}
+//# sourceMappingURL=realm-contract.js.map

package/dist/realm-contract.js.map

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

package/dist/realm-record.d.ts

@@ -0,0 +1,51 @@
+/** Is this a shared global default, or a tenant's own copy? */
+export type RealmClass = 'global' | 'tenant';
+/** How far down the tree a tenant's own record is offered to its descendants. */
+export type ShareMode = 'private' | 'children' | 'subtree';
+/** Whether a forked copy stays pinned to the version it forked, or auto-follows the source. */
+export type TrackMode = 'pin' | 'track_latest';
+/** The realm columns every realm-enabled config row gains. */
+export interface RealmFields {
+    /** 'global' = a shared default; 'tenant' = a specific tenant's copy. */
+    realm: RealmClass;
+    /** The owning tenant's id. NULL exactly when realm='global'. */
+    ownerTenantId: string | null;
+    /** The stable identity of the config across copies (e.g. a prompt's key). References use this. */
+    logicalKey: string;
+    /** The row this was forked from (a global default, or a parent's shared copy). NULL for originals/natives. */
+    originId: string | null;
+    /** The origin's content hash AT FORK TIME — the "Base" in a three-way drift check. */
+    originHash: string | null;
+    /** Hash of this row's own semantic content — the "Local". */
+    contentHash: string;
+    /** Pinned to the fork point, or auto-following the source. */
+    trackMode: TrackMode;
+    /** Sharing reach down the tenant tree. */
+    shareMode: ShareMode;
+}
+/** A config row = the app's own payload columns plus the realm fields plus an id. */
+export type RealmRecord<T = Record<string, unknown>> = T & RealmFields & {
+    id: string;
+};
+/** The three shapes a realm row can take, distinguished by (realm, originId). */
+export type RealmArchetype = 'global_original' | 'tenant_override' | 'tenant_native';
+/** Classify a row: a shared default, a fork of one, or a tenant's from-scratch record. */
+export declare function archetypeOf(f: Pick<RealmFields, 'realm' | 'originId'>): RealmArchetype;
+/**
+ * Deterministic content hash over just the *semantic* fields (the substance — a prompt's template &
+ * variables, NOT its id, timestamps, enabled flag or realm columns). Stable across key order and
+ * environments, so two rows with the same meaning hash the same on any machine or database.
+ */
+export declare function computeContentHash(semantic: Record<string, unknown>): string;
+/** Canonical JSON: object keys sorted recursively so hashing is order-independent. */
+export declare function canonicalize(value: unknown): string;
+/** The four drift states of a tenant's forked copy versus the default it came from. */
+export type DriftState = 'in_sync' | 'customized' | 'stale' | 'diverged';
+/**
+ * The three-way drift check — Base = the hash at fork time, Local = this copy's current hash, Remote =
+ * the source's current hash. Exactly git's merge logic, for config.
+ */
+export declare function driftState(base: string | null, local: string, remote: string | null): DriftState | 'not_a_fork';
+/** Default realm fields for a brand-new GLOBAL original (what a package seed publishes). */
+export declare function globalOriginalFields(logicalKey: string, contentHash: string): RealmFields;
+//# sourceMappingURL=realm-record.d.ts.map

package/dist/realm-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-record.d.ts","sourceRoot":"","sources":["../src/realm-record.ts"],"names":[],"mappings":"AAiBA,+DAA+D;AAC/D,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE7C,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAE3D,+FAA+F;AAC/F,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,cAAc,CAAC;AAE/C,8DAA8D;AAC9D,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC;IAClB,gEAAgE;IAChE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;IACnB,8GAA8G;IAC9G,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sFAAsF;IACtF,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,SAAS,EAAE,SAAS,CAAC;IACrB,0CAA0C;IAC1C,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,qFAAqF;AACrF,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAErF,0FAA0F;AAC1F,wBAAgB,WAAW,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,cAAc,CAGtF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAE5E;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEnD;AAWD,uFAAuF;AACvF,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,YAAY,GACZ,OAAO,GACP,UAAU,CAAC;AAEf;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,UAAU,GAAG,YAAY,CAQ/G;AAED,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW,CAWzF"}

package/dist/realm-record.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+/**
+ * Realm records — the small set of columns a *configuration* row carries so it can live in a
+ * global→tenant hierarchy.
+ *
+ * Think of any piece of shipped configuration — a prompt template, a skill, a guardrail. In a single
+ * product there's one copy. In a multi-tenant product you want three things at once:
+ *   1. a **global** default everyone gets,
+ *   2. the ability for a tenant to **customize** its own copy (without touching anyone else's), and
+ *   3. a way to tell, later, whether that customized copy has drifted from the default it was forked
+ *      from — so a product update doesn't silently clobber a customer's edits (or leave them stale).
+ *
+ * These fields make that possible, and the drift check is the exact same three-way (Base / Local /
+ * Remote) comparison git uses for a merge — just applied to configuration instead of source files.
+ */
+import { createHash } from 'node:crypto';
+/** Classify a row: a shared default, a fork of one, or a tenant's from-scratch record. */
+export function archetypeOf(f) {
+    if (f.realm === 'global')
+        return 'global_original';
+    return f.originId == null ? 'tenant_native' : 'tenant_override';
+}
+/**
+ * Deterministic content hash over just the *semantic* fields (the substance — a prompt's template &
+ * variables, NOT its id, timestamps, enabled flag or realm columns). Stable across key order and
+ * environments, so two rows with the same meaning hash the same on any machine or database.
+ */
+export function computeContentHash(semantic) {
+    return `sha256:${createHash('sha256').update(canonicalize(semantic), 'utf8').digest('hex')}`;
+}
+/** Canonical JSON: object keys sorted recursively so hashing is order-independent. */
+export function canonicalize(value) {
+    return JSON.stringify(sortDeep(value));
+}
+function sortDeep(v) {
+    if (Array.isArray(v))
+        return v.map(sortDeep);
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v).sort())
+            out[k] = sortDeep(v[k]);
+        return out;
+    }
+    return v;
+}
+/**
+ * The three-way drift check — Base = the hash at fork time, Local = this copy's current hash, Remote =
+ * the source's current hash. Exactly git's merge logic, for config.
+ */
+export function driftState(base, local, remote) {
+    if (base == null || remote == null)
+        return 'not_a_fork'; // an original/native has nothing to drift from
+    const localChanged = local !== base;
+    const remoteChanged = remote !== base;
+    if (!localChanged && !remoteChanged)
+        return 'in_sync';
+    if (localChanged && !remoteChanged)
+        return 'customized';
+    if (!localChanged && remoteChanged)
+        return 'stale';
+    return 'diverged';
+}
+/** Default realm fields for a brand-new GLOBAL original (what a package seed publishes). */
+export function globalOriginalFields(logicalKey, contentHash) {
+    return {
+        realm: 'global',
+        ownerTenantId: null,
+        logicalKey,
+        originId: null,
+        originHash: null,
+        contentHash,
+        trackMode: 'pin',
+        shareMode: 'private',
+    };
+}
+//# sourceMappingURL=realm-record.js.map

package/dist/realm-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realm-record.js","sourceRoot":"","sources":["../src/realm-record.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAqCzC,0FAA0F;AAC1F,MAAM,UAAU,WAAW,CAAC,CAA0C;IACpE,IAAI,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,iBAAiB,CAAC;IACnD,OAAO,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,CAAC;AAClE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAiC;IAClE,OAAO,UAAU,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAC/F,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AACD,SAAS,QAAQ,CAAC,CAAU;IAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAA4B,CAAC,CAAC,IAAI,EAAE;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAE,CAA6B,CAAC,CAAC,CAAC,CAAC,CAAC;QACvH,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AASD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,IAAmB,EAAE,KAAa,EAAE,MAAqB;IAClF,IAAI,IAAI,IAAI,IAAI,IAAI,MAAM,IAAI,IAAI;QAAE,OAAO,YAAY,CAAC,CAAC,+CAA+C;IACxG,MAAM,YAAY,GAAG,KAAK,KAAK,IAAI,CAAC;IACpC,MAAM,aAAa,GAAG,MAAM,KAAK,IAAI,CAAC;IACtC,IAAI,CAAC,YAAY,IAAI,CAAC,aAAa;QAAE,OAAO,SAAS,CAAC;IACtD,IAAI,YAAY,IAAI,CAAC,aAAa;QAAE,OAAO,YAAY,CAAC;IACxD,IAAI,CAAC,YAAY,IAAI,aAAa;QAAE,OAAO,OAAO,CAAC;IACnD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,WAAmB;IAC1E,OAAO;QACL,KAAK,EAAE,QAAQ;QACf,aAAa,EAAE,IAAI;QACnB,UAAU;QACV,QAAQ,EAAE,IAAI;QACd,UAAU,EAAE,IAAI;QAChB,WAAW;QACX,SAAS,EAAE,KAAK;QAChB,SAAS,EAAE,SAAS;KACrB,CAAC;AACJ,CAAC"}