@ai-matrx/agents 0.32.0 → 0.33.0

package/dist/mandates/index.d.cts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   a6b049dc158af5a226cdaee78dda64289fe8cf99
+ * aidream revision:   74afbd5d601164b5b5188572fd3d242dbed25996
  * generator version:  1.0.0
- * package version:    0.32.0
+ * package version:    0.33.0
  * active keys:        544
  * retiring keys:      0
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "a6b049dc158af5a226cdaee78dda64289fe8cf99";
+    readonly aidreamRevision: "74afbd5d601164b5b5188572fd3d242dbed25996";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.32.0";
+    readonly packageVersion: "0.33.0";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -629,6 +629,63 @@ declare function mandateKeyOfApp(appSlug: string, surfaceSlug?: string): Dynamic
  */
 declare function mandateKeyOfShortcut(shortcutSlug: string, surfaceSlug?: string): DynamicMandateKey;
 
+/**
+ * The Mandate CONTRACT, client-side — one leaf module so both the resolution
+ * path (`service.ts`) and the binding-editor path (`overrides.ts`) read the
+ * same shape without importing each other.
+ *
+ * 🚨 THE DOCUMENT-VARIABLE LAW (disease D4, Arman 2026-08-19). A Mandate's
+ * `required_variables` are not decoration and not only a BIND-time check
+ * against what the agent declares. They are also a RUN-time precondition on
+ * what the CALLER supplies:
+ *
+ *   "this agent should never have even started without getting the rules in
+ *    place."
+ *
+ * `missingRequiredVariables` is the one implementation of that check. A run
+ * whose required variable is absent or blank REFUSES — there is no seed
+ * fallback and no "the model can fetch it with a tool" consolation, because a
+ * document that arrives by tool call is a document that gets skimmed.
+ *
+ * Law: `common-docs/systems/agent-variable-binding/FEATURE.md` § THE
+ * USER-INPUT LAW · register: `common-docs/operations/agent-failure-diseases.md` § D4.
+ */
+
+interface MandateContract {
+    requiredVariables: string[];
+    requiredContextPolicyKeys: string[];
+    requiredOutputKeys: string[];
+    /**
+     * Variables the contract deliberately delivers as user text instead of a
+     * declared variable (Scenario 4). A spilled variable still ARRIVES, so it is
+     * never counted as missing — but structured content may never take this
+     * path.
+     */
+    spillVariables: string[];
+    /**
+     * The Mandate's context kill switch (`contract.auto_context_disabled`): only
+     * the Holder's declared Context Policies reach it, unless the person turned a
+     * value on themselves (common-docs context-delivery RULES.md §2). The
+     * composer's context table needs it to show the truth before the first turn.
+     */
+    autoContextDisabled: boolean;
+}
+declare const EMPTY_MANDATE_CONTRACT: MandateContract;
+declare function parseMandateContract(contract: unknown): MandateContract;
+/**
+ * Which of the Mandate's required variables the caller did NOT actually
+ * supply. Blank counts as missing: a required document that resolved to an
+ * empty string is the wiring failure this check exists to catch, and a
+ * deliberately empty document must still say so in words (see
+ * `features/masterwork/agent-context/rulebookDocument.ts`).
+ *
+ * Spilled variables are excluded — they arrive as user text, so they are
+ * delivered, just not as a named variable.
+ */
+declare function missingRequiredVariables(contract: MandateContract, supplied: Record<string, unknown> | null | undefined): string[];
+/** The one refusal message, so every surface says the same thing. */
+declare function missingVariablesMessage(mandateKey: AnyMandateKey, missing: string[]): string;
+
 /**
  * `@ai-matrx/agents/mandates` — the ONE place a TypeScript client learns a
  * mandate key.
@@ -693,5 +750,28 @@ declare function isMandateKey(value: unknown): value is MandateKey;
  * key set came from, and what to do — never a bare "invalid key".
  */
 declare function assertMandateKey(value: unknown, context?: string): asserts value is MandateKey;
+/**
+ * A DB-AUTHORED KEY THE GENERATED UNION CANNOT CARRY — the ONE typed door for
+ * a literal a client's mandate-key allowlist already governs.
+ *
+ * Two honest cases: an `origin='user'` mandate somebody created in the console
+ * (no generator built from code declarations can ever contain it), and a key
+ * aidream has declared but the installed `@ai-matrx/agents` predates. Because
+ * the parameter is a literal type, the key still appears verbatim at the call
+ * site for a hand-typed-key scanner and for a human reading the diff.
+ *
+ * 🚨 NOT an escape hatch for a declared key. A key in `MANDATE_KEYS` goes
+ * through `MANDATE_KEYS.<id>`; using this for one hides a real rename from the
+ * compiler. When the package publishes a key routed through here, delete the call.
+ */
+declare function dbAuthoredMandateKey<K extends string>(key: K): DynamicMandateKey;
+interface MandateKeyParts {
+    /** The feature/domain namespace before the first dot. */
+    feature: string;
+    /** The complete step name after the first dot; later dots are preserved. */
+    mandate: string;
+}
+/** Split canonical `<feature>.<mandate>` identity without losing information. */
+declare function splitMandateKey(mandateKey: string): MandateKeyParts;
 
-export { ALL_MANDATE_KEYS, type AnyMandateKey, DYNAMIC_MANDATE_FAMILIES, type DynamicMandateFamilyPrefix, type DynamicMandateKey, MANDATE_FAMILIES, MANDATE_KEYS, MANDATE_KEYS_META, type MandateFamilyMember, type MandateFamilyPrefix, type MandateKey, RETIRING_MANDATE_KEYS, assertMandateKey, isMandateKey, mandateKeyOfApp, mandateKeyOfShortcut, storedMandateKey };
+export { ALL_MANDATE_KEYS, type AnyMandateKey, DYNAMIC_MANDATE_FAMILIES, type DynamicMandateFamilyPrefix, type DynamicMandateKey, EMPTY_MANDATE_CONTRACT, MANDATE_FAMILIES, MANDATE_KEYS, MANDATE_KEYS_META, type MandateContract, type MandateFamilyMember, type MandateFamilyPrefix, type MandateKey, type MandateKeyParts, RETIRING_MANDATE_KEYS, assertMandateKey, dbAuthoredMandateKey, isMandateKey, mandateKeyOfApp, mandateKeyOfShortcut, missingRequiredVariables, missingVariablesMessage, parseMandateContract, splitMandateKey, storedMandateKey };

package/dist/mandates/index.d.ts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   a6b049dc158af5a226cdaee78dda64289fe8cf99
+ * aidream revision:   74afbd5d601164b5b5188572fd3d242dbed25996
  * generator version:  1.0.0
- * package version:    0.32.0
+ * package version:    0.33.0
  * active keys:        544
  * retiring keys:      0
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "a6b049dc158af5a226cdaee78dda64289fe8cf99";
+    readonly aidreamRevision: "74afbd5d601164b5b5188572fd3d242dbed25996";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.32.0";
+    readonly packageVersion: "0.33.0";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -629,6 +629,63 @@ declare function mandateKeyOfApp(appSlug: string, surfaceSlug?: string): Dynamic
  */
 declare function mandateKeyOfShortcut(shortcutSlug: string, surfaceSlug?: string): DynamicMandateKey;
 
+/**
+ * The Mandate CONTRACT, client-side — one leaf module so both the resolution
+ * path (`service.ts`) and the binding-editor path (`overrides.ts`) read the
+ * same shape without importing each other.
+ *
+ * 🚨 THE DOCUMENT-VARIABLE LAW (disease D4, Arman 2026-08-19). A Mandate's
+ * `required_variables` are not decoration and not only a BIND-time check
+ * against what the agent declares. They are also a RUN-time precondition on
+ * what the CALLER supplies:
+ *
+ *   "this agent should never have even started without getting the rules in
+ *    place."
+ *
+ * `missingRequiredVariables` is the one implementation of that check. A run
+ * whose required variable is absent or blank REFUSES — there is no seed
+ * fallback and no "the model can fetch it with a tool" consolation, because a
+ * document that arrives by tool call is a document that gets skimmed.
+ *
+ * Law: `common-docs/systems/agent-variable-binding/FEATURE.md` § THE
+ * USER-INPUT LAW · register: `common-docs/operations/agent-failure-diseases.md` § D4.
+ */
+
+interface MandateContract {
+    requiredVariables: string[];
+    requiredContextPolicyKeys: string[];
+    requiredOutputKeys: string[];
+    /**
+     * Variables the contract deliberately delivers as user text instead of a
+     * declared variable (Scenario 4). A spilled variable still ARRIVES, so it is
+     * never counted as missing — but structured content may never take this
+     * path.
+     */
+    spillVariables: string[];
+    /**
+     * The Mandate's context kill switch (`contract.auto_context_disabled`): only
+     * the Holder's declared Context Policies reach it, unless the person turned a
+     * value on themselves (common-docs context-delivery RULES.md §2). The
+     * composer's context table needs it to show the truth before the first turn.
+     */
+    autoContextDisabled: boolean;
+}
+declare const EMPTY_MANDATE_CONTRACT: MandateContract;
+declare function parseMandateContract(contract: unknown): MandateContract;
+/**
+ * Which of the Mandate's required variables the caller did NOT actually
+ * supply. Blank counts as missing: a required document that resolved to an
+ * empty string is the wiring failure this check exists to catch, and a
+ * deliberately empty document must still say so in words (see
+ * `features/masterwork/agent-context/rulebookDocument.ts`).
+ *
+ * Spilled variables are excluded — they arrive as user text, so they are
+ * delivered, just not as a named variable.
+ */
+declare function missingRequiredVariables(contract: MandateContract, supplied: Record<string, unknown> | null | undefined): string[];
+/** The one refusal message, so every surface says the same thing. */
+declare function missingVariablesMessage(mandateKey: AnyMandateKey, missing: string[]): string;
+
 /**
  * `@ai-matrx/agents/mandates` — the ONE place a TypeScript client learns a
  * mandate key.
@@ -693,5 +750,28 @@ declare function isMandateKey(value: unknown): value is MandateKey;
  * key set came from, and what to do — never a bare "invalid key".
  */
 declare function assertMandateKey(value: unknown, context?: string): asserts value is MandateKey;
+/**
+ * A DB-AUTHORED KEY THE GENERATED UNION CANNOT CARRY — the ONE typed door for
+ * a literal a client's mandate-key allowlist already governs.
+ *
+ * Two honest cases: an `origin='user'` mandate somebody created in the console
+ * (no generator built from code declarations can ever contain it), and a key
+ * aidream has declared but the installed `@ai-matrx/agents` predates. Because
+ * the parameter is a literal type, the key still appears verbatim at the call
+ * site for a hand-typed-key scanner and for a human reading the diff.
+ *
+ * 🚨 NOT an escape hatch for a declared key. A key in `MANDATE_KEYS` goes
+ * through `MANDATE_KEYS.<id>`; using this for one hides a real rename from the
+ * compiler. When the package publishes a key routed through here, delete the call.
+ */
+declare function dbAuthoredMandateKey<K extends string>(key: K): DynamicMandateKey;
+interface MandateKeyParts {
+    /** The feature/domain namespace before the first dot. */
+    feature: string;
+    /** The complete step name after the first dot; later dots are preserved. */
+    mandate: string;
+}
+/** Split canonical `<feature>.<mandate>` identity without losing information. */
+declare function splitMandateKey(mandateKey: string): MandateKeyParts;
 
-export { ALL_MANDATE_KEYS, type AnyMandateKey, DYNAMIC_MANDATE_FAMILIES, type DynamicMandateFamilyPrefix, type DynamicMandateKey, MANDATE_FAMILIES, MANDATE_KEYS, MANDATE_KEYS_META, type MandateFamilyMember, type MandateFamilyPrefix, type MandateKey, RETIRING_MANDATE_KEYS, assertMandateKey, isMandateKey, mandateKeyOfApp, mandateKeyOfShortcut, storedMandateKey };
+export { ALL_MANDATE_KEYS, type AnyMandateKey, DYNAMIC_MANDATE_FAMILIES, type DynamicMandateFamilyPrefix, type DynamicMandateKey, EMPTY_MANDATE_CONTRACT, MANDATE_FAMILIES, MANDATE_KEYS, MANDATE_KEYS_META, type MandateContract, type MandateFamilyMember, type MandateFamilyPrefix, type MandateKey, type MandateKeyParts, RETIRING_MANDATE_KEYS, assertMandateKey, dbAuthoredMandateKey, isMandateKey, mandateKeyOfApp, mandateKeyOfShortcut, missingRequiredVariables, missingVariablesMessage, parseMandateContract, splitMandateKey, storedMandateKey };

package/dist/mandates/index.js

@@ -1,8 +1,8 @@
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "a6b049dc158af5a226cdaee78dda64289fe8cf99",
+  aidreamRevision: "74afbd5d601164b5b5188572fd3d242dbed25996",
   generatorVersion: "1.0.0",
-  packageVersion: "0.32.0",
+  packageVersion: "0.33.0",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -677,6 +677,42 @@ function mandateKeyOfShortcut(shortcutSlug, surfaceSlug) {
   return dynamicKey("shortcut", shortcutSlug, surfaceSlug);
 }
 
+// mandates/contract.ts
+import { isJsonObject } from "@ai-matrx/kit/json-format";
+var EMPTY_MANDATE_CONTRACT = {
+  requiredVariables: [],
+  requiredContextPolicyKeys: [],
+  requiredOutputKeys: [],
+  spillVariables: [],
+  autoContextDisabled: false
+};
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+function parseMandateContract(contract) {
+  if (!isJsonObject(contract)) return { ...EMPTY_MANDATE_CONTRACT };
+  return {
+    requiredVariables: stringList(contract.required_variables),
+    requiredContextPolicyKeys: stringList(contract.required_context_policies),
+    requiredOutputKeys: stringList(contract.required_output_keys),
+    spillVariables: stringList(contract.spill_variables),
+    autoContextDisabled: contract.auto_context_disabled === true
+  };
+}
+function missingRequiredVariables(contract, supplied) {
+  const spilled = new Set(contract.spillVariables);
+  return contract.requiredVariables.filter((name) => {
+    if (spilled.has(name)) return false;
+    const value = supplied?.[name];
+    if (value === void 0 || value === null) return true;
+    if (typeof value === "string") return value.trim().length === 0;
+    return false;
+  });
+}
+function missingVariablesMessage(mandateKey, missing) {
+  return `The "${mandateKey}" step cannot start: it requires ${missing.map((n) => `\`${n}\``).join(", ")}, and ${missing.length === 1 ? "it was" : "they were"} not supplied. Refusing rather than starting the agent without ${missing.length === 1 ? "it" : "them"}.`;
+}
+
 // mandates/index.ts
 function storedMandateKey(value) {
   return value;
@@ -692,17 +728,36 @@ function assertMandateKey(value, context) {
     `${JSON.stringify(value)} is not a declared mandate key${where}. @ai-matrx/agents@${MANDATE_KEYS_META.packageVersion} ships ${ALL_MANDATE_KEYS.length} keys (aidream ${MANDATE_KEYS_META.aidreamRevision.slice(0, 12)}). If the key is real, this package is behind \u2014 take \`latest\` and re-check. If it is a user-built app or shortcut, it is DB-authored: build it with mandateKeyOfApp() / mandateKeyOfShortcut(), which return DynamicMandateKey.`
   );
 }
+function dbAuthoredMandateKey(key) {
+  return key;
+}
+function splitMandateKey(mandateKey) {
+  const separator = mandateKey.indexOf(".");
+  if (separator <= 0 || separator === mandateKey.length - 1) {
+    return { feature: "(unscoped)", mandate: mandateKey };
+  }
+  return {
+    feature: mandateKey.slice(0, separator),
+    mandate: mandateKey.slice(separator + 1)
+  };
+}
 export {
   ALL_MANDATE_KEYS,
   DYNAMIC_MANDATE_FAMILIES,
+  EMPTY_MANDATE_CONTRACT,
   MANDATE_FAMILIES,
   MANDATE_KEYS,
   MANDATE_KEYS_META,
   RETIRING_MANDATE_KEYS,
   assertMandateKey,
+  dbAuthoredMandateKey,
   isMandateKey,
   mandateKeyOfApp,
   mandateKeyOfShortcut,
+  missingRequiredVariables,
+  missingVariablesMessage,
+  parseMandateContract,
+  splitMandateKey,
   storedMandateKey
 };
 //# sourceMappingURL=index.js.map