@openrig/cli 0.5.15 → 0.5.17

package/node_modules/@openrig/daemon/dist/domain/gateway/human-registry.js

@@ -1,692 +0,0 @@
-// OPR gateway M1 A3 — human specs: file-per-human FRAGMENTS + a GENERATED registry
-// projection. Schema sealed in GATEWAY-M1-A3-ENTITY-SCHEMA (b2a2594b, supersedes
-// e499dab6): prefs are PER-ENTITY (loudness once per human) and `role` is PER-BINDING
-// (routing / default delivery channel) — two DISTINCT axes.
-//
-// TRUTH MODEL (design-record §7 / plan §1): each human is one YAML fragment at
-// <home>/gateway/humans/<entityId>.yaml. The registry is a GENERATED PROJECTION of
-// the fragments (humans.generated.yaml) — NEVER hand-edited; the fragment is truth.
-// The projection carries a DO-NOT-EDIT header and a drift pin (mirrors the
-// attestation-lineage.generated codegen convention). Admission/resolution is the
-// A1/A4 gateway's job — this module only owns the fragment + projection contract.
-//
-// Validation is add-time == load-time (the hosts-registry entry pattern): the SAME
-// validateHumanFragment runs on `add` and on load, so a present-but-invalid fragment
-// is a loud error, never silently projected.
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, readdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
-import { getOpenRigHome } from "../../openrig-compat.js";
-import { DispatchBuffer } from "./dispatch-buffer.js";
-import { parseSessionName } from "../session-name.js";
-// ── Schema (closed enums; extend only additively behind the contract) ──
-export const HUMAN_ENTITY_CLASSES = new Set(["human"]); // M1's only class
-export const HUMAN_CONNECTOR_KINDS = new Set(["slack"]); // M1's only kind
-export const HUMAN_BINDING_ROLES = new Set(["primary", "secondary"]);
-export const HUMAN_DELIVERY_CLASSES = new Set(["A", "B", "C", "D"]);
-// entityId is the fragment key + filename: a stable slug that survives platform
-// renames. Lowercase alnum + separators, no path chars (it is spliced into a path).
-export const ENTITY_ID_PATTERN = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/;
-// The registered @external ref shape (the section2 registered mode). A registry
-// fragment's address is <entityId>@external by convention; literal-scheme addresses
-// (slack:U...@external) are one-off ADDRESSES, never registry entries.
-export const ADDRESS_DOMAIN = "external";
-// Closed key sets — a typo'd field must fail LOUD, never silently degrade behavior.
-const ALLOWED_FRAGMENT_KEYS = new Set(["entityId", "class", "displayName", "address", "connectorBindings", "prefs"]);
-const ALLOWED_BINDING_KEYS = new Set(["kind", "connectorRef", "secretsRef", "role", "handle"]);
-// A connector handle (M1 A6 v3 schema 9e468b2f): the platform-native id of the human ON that
-// connector (e.g. a Slack user id). Constrained so it can never forge a session ref (no ':' / '@'
-// / whitespace) — it is compared to an inbound sender id and spliced into teaching text.
-export const HANDLE_PATTERN = /^[A-Za-z0-9._-]+$/;
-const ALLOWED_PREFS_KEYS = new Set(["deliveryClass", "away", "availability"]);
-// OPR.0.5.6.1 — the availability enum the delivery rules engine consumes.
-// Legacy `away: true` reads as availability=away ONLY when availability is
-// whole-field-absent (the D1 convention); a present-but-conflicting pair is
-// refused at validation, never silently resolved.
-export const HUMAN_AVAILABILITY_MODES = new Set(["available", "focus", "away", "off"]);
-function unknownKey(obj, allowed) {
-    for (const k of Object.keys(obj))
-        if (!allowed.has(k))
-            return k;
-    return undefined;
-}
-function isObj(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-/** add-time == load-time validation. Returns the typed fragment or a loud error.
- *  Structural + closed-enum + the two cross-field invariants (>=1 binding,
- *  exactly-one-primary-per-entity). Does NOT touch the filesystem. */
-export function validateHumanFragment(raw) {
-    if (!isObj(raw))
-        return { ok: false, error: "human fragment must be a mapping" };
-    const uk = unknownKey(raw, ALLOWED_FRAGMENT_KEYS);
-    if (uk)
-        return { ok: false, error: `unknown fragment key "${uk}" — allowed: ${[...ALLOWED_FRAGMENT_KEYS].join(", ")} (a typo must not silently degrade)` };
-    const { entityId, class: cls, displayName, address, connectorBindings, prefs } = raw;
-    if (typeof entityId !== "string" || !ENTITY_ID_PATTERN.test(entityId)) {
-        return { ok: false, error: `entityId "${String(entityId)}" must be a lowercase slug (a-z0-9._- , no leading/trailing separator)` };
-    }
-    if (cls !== "human") {
-        return { ok: false, error: `class "${String(cls)}" is not a known entity class (M1: ${[...HUMAN_ENTITY_CLASSES].join(", ")})` };
-    }
-    if (typeof displayName !== "string" || displayName.length === 0) {
-        return { ok: false, error: "displayName must be a non-empty string" };
-    }
-    if (typeof address !== "string" || address.length === 0) {
-        return { ok: false, error: "address must be a non-empty string (the registered @external ref)" };
-    }
-    // Registered-mode pin: the address is <entityId>@external (collision-free, ties the
-    // ref to the fragment key). Not a loose @external match — mike@externalx is NOT a ref.
-    if (address !== `${entityId}@${ADDRESS_DOMAIN}`) {
-        return { ok: false, error: `address "${address}" must be the registered ref "${entityId}@${ADDRESS_DOMAIN}" (the <entityId>@external convention)` };
-    }
-    if (!Array.isArray(connectorBindings) || connectorBindings.length < 1) {
-        return { ok: false, error: "connectorBindings must be a non-empty list (>=1)" };
-    }
-    const bindings = [];
-    let primaryCount = 0;
-    for (let i = 0; i < connectorBindings.length; i++) {
-        const b = connectorBindings[i];
-        if (!isObj(b))
-            return { ok: false, error: `connectorBindings[${i}] must be a mapping` };
-        const ubk = unknownKey(b, ALLOWED_BINDING_KEYS);
-        if (ubk)
-            return { ok: false, error: `connectorBindings[${i}] has unknown key "${ubk}" — allowed: ${[...ALLOWED_BINDING_KEYS].join(", ")}` };
-        if (!HUMAN_CONNECTOR_KINDS.has(String(b.kind))) {
-            return { ok: false, error: `connectorBindings[${i}].kind "${String(b.kind)}" is not a known connector kind (M1: ${[...HUMAN_CONNECTOR_KINDS].join(", ")})` };
-        }
-        if (typeof b.connectorRef !== "string" || b.connectorRef.length === 0) {
-            return { ok: false, error: `connectorBindings[${i}].connectorRef must be a non-empty string` };
-        }
-        if (typeof b.secretsRef !== "string" || b.secretsRef.length === 0) {
-            return { ok: false, error: `connectorBindings[${i}].secretsRef must be a non-empty vault POINTER (never the secret)` };
-        }
-        if (!HUMAN_BINDING_ROLES.has(String(b.role))) {
-            return { ok: false, error: `connectorBindings[${i}].role "${String(b.role)}" must be primary|secondary` };
-        }
-        if (b.role === "primary")
-            primaryCount++;
-        // A6 v3: handle is OPTIONAL; when present it must be a clean platform id (ref-forgery-safe).
-        let handle;
-        if (b.handle !== undefined) {
-            if (typeof b.handle !== "string" || !HANDLE_PATTERN.test(b.handle)) {
-                return { ok: false, error: `connectorBindings[${i}].handle "${String(b.handle)}" must match ${HANDLE_PATTERN} (a platform id — no ':' '@' or whitespace, which could forge a ref)` };
-            }
-        }
-        const binding = { kind: "slack", connectorRef: b.connectorRef, secretsRef: b.secretsRef, role: b.role };
-        if (b.handle !== undefined) {
-            handle = b.handle;
-            binding.handle = handle;
-        }
-        bindings.push(binding);
-    }
-    // EXACTLY ONE primary binding per entity = the default delivery channel.
-    if (primaryCount !== 1) {
-        return { ok: false, error: `exactly one connectorBinding must have role "primary" (found ${primaryCount}) — it is the default delivery channel` };
-    }
-    // A6 v3 pin-1 (within-fragment): a handle is UNIQUE per kind across this human's bindings —
-    // one human must not claim the same platform id twice. (Cross-fragment uniqueness is enforced
-    // in projectHumans, which sees every human at once.)
-    const seenHandles = new Set();
-    for (const b of bindings) {
-        if (b.handle === undefined)
-            continue;
-        const key = `${b.kind}:${b.handle}`;
-        if (seenHandles.has(key)) {
-            return { ok: false, error: `duplicate ${b.kind} handle "${b.handle}" across this human's bindings — a handle is unique per kind (one platform id = one human)` };
-        }
-        seenHandles.add(key);
-    }
-    if (!isObj(prefs))
-        return { ok: false, error: "prefs must be a mapping { deliveryClass, away? }" };
-    const upk = unknownKey(prefs, ALLOWED_PREFS_KEYS);
-    if (upk)
-        return { ok: false, error: `prefs has unknown key "${upk}" — allowed: ${[...ALLOWED_PREFS_KEYS].join(", ")} (the notifications register selection)` };
-    if (!HUMAN_DELIVERY_CLASSES.has(String(prefs.deliveryClass))) {
-        return { ok: false, error: `prefs.deliveryClass "${String(prefs.deliveryClass)}" must be one of A|B|C|D (the notifications register)` };
-    }
-    if (prefs.away !== undefined && typeof prefs.away !== "boolean") {
-        return { ok: false, error: "prefs.away must be a boolean when present" };
-    }
-    if (prefs.availability !== undefined && !HUMAN_AVAILABILITY_MODES.has(String(prefs.availability))) {
-        return { ok: false, error: `prefs.availability "${String(prefs.availability)}" must be one of available|focus|away|off` };
-    }
-    // Two spellings of one truth are refused: a present availability is the
-    // authority; legacy away may only AGREE with it (away:true + availability=away).
-    if (prefs.availability !== undefined && prefs.away === true && prefs.availability !== "away") {
-        return { ok: false, error: `prefs.away=true conflicts with prefs.availability "${String(prefs.availability)}" — set availability alone (away is the legacy spelling)` };
-    }
-    const validatedPrefs = { deliveryClass: prefs.deliveryClass };
-    if (prefs.away !== undefined)
-        validatedPrefs.away = prefs.away;
-    if (prefs.availability !== undefined)
-        validatedPrefs.availability = prefs.availability;
-    return {
-        ok: true,
-        fragment: { entityId, class: "human", displayName, address, connectorBindings: bindings, prefs: validatedPrefs },
-    };
-}
-// ── Paths (under getOpenRigHome(); `home` injectable for hermetic tests) ──
-export function humansDir(home = getOpenRigHome()) {
-    return join(home, "gateway", "humans");
-}
-export function projectionPath(home = getOpenRigHome()) {
-    return join(home, "gateway", "humans.generated.yaml");
-}
-/** @deprecated Historical spelling retained for readers of old records only.
- * Never a routing default: an address must resolve to an actual registry entity. */
-export const OPERATOR_HUMAN_DEFAULT_SLOT = "human-operator@kernel";
-const PROJECTION_HEADER = "# GENERATED FILE — DO NOT EDIT.\n" +
-    "# Projection of the human fragments under gateway/humans/<entityId>.yaml.\n" +
-    "# The fragment is truth: add/edit a human via its fragment (or `rig gateway human\n" +
-    "# add`), then re-project. A hand-edit here is REFUSED at load.\n";
-const PROJECTION_V2_HEADER = PROJECTION_HEADER + "# Projection format: v2 content-addressed\n";
-const PROJECTION_DIGEST_PREFIX = "# projection-body-sha256: ";
-function projectionBody(entities) {
-    const entityBody = stringifyYaml({ entities });
-    const digest = createHash("sha256").update(entityBody).digest("hex");
-    return `${PROJECTION_V2_HEADER}${PROJECTION_DIGEST_PREFIX}${digest}\n${entityBody}`;
-}
-function validateEntityCollection(entities) {
-    const entityIds = new Set();
-    const handleOwner = new Map();
-    for (const entity of entities) {
-        if (entityIds.has(entity.entityId)) {
-            return `duplicate human entityId "${entity.entityId}" — one fragment owns one identity`;
-        }
-        entityIds.add(entity.entityId);
-        for (const binding of entity.connectorBindings) {
-            if (binding.handle === undefined)
-                continue;
-            const key = `${binding.kind}:${binding.handle}`;
-            const prior = handleOwner.get(key);
-            if (prior !== undefined && prior !== entity.entityId) {
-                return `${binding.kind} handle "${binding.handle}" is claimed by both "${prior}" and "${entity.entityId}" — a handle maps to exactly one human (registration conflict)`;
-            }
-            handleOwner.set(key, entity.entityId);
-        }
-    }
-    return undefined;
-}
-/** Generate the canonical registry projection from the fragments (the ONE generator
- *  used by both the write path and the drift/load check). Load-time validation is the
- *  SAME validateHumanFragment as add-time; the filename must equal <entityId>.yaml
- *  (collision-free key). Entities are sorted by entityId for a stable, diffable body. */
-export function projectHumans(home = getOpenRigHome()) {
-    const dir = humansDir(home);
-    const entities = [];
-    if (existsSync(dir)) {
-        const files = readdirSync(dir).filter((f) => f.endsWith(".yaml") && !f.startsWith(".")).sort();
-        for (const f of files) {
-            let raw;
-            try {
-                raw = parseYaml(readFileSync(join(dir, f), "utf8"));
-            }
-            catch (err) {
-                return { ok: false, error: `failed to parse human fragment ${f}: ${err.message}` };
-            }
-            const v = validateHumanFragment(raw);
-            if (!v.ok)
-                return { ok: false, error: `invalid human fragment ${f}: ${v.error}` };
-            if (`${v.fragment.entityId}.yaml` !== f) {
-                return { ok: false, error: `human fragment ${f} declares entityId "${v.fragment.entityId}" — the filename must be <entityId>.yaml` };
-            }
-            entities.push(v.fragment);
-        }
-    }
-    entities.sort((a, b) => (a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0));
-    // A6 v3 pin-1 (cross-fragment): a handle is UNIQUE per kind across ALL humans — one platform
-    // id maps to exactly one human, so the inbound resolver is unambiguous. A collision between two
-    // fragments is a registration conflict, REFUSED at projection (so add/load/drift all catch it).
-    const collectionError = validateEntityCollection(entities);
-    if (collectionError)
-        return { ok: false, error: collectionError };
-    return { ok: true, body: projectionBody(entities), entities };
-}
-/** A6 v3 pins 2+3 — resolve an INBOUND connector handle to its registered human. Walks every
- *  human's bindings of `connectorKind` for one whose `handle` equals `handle`:
- *   - a match          -> registered (admit as that entity; its address is the human-class source)
- *   - no match         -> unregistered LOUD teaching (admit-iff-registered — never fabricate a
- *                         human seat from a raw platform id; a handle-LESS binding is outbound-only
- *                         and simply never matches, so it fails inbound here, loudly).
- *  Cross-fragment uniqueness (projectHumans) guarantees at most one match. */
-export function resolveSlackHandle(handle, entities, connectorKind = "slack") {
-    for (const e of entities) {
-        for (const b of e.connectorBindings) {
-            if (b.kind === connectorKind && b.handle !== undefined && b.handle === handle) {
-                return { kind: "registered", entityId: e.entityId, address: e.address };
-            }
-        }
-    }
-    return {
-        kind: "unregistered",
-        handle,
-        error: `inbound ${connectorKind} sender "${handle}" is not a registered human (no binding with handle "${handle}"). ` +
-            `Register the human + their handle first: rig gateway human add <entityId> --display-name … ` +
-            `--binding ${connectorKind}:<connectorRef>:<secretsRef>:primary:handle=${handle} --delivery-class …; ` +
-            `until then this message is REFUSED (it was NOT landed as a fabricated human seat).`,
-    };
-}
-function atomicWrite(path, body) {
-    try {
-        mkdirSync(dirname(path), { recursive: true });
-        const tmp = `${path}.tmp-${process.pid}`;
-        writeFileSync(tmp, body, { mode: 0o600 });
-        renameSync(tmp, path);
-        return { ok: true };
-    }
-    catch (err) {
-        return { ok: false, error: `failed to write ${path}: ${err.message}` };
-    }
-}
-/** (Re)write the generated projection from the current fragments. Atomic. */
-export function writeProjection(home = getOpenRigHome()) {
-    const proj = projectHumans(home);
-    if (!proj.ok)
-        return { ok: false, error: proj.error };
-    const path = projectionPath(home);
-    const w = atomicWrite(path, proj.body);
-    return w.ok ? { ok: true, path } : w;
-}
-/** The verb-add writer: validate (add-time) -> atomic write the ONE fragment file ->
- *  re-project. Operators never hand-create the fragment YAML; the verb owns it.
- *  NO SILENT CLOBBER (mirrors hosts-registry addHostEntry): an existing entityId is
- *  REFUSED unless `replace` is passed explicitly — a re-run must not silently replace
- *  a human's data (managed-config data-safety class). */
-export function addHumanFragment(raw, home = getOpenRigHome(), opts = {}) {
-    const v = validateHumanFragment(raw);
-    if (!v.ok)
-        return { ok: false, error: v.error };
-    const file = join(humansDir(home), `${v.fragment.entityId}.yaml`);
-    if (!opts.replace && existsSync(file)) {
-        return { ok: false, error: `human "${v.fragment.entityId}" already exists at ${file} — pass an explicit replace to update it (no silent overwrite)` };
-    }
-    // A6 v3 pin-1: reject a handle already claimed by a DIFFERENT human BEFORE writing (never leave a
-    // conflicting fragment on disk with a failed re-projection). projectHumans is the load-time backstop.
-    const existing = projectHumans(home);
-    if (!existing.ok)
-        return { ok: false, error: `cannot validate handle uniqueness — existing registry is invalid: ${existing.error}` };
-    const claimed = new Map();
-    for (const e of existing.entities) {
-        if (e.entityId === v.fragment.entityId)
-            continue; // a replace of the same human is fine
-        for (const b of e.connectorBindings)
-            if (b.handle !== undefined)
-                claimed.set(`${b.kind}:${b.handle}`, e.entityId);
-    }
-    for (const b of v.fragment.connectorBindings) {
-        if (b.handle === undefined)
-            continue;
-        const owner = claimed.get(`${b.kind}:${b.handle}`);
-        if (owner !== undefined) {
-            return { ok: false, error: `${b.kind} handle "${b.handle}" is already registered to human "${owner}" — a handle maps to exactly one human (registration conflict)` };
-        }
-    }
-    const w = atomicWrite(file, stringifyYaml(v.fragment));
-    if (!w.ok)
-        return { ok: false, error: w.error };
-    const proj = writeProjection(home);
-    if (!proj.ok)
-        return { ok: false, error: `fragment written but re-projection failed: ${proj.error}` };
-    return { ok: true, path: file, fragment: v.fragment };
-}
-/** Amendment A1 (founder R5): the 0.5.5 surface is SINGLE-HUMAN. Several fragments render
- *  honestly, but enumeration is display, never management — the advisory names the boundary. */
-export const MULTI_HUMAN_ADVISORY = "several human fragments exist; this release's surface is single-human — multi-human management is 0.5.7 scope (fragments are displayed honestly; no plural management verbs exist)";
-/** --binding / set-binding spec: kind:connectorRef:secretsRef:role[:handle=<id>]. secretsRef is
- *  a vault POINTER and may itself contain ':', so kind/connectorRef are the first two fields,
- *  role is the LAST positional, secretsRef is everything between. An optional handle= token may
- *  appear anywhere. ONE source for add (CLI) and set (here) — the same parse both paths. */
-export function parseBindingSpec(spec) {
-    const all = spec.split(":");
-    const handleTokens = all.filter((p) => p.startsWith("handle="));
-    if (handleTokens.length > 1)
-        return { ok: false, error: `binding spec must carry at most one handle= token (got "${spec}")` };
-    const handle = handleTokens.length === 1 ? handleTokens[0].slice("handle=".length) : undefined;
-    if (handle !== undefined && handle.length === 0)
-        return { ok: false, error: `binding handle= must be non-empty (got "${spec}")` };
-    const parts = all.filter((p) => !p.startsWith("handle="));
-    if (parts.length < 4)
-        return { ok: false, error: `binding spec must be kind:connectorRef:secretsRef:role[:handle=<id>] (got "${spec}")` };
-    const kind = parts[0];
-    const connectorRef = parts[1];
-    const role = parts[parts.length - 1];
-    const secretsRef = parts.slice(2, -1).join(":");
-    if (!kind || !connectorRef || !secretsRef || !role) {
-        return { ok: false, error: `binding spec fields must be non-empty: kind:connectorRef:secretsRef:role[:handle=<id>] (got "${spec}")` };
-    }
-    return { ok: true, binding: handle !== undefined ? { kind, connectorRef, secretsRef, role, handle } : { kind, connectorRef, secretsRef, role } };
-}
-function fragmentPathFor(entityId, home) {
-    return join(humansDir(home), `${entityId}.yaml`);
-}
-function knownEntityIds(home) {
-    const dir = humansDir(home);
-    if (!existsSync(dir))
-        return [];
-    return readdirSync(dir)
-        .filter((f) => f.endsWith(".yaml") && !f.startsWith("."))
-        .map((f) => f.slice(0, -".yaml".length))
-        .sort();
-}
-function unknownHumanError(entityId, home) {
-    const known = knownEntityIds(home);
-    return `no human "${entityId}" is registered — known humans: ${known.length ? known.join(", ") : "(none)"}`;
-}
-export function listHumans(home = getOpenRigHome()) {
-    const proj = projectHumans(home);
-    if (!proj.ok)
-        return { ok: false, error: proj.error };
-    const humans = proj.entities.map((e) => {
-        const primary = e.connectorBindings.find((b) => b.role === "primary");
-        return {
-            entityId: e.entityId,
-            displayName: e.displayName,
-            address: e.address,
-            deliveryClass: e.prefs.deliveryClass,
-            away: e.prefs.away === true,
-            bindings: {
-                count: e.connectorBindings.length,
-                primary: { kind: primary.kind, connectorRef: primary.connectorRef },
-                inboundResolvable: e.connectorBindings.some((b) => b.handle !== undefined),
-            },
-            fragmentPath: fragmentPathFor(e.entityId, home),
-        };
-    });
-    return humans.length > 1 ? { ok: true, humans, advisory: MULTI_HUMAN_ADVISORY } : { ok: true, humans };
-}
-/** Read one fragment RAW (for authored-vs-default provenance) + validated. */
-function readFragment(entityId, home) {
-    const path = fragmentPathFor(entityId, home);
-    if (!existsSync(path))
-        return { ok: false, error: unknownHumanError(entityId, home) };
-    let raw;
-    try {
-        raw = parseYaml(readFileSync(path, "utf8"));
-    }
-    catch (err) {
-        return { ok: false, error: `failed to parse human fragment ${entityId}.yaml: ${err.message}` };
-    }
-    const v = validateHumanFragment(raw);
-    if (!v.ok)
-        return { ok: false, error: `invalid human fragment ${entityId}.yaml: ${v.error}` };
-    return { ok: true, raw: raw, fragment: v.fragment, path };
-}
-export function showHuman(entityId, home = getOpenRigHome()) {
-    const f = readFragment(entityId, home);
-    if (!f.ok)
-        return f;
-    const rawPrefs = isObj(f.raw.prefs) ? f.raw.prefs : {};
-    return {
-        ok: true,
-        record: {
-            entityId: f.fragment.entityId,
-            address: f.fragment.address,
-            displayName: f.fragment.displayName,
-            fragmentPath: f.path,
-            prefs: {
-                deliveryClass: { value: f.fragment.prefs.deliveryClass, source: "authored" },
-                away: {
-                    value: f.fragment.prefs.away === true,
-                    source: rawPrefs.away !== undefined ? "authored" : "default",
-                },
-            },
-            connectorBindings: f.fragment.connectorBindings.map((b) => ({ ...b, inboundResolvable: b.handle !== undefined })),
-        },
-    };
-}
-const SETTABLE_FIELDS_TEACHING = "settable fields: display-name, delivery-class, away, binding.<n> (binding.<n> takes a full kind:connectorRef:secretsRef:role[:handle=<id>] spec)";
-/** Cross-fragment handle-uniqueness: the same pre-write check add runs (one platform id =
- *  one human), extracted so set enforces it identically. */
-function handleConflict(fragment, home) {
-    const existing = projectHumans(home);
-    if (!existing.ok)
-        return `cannot validate handle uniqueness — existing registry is invalid: ${existing.error}`;
-    const claimed = new Map();
-    for (const e of existing.entities) {
-        if (e.entityId === fragment.entityId)
-            continue;
-        for (const b of e.connectorBindings)
-            if (b.handle !== undefined)
-                claimed.set(`${b.kind}:${b.handle}`, e.entityId);
-    }
-    for (const b of fragment.connectorBindings) {
-        if (b.handle === undefined)
-            continue;
-        const owner = claimed.get(`${b.kind}:${b.handle}`);
-        if (owner !== undefined) {
-            return `${b.kind} handle "${b.handle}" is already registered to human "${owner}" — a handle maps to exactly one human (registration conflict)`;
-        }
-    }
-    return undefined;
-}
-export function setHumanField(entityId, field, value, home = getOpenRigHome()) {
-    const f = readFragment(entityId, home);
-    if (!f.ok)
-        return f;
-    // Edit the RAW mapping (not the normalized fragment) so an unauthored optional field
-    // stays unauthored — show's provenance depends on the authored shape surviving edits.
-    const raw = f.raw;
-    const rawPrefs = isObj(raw.prefs) ? raw.prefs : {};
-    if (field === "display-name") {
-        if (value.length === 0)
-            return { ok: false, error: "display-name must be a non-empty string" };
-        raw.displayName = value;
-    }
-    else if (field === "delivery-class") {
-        rawPrefs.deliveryClass = value; // enum validated below by the SAME add-time validator
-        raw.prefs = rawPrefs;
-    }
-    else if (field === "away") {
-        if (value !== "true" && value !== "false") {
-            return { ok: false, error: `away must be true|false (got "${value}")` };
-        }
-        rawPrefs.away = value === "true";
-        raw.prefs = rawPrefs;
-    }
-    else if (field.startsWith("binding.")) {
-        const idxRaw = field.slice("binding.".length);
-        const idx = /^\d+$/.test(idxRaw) ? Number.parseInt(idxRaw, 10) : NaN;
-        const bindings = Array.isArray(raw.connectorBindings) ? raw.connectorBindings : [];
-        if (!Number.isInteger(idx) || idx < 0 || idx >= bindings.length) {
-            const valid = bindings.map((_, i) => `binding.${i}`).join(", ");
-            return { ok: false, error: `"${field}" is out of range — this human has ${bindings.length} binding(s): ${valid || "(none)"}` };
-        }
-        const parsed = parseBindingSpec(value);
-        if (!parsed.ok)
-            return parsed;
-        bindings[idx] = parsed.binding;
-        raw.connectorBindings = bindings;
-    }
-    else {
-        return { ok: false, error: `unknown field "${field}" — ${SETTABLE_FIELDS_TEACHING}` };
-    }
-    // Full add-time parity: structural + closed enums + cross-field invariants...
-    const v = validateHumanFragment(raw);
-    if (!v.ok)
-        return { ok: false, error: v.error };
-    if (v.fragment.entityId !== entityId) {
-        return { ok: false, error: `set must not change entityId (fragment key)` };
-    }
-    // ...plus the cross-fragment handle-uniqueness pre-write check add runs.
-    const conflict = handleConflict(v.fragment, home);
-    if (conflict)
-        return { ok: false, error: conflict };
-    const w = atomicWrite(f.path, stringifyYaml(raw));
-    if (!w.ok)
-        return { ok: false, error: w.error };
-    const proj = writeProjection(home);
-    if (!proj.ok)
-        return { ok: false, error: `fragment written but re-projection failed: ${proj.error}` };
-    return { ok: true, path: f.path, fragment: v.fragment };
-}
-export function removeHumanFragment(entityId, opts, home = getOpenRigHome()) {
-    const path = fragmentPathFor(entityId, home);
-    if (!existsSync(path))
-        return { ok: false, error: unknownHumanError(entityId, home) };
-    if (!opts.force && opts.inflight.length > 0) {
-        const lines = opts.inflight.map((i) => `  - ${i.kind} ${i.id} — ${i.detail}`).join("\n");
-        return {
-            ok: false,
-            inflight: opts.inflight,
-            error: `refusing to remove "${entityId}" — ${opts.inflight.length} in-flight item(s) would be orphaned:\n${lines}\n` +
-                `Resolve them first, or pass --force to archive anyway (every in-flight item above will be recorded as orphaned, never silently dropped).`,
-        };
-    }
-    // Archive, never delete bytes. Collision-safe name (ms timestamp + counter fallback).
-    const archiveDir = join(humansDir(home), ".archive");
-    try {
-        mkdirSync(archiveDir, { recursive: true });
-    }
-    catch (err) {
-        return { ok: false, error: `failed to create archive dir ${archiveDir}: ${err.message}` };
-    }
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    let archivedPath = join(archiveDir, `${entityId}.${stamp}.yaml`);
-    for (let n = 1; existsSync(archivedPath); n++)
-        archivedPath = join(archiveDir, `${entityId}.${stamp}-${n}.yaml`);
-    try {
-        renameSync(path, archivedPath);
-    }
-    catch (err) {
-        return { ok: false, error: `failed to archive ${path}: ${err.message}` };
-    }
-    let orphanRecordPath;
-    if (opts.inflight.length > 0) {
-        orphanRecordPath = archivedPath.replace(/\.yaml$/, ".orphans.json");
-        const record = { entityId, archivedFragment: archivedPath, orphaned: opts.inflight };
-        const w = atomicWrite(orphanRecordPath, JSON.stringify(record, null, 2));
-        if (!w.ok)
-            return { ok: false, error: `fragment archived to ${archivedPath} but the orphan record failed: ${w.error}` };
-    }
-    const proj = writeProjection(home);
-    if (!proj.ok)
-        return { ok: false, error: `fragment archived to ${archivedPath} but re-projection failed: ${proj.error}` };
-    const base = { ok: true, removed: entityId, archivedPath };
-    return orphanRecordPath !== undefined ? { ...base, orphanRecordPath } : base;
-}
-/** The dispatch-buffer half of the remove guard: un-Acked outbound decisions bound to this
- *  entity are open conversations. Match rule (documented, not guessed): entityBindingRef equal
- *  to the entityId, equal to its registered address, or prefixed "<entityId>:". */
-export function pendingConversationsFor(entityId, home = getOpenRigHome()) {
-    const address = `${entityId}@${ADDRESS_DOMAIN}`;
-    return new DispatchBuffer(home)
-        .pending()
-        .filter((d) => d.entityBindingRef === entityId || d.entityBindingRef === address || d.entityBindingRef.startsWith(`${entityId}:`))
-        .map((d) => ({
-        kind: "open-conversation",
-        id: d.decisionId,
-        detail: `undelivered outbound decision ${d.decisionId} (op ${d.op}, binding ${d.entityBindingRef})`,
-    }));
-}
-/** Recognize only projection bytes an adopted generator could have emitted. The
- * parsed snapshot is validation evidence, never identity input; current fragments
- * remain the registry truth and are re-projected after a compatible old format. */
-function canonicalProjectionSnapshot(body, expectedEntityBody) {
-    let entityBody;
-    let expectedDigest;
-    let format;
-    if (body.startsWith(PROJECTION_V2_HEADER)) {
-        format = "v2";
-        const remainder = body.slice(PROJECTION_V2_HEADER.length);
-        const digestLineEnd = remainder.indexOf("\n");
-        if (digestLineEnd < 0 || !remainder.startsWith(PROJECTION_DIGEST_PREFIX)) {
-            return { ok: false, error: "the v2 projection digest line is missing or changed" };
-        }
-        expectedDigest = remainder.slice(PROJECTION_DIGEST_PREFIX.length, digestLineEnd);
-        if (!/^[a-f0-9]{64}$/.test(expectedDigest)) {
-            return { ok: false, error: "the v2 projection digest is malformed" };
-        }
-        entityBody = remainder.slice(digestLineEnd + 1);
-    }
-    else if (body.startsWith(PROJECTION_HEADER)) {
-        format = "legacy";
-        entityBody = body.slice(PROJECTION_HEADER.length);
-    }
-    else {
-        return { ok: false, error: "the generated header is missing or changed" };
-    }
-    let raw;
-    try {
-        raw = parseYaml(entityBody);
-    }
-    catch (err) {
-        return { ok: false, error: `the generated YAML does not parse: ${err.message}` };
-    }
-    if (!isObj(raw) || Object.keys(raw).length !== 1 || !Array.isArray(raw.entities)) {
-        return { ok: false, error: "the generated body must contain exactly one entities list" };
-    }
-    const entities = [];
-    for (let i = 0; i < raw.entities.length; i++) {
-        const validated = validateHumanFragment(raw.entities[i]);
-        if (!validated.ok) {
-            return { ok: false, error: `generated entities[${i}] is invalid: ${validated.error}` };
-        }
-        entities.push(validated.fragment);
-    }
-    entities.sort((a, b) => (a.entityId < b.entityId ? -1 : a.entityId > b.entityId ? 1 : 0));
-    const collectionError = validateEntityCollection(entities);
-    if (collectionError)
-        return { ok: false, error: collectionError };
-    const canonicalEntityBody = stringifyYaml({ entities });
-    if (entityBody !== canonicalEntityBody) {
-        return { ok: false, error: "the generated bytes are not canonical (manual edits or extra content are present)" };
-    }
-    if (expectedDigest !== undefined) {
-        const actualDigest = createHash("sha256").update(canonicalEntityBody).digest("hex");
-        if (actualDigest !== expectedDigest) {
-            return { ok: false, error: "the v2 projection digest does not match its generated body (manual edit detected)" };
-        }
-    }
-    if (canonicalEntityBody !== expectedEntityBody) {
-        return { ok: false, error: "the generated body does not match the current fragment truth (manual edit detected)" };
-    }
-    return { ok: true, format };
-}
-/** Load the registry via the projection, but REFUSE a hand-edited/drifted projection:
- *  the fragments are truth, so identities always come from a fresh fragment projection.
- *  A canonical snapshot from an adopted projection format is compatible and is
- *  rewritten atomically; malformed/non-canonical bytes remain a loud error. */
-export function loadHumanRegistry(home = getOpenRigHome(), opts = {}) {
-    const proj = projectHumans(home);
-    if (!proj.ok)
-        return { ok: false, error: proj.error };
-    const path = projectionPath(home);
-    if (!existsSync(path)) {
-        return { ok: false, error: `registry projection missing at ${path} — re-project from the fragments` };
-    }
-    const stored = readFileSync(path, "utf8");
-    if (stored !== proj.body) {
-        const snapshot = canonicalProjectionSnapshot(stored, stringifyYaml({ entities: proj.entities }));
-        if (!snapshot.ok) {
-            return {
-                ok: false,
-                error: `registry projection HAND-EDITED or drifted at ${path}: ${snapshot.error}. The fragment files remain identity truth; repair by re-projecting them, never by re-adding an existing human or editing the generated file`,
-            };
-        }
-        if (opts.readOnly)
-            return { ok: true, entities: proj.entities };
-        const repaired = atomicWrite(path, proj.body);
-        if (!repaired.ok) {
-            return { ok: false, error: `registry projection drift at ${path}: fragment truth was valid, but atomic re-projection failed: ${repaired.error}` };
-        }
-    }
-    return { ok: true, entities: proj.entities };
-}
-/** Resolve every registered spelling of a human to its canonical external address.
- * Identity comes from the registry entity, never from a domain/suffix allow-list. */
-export function resolveRegisteredHumanAddress(sessionRef, entities) {
-    if (!sessionRef)
-        return null;
-    const parsed = parseSessionName(sessionRef);
-    const identity = parsed.kind === "external"
-        ? parsed.local
-        : parsed.kind === "canonical"
-            ? parsed.member
-            : null;
-    if (!identity)
-        return null;
-    return entities.find((entity) => entity.entityId === identity)?.address ?? null;
-}
-//# sourceMappingURL=human-registry.js.map