attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/boundary/frame.js

@@ -1,9 +1,32 @@
 import { digestOf } from "../semantic/canonical.js";
+import { deepFreezeJson } from "../semantic/jsonValue.js";
+import { isDateTime } from "../semantic/time.js";
 import { isId } from "./ids.js";
+import { isRefKind } from "./kinds.js";
 import { BoundaryRejection } from "../error/boundaryRejection.js";
 const SchemaMaxSlots = 9;
 const DefaultMaxIgnored = 50;
 const BudgetDimensions = ["tokens", "ms", "calls", "interrupts", "money"];
+const FrameProperties = [
+    "id",
+    "agent",
+    "cycle",
+    "ts",
+    "parent",
+    "mode",
+    "goal",
+    "slots",
+    "ignored",
+    "budget",
+    "open_questions",
+    "impasse",
+    "note",
+];
+const SlotProperties = ["target", "role", "tier", "salience", "voi", "cost", "budget", "why", "ttl_turns", "state"];
+const IgnoredProperties = ["target", "reason", "revisit_if"];
+const RefProperties = ["kind", "id", "label"];
+const FrameBudgetProperties = ["allocated", "spent"];
+const ImpasseProperties = ["state", "detail"];
 const FrameModes = ["explore", "exploit", "triage", "reflect", "rest"];
 const SlotRoles = ["goal", "question", "evidence", "concept", "process", "tool", "memory", "self", "other", "threat", "artifact"];
 const SlotStates = ["active", "released", "evicted", "done"];
@@ -11,229 +34,443 @@ const IgnoredReasons = ["low_voi", "out_of_scope", "untrusted", "budget", "block
 const ImpasseStates = ["TIE", "STUCK", "STALLED", "CONFLICT", "INFEASIBLE", "UNKNOWN", "UNVERIFIED", "DRIFT", "BUDGET"];
 const Tiers = ["T0", "T1", "T2", "T3", "T4"];
 const isRecord = (value) => typeof (value) === "object" && value !== null && !Array.isArray(value);
-const checkBudget = (value, at, problems) => {
+/**
+ * A host draft must be a plain object (or null-prototype). Class instances,
+ * arrays and functions are not drafts, even though they can carry the fields.
+ */
+const isPlainRecord = (value) => {
     if (!isRecord(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype === Object.prototype;
+};
+const isRefTable = (value) => typeof (value) === "object" && value !== null && typeof (value.check) === "function";
+const reportUnknownProperties = (value, allowed, at, problems) => {
+    const keys = Object.keys(value);
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
+        if (!allowed.includes(key)) {
+            problems.push(at.length === 0 ? `unknown property "${key}"` : `${at}: unknown property "${key}"`);
+        }
+    }
+};
+/**
+ * Validate a budget-like object and return a fresh copy that only holds the
+ * five declared dimensions. `money` alone may be fractional.
+ */
+const readBudget = (value, at, problems) => {
+    if (!isPlainRecord(value)) {
         problems.push(`${at} must be an object`);
-        return;
+        return (void 0);
     }
-    const budgetKeys = Object.keys(value);
-    for (let keyIndex = 0; keyIndex < budgetKeys.length; keyIndex += 1) {
-        const key = budgetKeys[keyIndex];
+    const keys = Object.keys(value);
+    const budget = {};
+    let valid = true;
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index];
         const amount = value[key];
         if (!BudgetDimensions.includes(key)) {
             problems.push(`${at}.${key} is not a budget dimension`);
+            valid = false;
             continue;
         }
         if (typeof (amount) !== "number" || !Number.isFinite(amount) || amount < 0) {
             problems.push(`${at}.${key} must be a non-negative finite number`);
+            valid = false;
             continue;
         }
         if (key !== "money" && !Number.isInteger(amount)) {
             problems.push(`${at}.${key} must be an integer`);
+            valid = false;
+            continue;
         }
+        budget[key] = amount;
     }
+    return valid ? budget : (void 0);
 };
-const checkRef = (value, refs, at, problems) => {
-    if (!isRecord(value)) {
+/**
+ * Validate a reference and return a fresh copy. Opaque kinds pass on shape
+ * alone; every other kind must resolve in the supplied scope.
+ */
+const readRef = (value, refs, at, problems) => {
+    if (!isPlainRecord(value)) {
         problems.push(`${at} must be a Ref object`);
-        return;
+        return (void 0);
     }
-    if (typeof (value.kind) !== "string" || !isId(value.id)) {
-        problems.push(`${at} must have a string kind and a valid id`);
-        return;
+    reportUnknownProperties(value, RefProperties, at, problems);
+    const kind = value.kind;
+    const id = value.id;
+    const label = value.label;
+    let shapeValid = true;
+    if (!isRefKind(kind)) {
+        problems.push(`${at}.kind is not a ref kind`);
+        shapeValid = false;
     }
-    if (!refs.has(value)) {
-        const problem = refs.check(value);
-        if (problem !== (void 0)) {
-            problems.push(`${at} ${problem}`);
-        }
+    if (!isId(id)) {
+        problems.push(`${at}.id is not a valid AMP id`);
+        shapeValid = false;
+    }
+    if (label !== (void 0) && typeof (label) !== "string") {
+        problems.push(`${at}.label must be a string`);
+        shapeValid = false;
     }
+    if (!shapeValid) {
+        return (void 0);
+    }
+    const ref = { kind: kind, id: id };
+    if (label !== (void 0)) {
+        ref.label = label;
+    }
+    const problem = refs.check(ref);
+    if (problem !== (void 0)) {
+        problems.push(`${at} ${problem}`);
+    }
+    return ref;
 };
-const checkSlot = (value, refs, at, problems) => {
-    if (!isRecord(value)) {
+/**
+ * Validate a slot and return a fresh copy with only the schema fields.
+ */
+const readSlot = (value, refs, at, problems) => {
+    if (!isPlainRecord(value)) {
         problems.push(`${at} must be an object`);
-        return;
+        return (void 0);
     }
-    checkRef(value.target, refs, `${at}.target`, problems);
-    if (typeof (value.role) !== "string" || !SlotRoles.includes(value.role)) {
+    const problemCount = problems.length;
+    reportUnknownProperties(value, SlotProperties, at, problems);
+    const target = readRef(value.target, refs, `${at}.target`, problems);
+    const role = value.role;
+    if (typeof (role) !== "string" || !SlotRoles.includes(role)) {
         problems.push(`${at}.role is not a slot role`);
     }
+    const tier = value.tier;
+    if (tier !== (void 0) && (typeof (tier) !== "string" || !Tiers.includes(tier))) {
+        problems.push(`${at}.tier is not a tier`);
+    }
     const salience = value.salience;
-    if (typeof (salience) !== "number" || salience < 0 || salience > 1) {
+    if (typeof (salience) !== "number" || !Number.isFinite(salience) || salience < 0 || salience > 1) {
         problems.push(`${at}.salience must be in [0,1]`);
     }
-    if (typeof (value.why) !== "string" || value.why.trim().length === 0) {
+    const voi = value.voi;
+    if (voi !== (void 0) && (typeof (voi) !== "number" || !Number.isFinite(voi) || voi < 0 || voi > 1)) {
+        problems.push(`${at}.voi must be in [0,1]`);
+    }
+    const cost = readBudget(value.cost, `${at}.cost`, problems);
+    const budget = value.budget === (void 0) ? (void 0) : readBudget(value.budget, `${at}.budget`, problems);
+    const why = value.why;
+    if (typeof (why) !== "string" || why.trim().length === 0) {
         problems.push(`${at}.why is empty`);
     }
-    checkBudget(value.cost, `${at}.cost`, problems);
-    if (typeof (value.state) !== "string" || !SlotStates.includes(value.state)) {
+    const ttlTurns = value.ttl_turns;
+    if (ttlTurns !== (void 0) && (typeof (ttlTurns) !== "number" || !Number.isSafeInteger(ttlTurns) || ttlTurns < 0)) {
+        problems.push(`${at}.ttl_turns must be a non-negative integer`);
+    }
+    const state = value.state;
+    if (typeof (state) !== "string" || !SlotStates.includes(state)) {
         problems.push(`${at}.state is not a slot state`);
     }
-    if (value.tier !== (void 0) && (typeof (value.tier) !== "string" || !Tiers.includes(value.tier))) {
-        problems.push(`${at}.tier is not a tier`);
+    if (problems.length !== problemCount || target === (void 0) || cost === (void 0)) {
+        return (void 0);
     }
-    const voi = value.voi;
-    if (voi !== (void 0) && (typeof (voi) !== "number" || voi < 0 || voi > 1)) {
-        problems.push(`${at}.voi must be in [0,1]`);
+    const slot = {
+        target,
+        role: role,
+        salience: salience,
+        cost,
+        why: why,
+        state: state,
+    };
+    if (tier !== (void 0)) {
+        slot.tier = tier;
     }
-    if (value.budget !== (void 0)) {
-        checkBudget(value.budget, `${at}.budget`, problems);
+    if (voi !== (void 0)) {
+        slot.voi = voi;
     }
-    const ttlTurns = value.ttl_turns;
-    if (ttlTurns !== (void 0) && (typeof (ttlTurns) !== "number" || !Number.isInteger(ttlTurns) || ttlTurns < 0)) {
-        problems.push(`${at}.ttl_turns must be a non-negative integer`);
+    if (budget !== (void 0)) {
+        slot.budget = budget;
+    }
+    if (ttlTurns !== (void 0)) {
+        slot.ttl_turns = ttlTurns;
     }
+    return slot;
 };
-const checkIgnored = (value, refs, at, problems) => {
-    if (!isRecord(value)) {
+/**
+ * Validate a deliberate exclusion and return a fresh copy.
+ */
+const readIgnored = (value, refs, at, problems) => {
+    if (!isPlainRecord(value)) {
         problems.push(`${at} must be an object`);
-        return;
+        return (void 0);
     }
-    checkRef(value.target, refs, `${at}.target`, problems);
-    if (typeof (value.reason) !== "string" || !IgnoredReasons.includes(value.reason)) {
+    const problemCount = problems.length;
+    reportUnknownProperties(value, IgnoredProperties, at, problems);
+    const target = readRef(value.target, refs, `${at}.target`, problems);
+    const reason = value.reason;
+    if (typeof (reason) !== "string" || !IgnoredReasons.includes(reason)) {
         problems.push(`${at}.reason is not an ignored reason`);
     }
-    if (typeof (value.revisit_if) !== "string" || value.revisit_if.trim().length === 0) {
+    const revisitIf = value.revisit_if;
+    if (typeof (revisitIf) !== "string" || revisitIf.trim().length === 0) {
         problems.push(`${at}.revisit_if is empty`);
     }
+    if (problems.length !== problemCount || target === (void 0)) {
+        return (void 0);
+    }
+    return { target, reason: reason, revisit_if: revisitIf };
 };
-const checkImpasse = (value, at, problems) => {
-    if (!isRecord(value)) {
+/**
+ * Validate an impasse marker and return a fresh copy.
+ */
+const readImpasse = (value, at, problems) => {
+    if (!isPlainRecord(value)) {
         problems.push(`${at} must be an object`);
-        return;
+        return (void 0);
     }
-    if (typeof (value.state) !== "string" || !ImpasseStates.includes(value.state)) {
+    const problemCount = problems.length;
+    reportUnknownProperties(value, ImpasseProperties, at, problems);
+    const state = value.state;
+    if (typeof (state) !== "string" || !ImpasseStates.includes(state)) {
         problems.push(`${at}.state is not an impasse state`);
     }
-    if (value.detail !== (void 0) && typeof (value.detail) !== "string") {
+    const detail = value.detail;
+    if (detail !== (void 0) && typeof (detail) !== "string") {
         problems.push(`${at}.detail must be a string`);
     }
+    if (problems.length !== problemCount) {
+        return (void 0);
+    }
+    const impasse = { state: state };
+    if (detail !== (void 0)) {
+        impasse.detail = detail;
+    }
+    return impasse;
 };
 /**
  * Validate a draft and return the only frame it permits.
  *
  * @throws BoundaryRejection `invalid_frame` with every problem found.
  */
-export const frameFrom = (draft, refs, options = {}) => {
+const buildFrame = (draft, refs, options = {}) => {
+    if (!isPlainRecord(draft)) {
+        throw new BoundaryRejection("invalid_frame", ["draft must be an object"]);
+    }
+    if (!isRefTable(refs)) {
+        throw new BoundaryRejection("invalid_frame", ["refs must be a RefTable"]);
+    }
+    if (!isRecord(options)) {
+        throw new BoundaryRejection("invalid_frame", ["options must be an object"]);
+    }
     const problems = [];
-    if (!isId(draft.id)) {
+    const source = draft;
+    const optionRecord = options;
+    reportUnknownProperties(source, FrameProperties, "", problems);
+    const id = source.id;
+    if (!isId(id)) {
         problems.push("id is not a valid AMP id");
     }
-    if (!isId(draft.agent)) {
+    const agent = source.agent;
+    if (!isId(agent)) {
         problems.push("agent is not a valid AMP id");
     }
-    if (!Number.isSafeInteger(draft.cycle) || draft.cycle < 0) {
+    const cycle = source.cycle;
+    if (typeof (cycle) !== "number" || !Number.isSafeInteger(cycle) || cycle < 0) {
         problems.push("cycle must be a non-negative integer");
     }
-    if (!FrameModes.includes(draft.mode)) {
+    const mode = source.mode;
+    if (typeof (mode) !== "string" || !FrameModes.includes(mode)) {
         problems.push("mode is not a frame mode");
     }
-    const ts = draft.ts ?? (options.now ? options.now() : new Date().toISOString());
-    if (typeof (ts) !== "string" || Number.isNaN(Date.parse(ts))) {
-        problems.push("ts is not a date-time");
+    const clock = optionRecord.now;
+    let ts;
+    if (Object.hasOwn(source, "ts")) {
+        ts = source.ts;
+        if (typeof (ts) !== "string" || !isDateTime(ts)) {
+            problems.push("ts is not a date-time");
+        }
     }
-    const requestedMaxSlots = options.maxSlots ?? SchemaMaxSlots;
-    if (!Number.isInteger(requestedMaxSlots) || requestedMaxSlots < 0 || requestedMaxSlots > SchemaMaxSlots) {
-        problems.push(`maxSlots must be an integer in [0,${SchemaMaxSlots}]`);
+    else if (clock === (void 0)) {
+        ts = new Date().toISOString();
+        if (typeof (ts) !== "string" || !isDateTime(ts)) {
+            problems.push("ts is not a date-time");
+        }
+    }
+    else if (typeof (clock) !== "function") {
+        ts = (void 0);
+        problems.push("now must be a function");
+    }
+    else {
+        try {
+            ts = clock();
+        }
+        catch {
+            ts = (void 0);
+        }
+        if (typeof (ts) !== "string" || !isDateTime(ts)) {
+            problems.push("ts is not a date-time");
+        }
     }
-    const maxSlots = Math.min(Math.max(0, requestedMaxSlots), SchemaMaxSlots);
-    const requestedMaxIgnored = options.maxIgnored ?? DefaultMaxIgnored;
-    if (!Number.isInteger(requestedMaxIgnored) || requestedMaxIgnored < 0) {
-        problems.push("maxIgnored must be a non-negative integer");
+    const requestedMaxSlots = optionRecord.maxSlots === (void 0) ? SchemaMaxSlots : optionRecord.maxSlots;
+    const maxSlotsValid = typeof (requestedMaxSlots) === "number" && Number.isInteger(requestedMaxSlots) && requestedMaxSlots >= 0 && requestedMaxSlots <= SchemaMaxSlots;
+    if (!maxSlotsValid) {
+        problems.push(`maxSlots must be an integer in [0,${SchemaMaxSlots}]`);
     }
-    const maxIgnored = Math.max(0, requestedMaxIgnored);
-    if (!Array.isArray(draft.slots)) {
+    const maxSlots = maxSlotsValid ? requestedMaxSlots : SchemaMaxSlots;
+    const requestedMaxIgnored = optionRecord.maxIgnored === (void 0) ? DefaultMaxIgnored : optionRecord.maxIgnored;
+    const maxIgnoredValid = typeof (requestedMaxIgnored) === "number" &&
+        Number.isInteger(requestedMaxIgnored) &&
+        requestedMaxIgnored >= 0 &&
+        requestedMaxIgnored <= DefaultMaxIgnored;
+    if (!maxIgnoredValid) {
+        problems.push(`maxIgnored must be an integer in [0,${DefaultMaxIgnored}]`);
+    }
+    const maxIgnored = maxIgnoredValid ? requestedMaxIgnored : DefaultMaxIgnored;
+    const rebuiltSlots = [];
+    const declaredSlots = source.slots;
+    if (!Array.isArray(declaredSlots)) {
         problems.push("slots must be an array");
     }
     else {
-        if (draft.slots.length > maxSlots) {
-            problems.push(`slots has ${draft.slots.length} entries, max is ${maxSlots}`);
+        if (declaredSlots.length > maxSlots) {
+            problems.push(`slots has ${declaredSlots.length} entries, max is ${maxSlots}`);
+        }
+        for (let index = 0; index < declaredSlots.length; index += 1) {
+            const rebuilt = readSlot(declaredSlots[index], refs, `slots[${index}]`, problems);
+            if (rebuilt !== (void 0)) {
+                rebuiltSlots.push(rebuilt);
+            }
         }
-        draft.slots.forEach((slot, index) => checkSlot(slot, refs, `slots[${index}]`, problems));
     }
-    const declaredIgnored = draft.ignored;
-    const ignored = Array.isArray(declaredIgnored) ? declaredIgnored : [];
-    if (declaredIgnored !== (void 0) && !Array.isArray(declaredIgnored)) {
-        problems.push("ignored must be an array");
+    const rebuiltIgnored = [];
+    const declaredIgnored = source.ignored;
+    if (declaredIgnored !== (void 0)) {
+        if (!Array.isArray(declaredIgnored)) {
+            problems.push("ignored must be an array");
+        }
+        else {
+            for (let index = 0; index < declaredIgnored.length; index += 1) {
+                const rebuilt = readIgnored(declaredIgnored[index], refs, `ignored[${index}]`, problems);
+                if (rebuilt !== (void 0)) {
+                    rebuiltIgnored.push(rebuilt);
+                }
+            }
+        }
     }
-    ignored.forEach((item, index) => checkIgnored(item, refs, `ignored[${index}]`, problems));
-    const budgetValue = draft.budget;
-    if (!isRecord(budgetValue)) {
+    let frameBudget;
+    const declaredBudget = source.budget;
+    if (!isPlainRecord(declaredBudget)) {
         problems.push("budget must be an object");
     }
     else {
-        const allocated = budgetValue.allocated;
-        const spent = budgetValue.spent;
-        checkBudget(allocated, "budget.allocated", problems);
-        checkBudget(spent, "budget.spent", problems);
-        if (isRecord(allocated) && isRecord(spent)) {
+        reportUnknownProperties(declaredBudget, FrameBudgetProperties, "budget", problems);
+        const allocated = readBudget(declaredBudget.allocated, "budget.allocated", problems);
+        const spent = readBudget(declaredBudget.spent, "budget.spent", problems);
+        if (allocated !== (void 0) && spent !== (void 0)) {
             if (Object.keys(allocated).length === 0) {
                 problems.push("budget.allocated must set at least one dimension");
             }
-            for (let dimensionIndex = 0; dimensionIndex < BudgetDimensions.length; dimensionIndex += 1) {
-                const key = BudgetDimensions[dimensionIndex];
+            const spentKeys = Object.keys(spent);
+            for (let index = 0; index < spentKeys.length; index += 1) {
+                const key = spentKeys[index];
+                if (!Object.hasOwn(allocated, key)) {
+                    problems.push(`budget.spent.${key} is not declared in budget.allocated`);
+                    continue;
+                }
                 const limit = allocated[key];
                 const used = spent[key];
                 if (typeof (limit) === "number" && typeof (used) === "number" && used > limit) {
                     problems.push(`budget.spent.${key} exceeds budget.allocated.${key}`);
                 }
             }
+            frameBudget = { allocated, spent };
         }
     }
-    if (draft.parent !== (void 0)) {
-        checkRef(draft.parent, refs, "parent", problems);
+    let parent;
+    const declaredParent = source.parent;
+    if (declaredParent !== (void 0)) {
+        parent = readRef(declaredParent, refs, "parent", problems);
     }
-    if (draft.goal !== (void 0)) {
-        checkRef(draft.goal, refs, "goal", problems);
+    let goal;
+    const declaredGoal = source.goal;
+    if (declaredGoal !== (void 0)) {
+        goal = readRef(declaredGoal, refs, "goal", problems);
     }
-    if (draft.open_questions !== (void 0)) {
-        if (!Array.isArray(draft.open_questions)) {
+    const rebuiltQuestions = [];
+    const declaredQuestions = source.open_questions;
+    if (declaredQuestions !== (void 0)) {
+        if (!Array.isArray(declaredQuestions)) {
             problems.push("open_questions must be an array");
         }
         else {
-            draft.open_questions.forEach((ref, index) => checkRef(ref, refs, `open_questions[${index}]`, problems));
+            for (let index = 0; index < declaredQuestions.length; index += 1) {
+                const rebuilt = readRef(declaredQuestions[index], refs, `open_questions[${index}]`, problems);
+                if (rebuilt !== (void 0)) {
+                    rebuiltQuestions.push(rebuilt);
+                }
+            }
         }
     }
-    if (draft.impasse !== (void 0)) {
-        checkImpasse(draft.impasse, "impasse", problems);
+    let impasse;
+    const declaredImpasse = source.impasse;
+    if (declaredImpasse !== (void 0)) {
+        impasse = readImpasse(declaredImpasse, "impasse", problems);
     }
-    if (draft.note !== (void 0) && typeof (draft.note) !== "string") {
+    const declaredNote = source.note;
+    if (declaredNote !== (void 0) && typeof (declaredNote) !== "string") {
         problems.push("note must be a string");
     }
     if (problems.length > 0) {
         throw new BoundaryRejection("invalid_frame", problems);
     }
-    const visible = ignored.slice(0, maxIgnored);
-    const deferred = ignored.slice(maxIgnored);
+    const visible = rebuiltIgnored.slice(0, maxIgnored);
+    const deferred = rebuiltIgnored.slice(maxIgnored);
     const body = {
         amp: "0.1",
         kind: "frame",
-        id: draft.id,
-        agent: draft.agent,
-        cycle: draft.cycle,
-        ts,
-        mode: draft.mode,
-        slots: [...draft.slots],
-        budget: { allocated: { ...draft.budget.allocated }, spent: { ...draft.budget.spent } },
+        id: id,
+        agent: agent,
+        cycle: cycle,
+        ts: ts,
+        mode: mode,
+        slots: rebuiltSlots,
+        budget: frameBudget,
     };
-    if (draft.parent !== (void 0)) {
-        body.parent = draft.parent;
+    if (parent !== (void 0)) {
+        body.parent = parent;
     }
-    if (draft.goal !== (void 0)) {
-        body.goal = draft.goal;
+    if (goal !== (void 0)) {
+        body.goal = goal;
     }
     if (visible.length > 0) {
         body.ignored = visible;
     }
-    if (draft.open_questions !== (void 0)) {
-        body.open_questions = [...draft.open_questions];
+    if (declaredQuestions !== (void 0)) {
+        body.open_questions = rebuiltQuestions;
     }
-    if (draft.impasse !== (void 0)) {
-        body.impasse = draft.impasse;
+    if (impasse !== (void 0)) {
+        body.impasse = impasse;
     }
-    if (draft.note !== (void 0)) {
-        body.note = draft.note;
+    if (declaredNote !== (void 0)) {
+        body.note = declaredNote;
     }
     const frame = { ...body, digest: digestOf(body) };
+    deepFreezeJson(frame);
+    deepFreezeJson(deferred);
     return { frame, deferred };
 };
+/**
+ * Public entry point. A revoked `Proxy`, a throwing getter or an exotic
+ * `refs` object can still throw while the draft is inspected; the boundary
+ * contract is that callers only ever see `BoundaryRejection`.
+ */
+export const frameFrom = (draft, refs, options = {}) => {
+    try {
+        return buildFrame(draft, refs, options);
+    }
+    catch (error) {
+        if (error instanceof BoundaryRejection) {
+            throw error;
+        }
+        const reason = error instanceof Error ? error.message : typeof (error);
+        throw new BoundaryRejection("invalid_frame", [`draft could not be inspected: ${reason}`]);
+    }
+};

package/lib/boundary/kinds.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Runtime mirror of `RefKind` (`src/types/common.ts` / `common.schema.json`).
+ *
+ * TypeScript unions disappear at runtime, so a boundary that accepts JSON or
+ * JavaScript callers cannot rely on the compiler to keep `kind` inside the
+ * closed set. This module is the single runtime list both `RefTable` and
+ * `frameFrom` consult.
+ */
+import type { RefKind } from "../types/common.js";
+export declare const RefKinds: ReadonlySet<RefKind>;
+export declare const isRefKind: (value: unknown) => value is RefKind;

package/lib/boundary/kinds.js

@@ -0,0 +1,33 @@
+export const RefKinds = new Set([
+    "entity",
+    "concept",
+    "process",
+    "thread",
+    "question",
+    "hypothesis",
+    "claim",
+    "evidence",
+    "goal",
+    "plan",
+    "task",
+    "tool",
+    "memory",
+    "other",
+    "human",
+    "agent",
+    "event",
+    "handle",
+    "frame",
+    "self",
+    "unknown",
+    "common-ground",
+    "capability",
+    "receipt",
+    "org",
+    "role",
+    "duty",
+    "assignment",
+    "interaction",
+    "result-contract",
+]);
+export const isRefKind = (value) => typeof (value) === "string" && RefKinds.has(value);