@open-everywhere/core 0.1.0

package/dist/agent/identity/principals.js

@@ -0,0 +1,303 @@
+// The config-as-code map of one human's native accounts across surfaces. Principals join ONLY on an explicit per-surface id, never on a display name, and a bare id means that id in whichever workspace this deployment serves.
+import { UNNAMED_TENANT, isTenantScopedPlatform, tryPrincipalKey } from "./principal-key.js";
+/** Identity-with-types helper (Eve's define* convention; returns unchanged). */
+export function definePrincipal(p) {
+    return p;
+}
+/** Normalize one written entry into accounts. Empty ids and non-string/object junk drop out — the
+ *  loud complaint about them is {@link assertPrincipalsValid}'s job, and every READER in this tree
+ *  has always been tolerant of a malformed map rather than crashing a display path over it. */
+function entryAccounts(platform, entry) {
+    const one = (v) => {
+        if (typeof v === "string")
+            return v.length > 0 ? { platform, id: v } : undefined;
+        if (!v || typeof v !== "object" || typeof v.id !== "string" || v.id.length === 0)
+            return undefined;
+        const tenant = typeof v.tenant === "string" ? v.tenant.trim() : "";
+        return tenant.length > 0 ? { platform, tenant, id: v.id } : { platform, id: v.id };
+    };
+    const list = Array.isArray(entry) ? entry : entry === undefined ? [] : [entry];
+    const out = [];
+    for (const v of list) {
+        const a = one(v);
+        if (a)
+            out.push(a);
+    }
+    return out;
+}
+/** Total order over accounts: platform, then tenant (UNQUALIFIED first — it is the older, wider
+ *  spelling and sorting it ahead keeps a pre-OPE-350 map's output byte-identical), then id. */
+function compareAccounts(a, b) {
+    if (a.platform !== b.platform)
+        return a.platform < b.platform ? -1 : 1;
+    const at = a.tenant ?? "";
+    const bt = b.tenant ?? "";
+    if (at !== bt)
+        return at < bt ? -1 : 1;
+    return a.id === b.id ? 0 : a.id < b.id ? -1 : 1;
+}
+/** The exact account identity as a map key: a JSON tuple over (platform, tenant, id), injective by construction, so there is no separator character that two different triples could collide on. */
+export function accountRefKey(a) {
+    return JSON.stringify([a.platform, a.tenant ?? "", a.id]);
+}
+/**
+ * Every account in a surface-ids record, FLATTENED, DEDUPED and in a deterministic order.
+ *
+ * The single reader every consumer goes through, so the three written spellings (bare id, one
+ * account, list) can never be interpreted three ways. Dedupe is on the exact (platform, tenant, id)
+ * triple: an unqualified and a qualified spelling of the same id are DIFFERENT entries here, on
+ * purpose — deciding they are the same account is a JOIN, and joins live in identity/link-resolve.ts
+ * where the reasoning is stated, not in a normalizer.
+ */
+export function surfaceAccounts(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const [platform, entry] of Object.entries(ids ?? {})) {
+        if (!platform)
+            continue;
+        for (const a of entryAccounts(platform, entry)) {
+            const k = accountRefKey(a);
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(a);
+        }
+    }
+    return out.sort(compareAccounts);
+}
+export function principalAccounts(p) {
+    return surfaceAccounts(p.ids);
+}
+/**
+ * Accounts back into the written record shape — the inverse of {@link surfaceAccounts}, for the
+ * paths that COMPOSE a principal (identity/link-resolve.ts's union, identity/link-store.ts's
+ * link-set projection) rather than read one.
+ *
+ * Canonical and deterministic: one unqualified account on a platform serializes to the BARE STRING
+ * it has always been, so a single-account deployment's union output is byte-identical to what it
+ * was before OPE-350; anything else serializes to a sorted list.
+ */
+export function surfaceIdsFromAccounts(accounts) {
+    const byPlatform = new Map();
+    const seen = new Set();
+    for (const a of accounts) {
+        if (!a.platform || !a.id)
+            continue;
+        const k = accountRefKey(a);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        const list = byPlatform.get(a.platform) ?? [];
+        list.push(a);
+        byPlatform.set(a.platform, list);
+    }
+    const out = {};
+    for (const platform of [...byPlatform.keys()].sort()) {
+        const list = byPlatform.get(platform).sort(compareAccounts);
+        if (list.length === 1 && list[0].tenant === undefined) {
+            out[platform] = list[0].id;
+            continue;
+        }
+        out[platform] = list.map((a) => (a.tenant === undefined ? { id: a.id } : { tenant: a.tenant, id: a.id }));
+    }
+    return out;
+}
+/**
+ * Resolve a canonical {@link Principal} from a (platform, tenant, native id) triple, or undefined
+ * when the account isn't in the map. The join is EXACT on the account — never on name/handle
+ * (fail-closed on merge).
+ *
+ * 🔴 THE TENANT ARM (OPE-350). On a tenant-scoped platform an entry matches when its tenant EQUALS
+ * the caller's; an UNQUALIFIED entry also matches, because that is precisely what the bare spelling
+ * has always meant — "this id, in whichever workspace this deployment serves". An EXACT match wins
+ * over an unqualified one so a qualified map is never shadowed by a stale bare entry, and
+ * {@link assertPrincipalsValid} refuses a map that mixes the two spellings on one tenant-scoped
+ * platform, so the fallback can never wildcard PAST a real per-tenant claim. On a vendor-global
+ * platform the tenant is not part of the address at all and is ignored on both sides (the same rule
+ * identity/principal-key.ts's composer applies), and a tenant written there is refused at load.
+ *
+ * Deterministic: with the config validated (no two principals share an account), at most one
+ * matches; a mis-validated config that double-claims returns the FIRST, and load-time validation
+ * would have thrown.
+ */
+export function resolvePrincipal(platform, tenant, id, principals) {
+    if (!platform || !id)
+        return undefined;
+    const scoped = isTenantScopedPlatform(platform);
+    const want = typeof tenant === "string" ? tenant.trim() : "";
+    let loose;
+    for (const p of principals) {
+        for (const a of principalAccounts(p)) {
+            if (a.platform !== platform || a.id !== id)
+                continue;
+            if (!scoped)
+                return p;
+            if (a.tenant === undefined) {
+                loose ??= p;
+                continue;
+            }
+            if (want.length > 0 && a.tenant === want)
+                return p;
+        }
+    }
+    return loose;
+}
+export function principalLabel(p) {
+    return p.handle ? `${p.name} (@${p.handle})` : p.name;
+}
+/** The platform ids this person holds at least one account on. The unified-domain audit differences this against the domain's containers to show which surfaces a person is NOT in. */
+export function principalSurfaces(p) {
+    return [...new Set(principalAccounts(p).map((a) => a.platform))].sort();
+}
+/**
+ * The PRINCIPAL KEYS this person's accounts compose, sorted and deduped. An UNQUALIFIED account on
+ * a tenant-scoped platform composes nothing (the grammar refuses to invent a tenant rung) and is
+ * omitted rather than spelled some other way — a caller asking for keys wants strings it can match
+ * a roster against, and a half-key would match nobody while looking like it should.
+ */
+export function principalKeys(p) {
+    const keys = new Set();
+    for (const a of principalAccounts(p)) {
+        const key = tryPrincipalKey(a.platform, a.tenant, a.id);
+        if (key !== undefined)
+            keys.add(key);
+    }
+    return [...keys].sort();
+}
+/**
+ * Config-load fail-loud validation for the principals map (P8). Enforces the invariants the
+ * fail-closed-on-merge guarantee rests on. Throws (with EVERY problem listed) if:
+ *  - a principal has an empty `name`;
+ *  - a principal has NO accounts at all (an unjoinable entry — almost certainly a mistake);
+ *  - a surface entry is empty, or holds an empty/non-string id;
+ *  - an entry names a `tenant` on a platform that is NOT tenant-scoped, or a tenant the key grammar
+ *    refuses (blank, slash- or whitespace-bearing, or the `dev` "nobody said" literal);
+ *  - one tenant-scoped platform carries BOTH qualified and unqualified entries anywhere in the map
+ *    — the half-migrated state;
+ *  - the SAME (platform, tenant, id) account is claimed by two ENTRIES — the merge conflict: an
+ *    account can be exactly one person, so this is fail-closed-on-merge at config time (the resolver
+ *    would otherwise silently pick one and grant it that person's standing). Two entries sharing a
+ *    display name are still two entries (see the keying note below);
+ *  - the same `email` is claimed by two entries (a softer conflict — emails feed the auto-join
+ *    flow, and a duplicate would propose a bad merge). Case-insensitive on email.
+ * Call it at config load alongside the domain asserts. A deployment with no principals map is valid
+ * (the feature degrades to per-surface identity — §5 fallback).
+ *
+ * 🔴 A TENANT ON A VENDOR-GLOBAL PLATFORM IS REFUSED, NOT IGNORED (OPE-350). `tryPrincipalKey`
+ * drops the tenant argument for a platform outside `TENANT_SCOPED_PLATFORMS`, so
+ * `github: [{ tenant: "a", id: "x" }, { tenant: "b", id: "x" }]` would read as two accounts here and
+ * compose ONE key `github/x` downstream. Two entries this validator called distinct and the grammar
+ * calls identical is precisely the double-claim it exists to catch, arriving through the back door —
+ * so a tenant is refused where it has no meaning rather than silently discarded.
+ *
+ * 🔴 MIXING QUALIFIED AND UNQUALIFIED ON ONE TENANT-SCOPED PLATFORM IS REFUSED — the half-migrated
+ * state, and the reason the whole widening needs no migration. A bare entry means "this id, in
+ * whichever workspace this deployment serves" (module header), which is exact while phase 0c's fence
+ * bounds the deployment to one admitted tenant. The moment ANY entry for that platform names a
+ * tenant, the map is asserting there is more than one workspace to tell apart — and a bare entry
+ * alongside it would wildcard across the very workspaces the qualified ones were written to
+ * separate, handing one person the other's cross-surface standing on an id collision. So a platform
+ * is all-bare (single workspace, today's semantics, untouched) or all-qualified, never in between.
+ * The check spans the WHOLE map, not one principal: the shadowing that matters is one person's bare
+ * entry swallowing a DIFFERENT person's qualified one.
+ *
+ * 🔴 CONFLICTS ARE KEYED BY ENTRY INDEX, NOT BY DISPLAY NAME. The claim ledgers used to record
+ * the claiming principal's `name` and reported a conflict only when the name DIFFERED — which made
+ * the check blind to the case it exists for: two SEPARATE entries both called "Tommy Long" could
+ * double-claim one account or one email in silence, and `resolvePrincipal` would then hand
+ * whichever came first that account's standing. A `name` is display data — the very thing this
+ * module's fail-closed-on-merge rule says is never a join key — so it could never have been an
+ * entry's identity; its position in the list is.
+ */
+export function assertPrincipalsValid(principals) {
+    const bad = [];
+    const claimed = new Map(); // accountRefKey → INDEX of the claiming entry
+    const emails = new Map(); // lowercased email → INDEX of the claiming entry
+    /** Per tenant-scoped platform: the first entry index that wrote a QUALIFIED account, and the
+     *  first that wrote an UNQUALIFIED one. Both present ⇒ the half-migrated state. */
+    const qualified = new Map();
+    const unqualified = new Map();
+    /** How an already-claiming entry is named in an error: its own `name` AND its index, because the
+     *  name alone does not distinguish two entries — which is the whole point of keying by index. */
+    const at = (i) => `"${principals[i].name}" (entry #${i})`;
+    /** How an account is named in an error: its principal key when the grammar can compose one, else
+     *  the honest tuple. Never a key-shaped string for something that addresses nobody. */
+    const named = (a) => tryPrincipalKey(a.platform, a.tenant, a.id) ?? `(${a.platform}, ${a.id})`;
+    for (const [index, p] of principals.entries()) {
+        if (!p.name || p.name.trim().length === 0) {
+            bad.push(`  a principal has an empty name (ids: ${JSON.stringify(p.ids)})`);
+        }
+        const entries = Object.entries(p.ids ?? {});
+        if (entries.length === 0) {
+            bad.push(`  "${p.name}" has no surface ids — an unjoinable principal (add at least one platform id)`);
+        }
+        for (const [platform, entry] of entries) {
+            const written = Array.isArray(entry) ? entry : entry === undefined ? [] : [entry];
+            if (written.length === 0) {
+                bad.push(`  "${p.name}" has an empty entry for platform "${platform}" — write an id, or drop the platform`);
+                continue;
+            }
+            const scoped = isTenantScopedPlatform(platform);
+            for (const v of written) {
+                const isObj = typeof v === "object" && v !== null;
+                const rawId = typeof v === "string" ? v : isObj ? v.id : undefined;
+                if (typeof rawId !== "string" || rawId.length === 0) {
+                    bad.push(`  "${p.name}" has an empty id for platform "${platform}"`);
+                    continue;
+                }
+                const rawTenant = isObj && typeof v.tenant === "string" ? v.tenant.trim() : undefined;
+                if (rawTenant !== undefined && !scoped) {
+                    bad.push(`  "${p.name}" names a tenant ("${rawTenant}") for "${platform}", whose person ids are addressed vendor-globally — ` +
+                        "the principal-key grammar has no workspace rung there, so the tenant would be silently discarded and two entries " +
+                        "differing only by it would collide on one key. Remove it, or write the platform as a bare id.");
+                    continue;
+                }
+                if (rawTenant !== undefined && (rawTenant.length === 0 || /[\s/]/u.test(rawTenant) || rawTenant === UNNAMED_TENANT)) {
+                    bad.push(`  "${p.name}" names an unusable ${platform} tenant ("${rawTenant}") — a tenant rung carries no slash and no whitespace, ` +
+                        `and "${UNNAMED_TENANT}" is the literal for "nobody said", not a workspace id. Omit the tenant to mean "this ` +
+                        'deployment\'s only workspace", or write the real workspace id.');
+                    continue;
+                }
+                const account = rawTenant !== undefined && scoped ? { platform, tenant: rawTenant, id: rawId } : { platform, id: rawId };
+                if (scoped) {
+                    const ledger = account.tenant === undefined ? unqualified : qualified;
+                    if (!ledger.has(platform))
+                        ledger.set(platform, index);
+                }
+                const key = accountRefKey(account);
+                const prev = claimed.get(key);
+                if (prev !== undefined) {
+                    bad.push(`  ${named(account)} is claimed by BOTH ${at(prev)} and ${at(index)} — an account is exactly one person (fail-closed on merge)`);
+                }
+                else {
+                    claimed.set(key, index);
+                }
+            }
+        }
+        if (p.email && p.email.trim().length > 0) {
+            const key = p.email.trim().toLowerCase();
+            const prev = emails.get(key);
+            if (prev !== undefined) {
+                bad.push(`  email "${p.email}" is claimed by BOTH ${at(prev)} and ${at(index)} — would propose a bad auto-join merge`);
+            }
+            else {
+                emails.set(key, index);
+            }
+        }
+    }
+    for (const [platform, qi] of qualified) {
+        const ui = unqualified.get(platform);
+        if (ui === undefined)
+            continue;
+        bad.push(`  "${platform}" is written BOTH with a workspace (${at(qi)}) and without one (${at(ui)}) — the half-migrated state. ` +
+            `On ${platform} a person id is issued PER WORKSPACE, so a bare id means "whichever workspace this deployment serves"; ` +
+            "alongside a workspace-qualified entry it would wildcard across the very workspaces those entries exist to tell apart. " +
+            `Qualify EVERY ${platform} entry ({ tenant: "<workspace-id>", id: "<user-id>" }), or none of them.`);
+    }
+    if (bad.length > 0) {
+        throw new Error("open-everywhere: invalid principals map (cross-surface identity):\n" +
+            bad.join("\n") +
+            "\n(identity/principals.ts assertPrincipalsValid).");
+    }
+}
+//# sourceMappingURL=principals.js.map

package/dist/agent/identity/principals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principals.js","sourceRoot":"","sources":["../../../agent/identity/principals.ts"],"names":[],"mappings":"AAAA,iOAAiO;AAEjO,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAmD7F,gFAAgF;AAChF,MAAM,UAAU,eAAe,CAAC,CAAY;IAC1C,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;+FAE+F;AAC/F,SAAS,aAAa,CAAC,QAAgB,EAAE,KAAwC;IAC/E,MAAM,GAAG,GAAG,CAAC,CAA4B,EAAmC,EAAE;QAC5E,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACjF,IAAI,CAAC,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,CAAC,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QACnG,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC;IACrF,CAAC,CAAC;IACF,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAgD,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAkC,CAAC,CAAC;IACxJ,MAAM,GAAG,GAA0B,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;QACjB,IAAI,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;+FAC+F;AAC/F,SAAS,eAAe,CAAC,CAAsB,EAAE,CAAsB;IACrE,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvE,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;IAC1B,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;IAC1B,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvC,OAAO,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClD,CAAC;AAED,oMAAoM;AACpM,MAAM,UAAU,aAAa,CAAC,CAAsB;IAClD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAoC;IAClE,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAA0B,EAAE,CAAC;IACtC,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC;QAC1D,IAAI,CAAC,QAAQ;YAAE,SAAS;QACxB,KAAK,MAAM,CAAC,IAAI,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,CAAY;IAC5C,OAAO,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAuC;IAC5E,MAAM,UAAU,GAAG,IAAI,GAAG,EAAiC,CAAC;IAC5D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,SAAS;QACnC,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACb,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IACD,MAAM,GAAG,GAA0C,EAAE,CAAC;IACtD,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACrD,MAAM,IAAI,GAAG,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC7D,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC,CAAE,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACvD,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;YAC5B,SAAS;QACX,CAAC;QACD,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB,EAAE,MAAiC,EAAE,EAAU,EAAE,UAAgC;IAChI,IAAI,CAAC,QAAQ,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IACvC,MAAM,MAAM,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,IAAI,KAA4B,CAAC;IACjC,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE;gBAAE,SAAS;YACrD,IAAI,CAAC,MAAM;gBAAE,OAAO,CAAC,CAAC;YACtB,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC3B,KAAK,KAAK,CAAC,CAAC;gBACZ,SAAS;YACX,CAAC;YACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;gBAAE,OAAO,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,CAAY;IACzC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC;AAED,uLAAuL;AACvL,MAAM,UAAU,iBAAiB,CAAC,CAAY;IAC5C,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,CAAY;IACxC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;QACxD,IAAI,GAAG,KAAK,SAAS;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,UAAU,qBAAqB,CAAC,UAAgC;IACpE,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAC,8CAA8C;IACzF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC,CAAC,iDAAiD;IAC3F;uFACmF;IACnF,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C;qGACiG;IACjG,MAAM,EAAE,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,IAAI,UAAU,CAAC,CAAC,CAAE,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC;IAC3E;2FACuF;IACvF,MAAM,KAAK,GAAG,CAAC,CAAsB,EAAU,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;IAC5H,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC;QAC9C,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1C,GAAG,CAAC,IAAI,CAAC,yCAAyC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9E,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;QAC5C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,+EAA+E,CAAC,CAAC;QACxG,CAAC;QACD,KAAK,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;YACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAA4B,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAgB,CAAC,CAAC;YACrH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,sCAAsC,QAAQ,uCAAuC,CAAC,CAAC;gBAC5G,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,sBAAsB,CAAC,QAAQ,CAAC,CAAC;YAChD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;gBACxB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC;gBAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,CAAsB,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACzF,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACpD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,mCAAmC,QAAQ,GAAG,CAAC,CAAC;oBACrE,SAAS;gBACX,CAAC;gBACD,MAAM,SAAS,GAAG,KAAK,IAAI,OAAQ,CAAsB,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAE,CAAsB,CAAC,MAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;gBACnI,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,EAAE,CAAC;oBACvC,GAAG,CAAC,IAAI,CACN,MAAM,CAAC,CAAC,IAAI,sBAAsB,SAAS,WAAW,QAAQ,sDAAsD;wBAClH,mHAAmH;wBACnH,+FAA+F,CAClG,CAAC;oBACF,SAAS;gBACX,CAAC;gBACD,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,SAAS,KAAK,cAAc,CAAC,EAAE,CAAC;oBACpH,GAAG,CAAC,IAAI,CACN,MAAM,CAAC,CAAC,IAAI,uBAAuB,QAAQ,aAAa,SAAS,yDAAyD;wBACxH,QAAQ,cAAc,wFAAwF;wBAC9G,gEAAgE,CACnE,CAAC;oBACF,SAAS;gBACX,CAAC;gBACD,MAAM,OAAO,GAAwB,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;gBAC9I,IAAI,MAAM,EAAE,CAAC;oBACX,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;oBACtE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;wBAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;gBACzD,CAAC;gBACD,MAAM,GAAG,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;gBACnC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAC9B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;oBACvB,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC,OAAO,CAAC,uBAAuB,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,4DAA4D,CAAC,CAAC;gBAC5I,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACzC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,KAAK,wBAAwB,EAAE,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;YACzH,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC;QACvC,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,EAAE,KAAK,SAAS;YAAE,SAAS;QAC/B,GAAG,CAAC,IAAI,CACN,MAAM,QAAQ,uCAAuC,EAAE,CAAC,EAAE,CAAC,sBAAsB,EAAE,CAAC,EAAE,CAAC,+BAA+B;YACpH,MAAM,QAAQ,yGAAyG;YACvH,wHAAwH;YACxH,iBAAiB,QAAQ,0EAA0E,CACtG,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CACb,qEAAqE;YACnE,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;YACd,mDAAmD,CACtD,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/agent/identity/surface-key-grammar.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A parsed entry — the SET of keys one line of config denotes. Three shapes, and keeping it to
+ * three is what makes {@link surfaceKeyEntriesIntersect} total:
+ *   • `tenant`  — `platform/<tenant>`: every key whose first two segments match, at ANY depth,
+ *     plus the bare tenant key itself.
+ *   • `surface` — `platform/<tenant>/<prefix>` (`glob: false`: that one key) or
+ *     `platform/<tenant>/<prefix>*` (`glob: true`: every EXACTLY-three-segment key under the tenant
+ *     whose last segment starts with `prefix`). Same level only — a glob never descends.
+ *   • `group`   — the same two forms over a MARKED segment (`team:<id>`, `team:pay*`), matched
+ *     against a platform-contributed GROUP key rather than the surface key. See the module header.
+ */
+export type SurfaceKeyEntry = {
+    readonly kind: "tenant";
+    readonly platform: string;
+    readonly tenant: string;
+} | {
+    readonly kind: "surface" | "group";
+    readonly platform: string;
+    readonly tenant: string;
+    readonly prefix: string;
+    readonly glob: boolean;
+};
+/** Is this third segment a GROUP rung (`team:<id>`) rather than a surface id? Exported so a plane
+ *  that does NOT support the rung can refuse one by name instead of accepting dead config. */
+export declare function isGroupSegment(segment: string): boolean;
+/**
+ * Parse one entry, or `undefined` if it is not one of the legal shapes. The refusal list is the
+ * syntax's whole safety argument, so it is enforced HERE (one parser) and merely *reported* by each
+ * plane's config validator: `*` only as the final character of a three-segment entry's final
+ * segment — so no `**`, no mid-string `*`, no second `*`, and none at all in the platform or tenant
+ * segment. A group segment (`team:<id>`) parses to `kind: "group"`; the colon is never legal in the
+ * platform or tenant segment.
+ */
+export declare function parseSurfaceKeyEntry(entry: string): SurfaceKeyEntry | undefined;
+/**
+ * Does a parsed entry admit this fully-qualified key? Pure string work, no I/O.
+ *
+ * The caller decides WHICH key it is asking about: a `surface` entry is matched against a surface
+ * key and a `group` entry against a platform-contributed group key. They cannot be confused —
+ * `keyKind` reads the same colon marker the parser did, so a surface entry can never admit a group
+ * key and a group entry can never admit a surface key.
+ */
+export declare function surfaceKeyEntryMatches(e: SurfaceKeyEntry, key: string): boolean;
+/**
+ * Do two entries' key sets overlap? DECIDABLE precisely because the pattern language is one
+ * trailing `*`, so "could these two match the same key?" is one `startsWith`. With a regex (or
+ * `**`, or a mid-string `*`) the honest answer would be "we cannot tell".
+ *
+ * The sets form a LAMINAR family — when two entries intersect, one always CONTAINS the other
+ * ({@link surfaceKeyEntryContains} finds which) — so the intersection is never some third set
+ * nobody wrote, which is what lets an exclusion cancel it exactly.
+ *
+ * A group entry and a surface entry NEVER intersect, because no key is both.
+ */
+export declare function surfaceKeyEntriesIntersect(a: SurfaceKeyEntry, b: SurfaceKeyEntry): boolean;
+/**
+ * Do two entries denote the SAME set of keys? True exactly when each contains the other — which,
+ * for this grammar, means they are the same shape over the same platform/tenant/prefix.
+ *
+ * This is the ONE case most-specific-wins cannot settle. Two entries where one strictly contains
+ * the other have an order (the narrower wins); two entries denoting one set have none, so the
+ * planes that resolve by specificity — the memory domain registry, the trust registry — refuse the
+ * pair at config load rather than letting declaration order decide.
+ */
+export declare function surfaceKeyEntriesEquivalent(a: SurfaceKeyEntry, b: SurfaceKeyEntry): boolean;
+/** Is every key of `inner` also a key of `outer`? (Total on intersecting entries — see above.) */
+export declare function surfaceKeyEntryContains(outer: SurfaceKeyEntry, inner: SurfaceKeyEntry): boolean;
+/**
+ * How SPECIFIC is an entry — the tiebreak the trust registry resolves on (most specific wins),
+ * ordered so that an explicitly-listed key can never be annexed by a broader pattern. Higher wins:
+ *
+ *   3  exact surface  (`slack/T0/C0BOARD`)
+ *   2  surface glob   (`github/acme/payments-*`)
+ *   1  group          (`teams/T0/team:<id>` — exact or globbed; the rung sits between)
+ *   0  tenant         (`slack/T0`)
+ *
+ * The group rung does NOT split into exact/glob tiers: a group glob only ever narrows within one
+ * marker's id space, and giving it its own tier would buy an ordering nobody can write a config to
+ * exercise. Two group entries that could match one key are a config error, not a tiebreak — see
+ * {@link surfaceKeyEntriesIntersect}, which the trust registry uses to refuse them at boot.
+ */
+export declare function surfaceKeyEntrySpecificity(e: SurfaceKeyEntry): number;
+//# sourceMappingURL=surface-key-grammar.d.ts.map

package/dist/agent/identity/surface-key-grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-key-grammar.d.ts","sourceRoot":"","sources":["../../../agent/identity/surface-key-grammar.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/E;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,CAAC;AAMN;8FAC8F;AAC9F,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAgB/E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAS/E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,GAAG,OAAO,CAQ1F;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,EAAE,eAAe,GAAG,OAAO,CAE3F;AAED,kGAAkG;AAClG,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAO/F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAIrE"}

package/dist/agent/identity/surface-key-grammar.js

@@ -0,0 +1,138 @@
+// One parser for surface-key config entries, called by BOTH the memory domain registry and the trust registry, so a fence and a router cannot disagree about which keys an entry admits. The refusal list is enforced here.
+// The pattern language is one trailing `*` on a three-segment entry precisely so overlap stays DECIDABLE at config load; a third segment carrying a colon (`team:<teamId>`) is a GROUP rung, which can never collide with a real key because binding.ts sanitises a colon out of every real segment.
+/** The marker that makes a third segment a GROUP rung rather than a surface (see the header): a
+ *  colon, which `seg()` sanitisation guarantees no real key segment can contain. */
+const GROUP_MARKER = ":";
+/** Is this third segment a GROUP rung (`team:<id>`) rather than a surface id? Exported so a plane
+ *  that does NOT support the rung can refuse one by name instead of accepting dead config. */
+export function isGroupSegment(segment) {
+    return segment.includes(GROUP_MARKER);
+}
+/**
+ * Parse one entry, or `undefined` if it is not one of the legal shapes. The refusal list is the
+ * syntax's whole safety argument, so it is enforced HERE (one parser) and merely *reported* by each
+ * plane's config validator: `*` only as the final character of a three-segment entry's final
+ * segment — so no `**`, no mid-string `*`, no second `*`, and none at all in the platform or tenant
+ * segment. A group segment (`team:<id>`) parses to `kind: "group"`; the colon is never legal in the
+ * platform or tenant segment.
+ */
+export function parseSurfaceKeyEntry(entry) {
+    const segs = entry.split("/");
+    const [platform, tenant, surface] = segs;
+    if (!platform || !tenant)
+        return undefined;
+    if (platform.includes("*") || tenant.includes("*"))
+        return undefined;
+    if (isGroupSegment(platform) || isGroupSegment(tenant))
+        return undefined;
+    if (segs.length === 2)
+        return { kind: "tenant", platform, tenant };
+    if (segs.length !== 3 || surface === undefined)
+        return undefined;
+    const kind = isGroupSegment(surface) ? "group" : "surface";
+    const star = surface.indexOf("*");
+    if (star === -1)
+        return surface === "" ? undefined : { kind, platform, tenant, prefix: surface, glob: false };
+    if (star !== surface.length - 1)
+        return undefined;
+    const prefix = surface.slice(0, -1);
+    // `team:*` is a legal group glob; a bare `*` prefix on a group segment is not reachable (a group
+    // segment contains the marker by definition), so no extra refusal is needed here.
+    return { kind, platform, tenant, prefix, glob: true };
+}
+/**
+ * Does a parsed entry admit this fully-qualified key? Pure string work, no I/O.
+ *
+ * The caller decides WHICH key it is asking about: a `surface` entry is matched against a surface
+ * key and a `group` entry against a platform-contributed group key. They cannot be confused —
+ * `keyKind` reads the same colon marker the parser did, so a surface entry can never admit a group
+ * key and a group entry can never admit a surface key.
+ */
+export function surfaceKeyEntryMatches(e, key) {
+    const segs = key.split("/");
+    if (segs[0] !== e.platform || segs[1] !== e.tenant)
+        return false;
+    if (e.kind === "tenant")
+        return true; // any depth, including the bare tenant key
+    if (segs.length !== 3)
+        return false; // SAME LEVEL ONLY — a glob never reaches a deeper key
+    const last = segs[2] ?? "";
+    // A group entry answers only about a group key, and a surface entry only about a surface key.
+    if (isGroupSegment(last) !== (e.kind === "group"))
+        return false;
+    return e.glob ? last.startsWith(e.prefix) : last === e.prefix;
+}
+/**
+ * Do two entries' key sets overlap? DECIDABLE precisely because the pattern language is one
+ * trailing `*`, so "could these two match the same key?" is one `startsWith`. With a regex (or
+ * `**`, or a mid-string `*`) the honest answer would be "we cannot tell".
+ *
+ * The sets form a LAMINAR family — when two entries intersect, one always CONTAINS the other
+ * ({@link surfaceKeyEntryContains} finds which) — so the intersection is never some third set
+ * nobody wrote, which is what lets an exclusion cancel it exactly.
+ *
+ * A group entry and a surface entry NEVER intersect, because no key is both.
+ */
+export function surfaceKeyEntriesIntersect(a, b) {
+    if (a.platform !== b.platform || a.tenant !== b.tenant)
+        return false;
+    if (a.kind === "tenant" || b.kind === "tenant")
+        return true; // a tenant covers every key under it
+    if (a.kind !== b.kind)
+        return false; // surface vs group — disjoint key spaces
+    if (a.glob && b.glob)
+        return a.prefix.startsWith(b.prefix) || b.prefix.startsWith(a.prefix);
+    if (a.glob)
+        return b.prefix.startsWith(a.prefix);
+    if (b.glob)
+        return a.prefix.startsWith(b.prefix);
+    return a.prefix === b.prefix;
+}
+/**
+ * Do two entries denote the SAME set of keys? True exactly when each contains the other — which,
+ * for this grammar, means they are the same shape over the same platform/tenant/prefix.
+ *
+ * This is the ONE case most-specific-wins cannot settle. Two entries where one strictly contains
+ * the other have an order (the narrower wins); two entries denoting one set have none, so the
+ * planes that resolve by specificity — the memory domain registry, the trust registry — refuse the
+ * pair at config load rather than letting declaration order decide.
+ */
+export function surfaceKeyEntriesEquivalent(a, b) {
+    return surfaceKeyEntryContains(a, b) && surfaceKeyEntryContains(b, a);
+}
+/** Is every key of `inner` also a key of `outer`? (Total on intersecting entries — see above.) */
+export function surfaceKeyEntryContains(outer, inner) {
+    if (outer.platform !== inner.platform || outer.tenant !== inner.tenant)
+        return false;
+    if (outer.kind === "tenant")
+        return true;
+    if (inner.kind === "tenant")
+        return false; // a same-level glob never covers a whole tenant
+    if (outer.kind !== inner.kind)
+        return false; // surface vs group — disjoint key spaces
+    if (!outer.glob)
+        return !inner.glob && inner.prefix === outer.prefix;
+    return inner.prefix.startsWith(outer.prefix);
+}
+/**
+ * How SPECIFIC is an entry — the tiebreak the trust registry resolves on (most specific wins),
+ * ordered so that an explicitly-listed key can never be annexed by a broader pattern. Higher wins:
+ *
+ *   3  exact surface  (`slack/T0/C0BOARD`)
+ *   2  surface glob   (`github/acme/payments-*`)
+ *   1  group          (`teams/T0/team:<id>` — exact or globbed; the rung sits between)
+ *   0  tenant         (`slack/T0`)
+ *
+ * The group rung does NOT split into exact/glob tiers: a group glob only ever narrows within one
+ * marker's id space, and giving it its own tier would buy an ordering nobody can write a config to
+ * exercise. Two group entries that could match one key are a config error, not a tiebreak — see
+ * {@link surfaceKeyEntriesIntersect}, which the trust registry uses to refuse them at boot.
+ */
+export function surfaceKeyEntrySpecificity(e) {
+    if (e.kind === "tenant")
+        return 0;
+    if (e.kind === "group")
+        return 1;
+    return e.glob ? 2 : 3;
+}
+//# sourceMappingURL=surface-key-grammar.js.map

package/dist/agent/identity/surface-key-grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-key-grammar.js","sourceRoot":"","sources":["../../../agent/identity/surface-key-grammar.ts"],"names":[],"mappings":"AAAA,4NAA4N;AAC5N,qSAAqS;AAuBrS;oFACoF;AACpF,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB;8FAC8F;AAC9F,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC3C,IAAI,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IACrE,IAAI,cAAc,CAAC,QAAQ,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IACzE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAE,OAAiB,CAAC,CAAC,CAAE,SAAmB,CAAC;IACjF,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,IAAI,KAAK,CAAC,CAAC;QAAE,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC9G,IAAI,IAAI,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpC,iGAAiG;IACjG,kFAAkF;IAClF,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,CAAkB,EAAE,GAAW;IACpE,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,CAAC,2CAA2C;IACjF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,sDAAsD;IAC3F,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3B,8FAA8F;IAC9F,IAAI,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAChE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,MAAM,CAAC;AAChE,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CAAC,CAAkB,EAAE,CAAkB;IAC/E,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,CAAC,qCAAqC;IAClG,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC,CAAC,yCAAyC;IAC9E,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5F,IAAI,CAAC,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,2BAA2B,CAAC,CAAkB,EAAE,CAAkB;IAChF,OAAO,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,uBAAuB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,uBAAuB,CAAC,KAAsB,EAAE,KAAsB;IACpF,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IACrF,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,CAAC,gDAAgD;IAC3F,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC,CAAC,yCAAyC;IACtF,IAAI,CAAC,KAAK,CAAC,IAAI;QAAE,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,CAAC;IACrE,OAAO,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,0BAA0B,CAAC,CAAkB;IAC3D,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,CAAC,CAAC;IACjC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACxB,CAAC"}