@agenticprimitives/orchestration 0.0.0-alpha.1 → 0.0.0-alpha.3

package/dist/admission.d.ts

@@ -0,0 +1,87 @@
+import type { Intent, Plan, ToolSpec } from './types.js';
+/** Spec 367 §4 — the violation codes. Each names the field at fault and the recovery it allows. */
+export type AdmissionCode = 'REQUIRED_ROLE_UNRESOLVED' | 'RESOURCE_SCOPE_MISMATCH' | 'CAPABILITY_UNAVAILABLE' | 'UNSUPPORTED_BINDING_SOURCE' | 'DEPENDENCY_NOT_SATISFIED' | 'OUTCOME_NOT_ESTABLISHED' | 'BRANCH_UNDECIDABLE' | 'QUESTION_NOT_ANSWERED' | 'EXTERNAL_EXECUTOR_ACT';
+export interface AdmissionViolation {
+    code: AdmissionCode;
+    /** The sentence a planner is re-planned with, and a person is refused with. */
+    message: string;
+    stepIndex?: number;
+    toolId?: string;
+    /** The argument or plan field at fault, when there is one. */
+    field?: string;
+    /** What may fix it: re-plan the means, ask the person, resolve the binding, or refuse. */
+    recovery: 'replan' | 'ask' | 'resolve' | 'refuse';
+}
+export type AdmissionVerdict = {
+    admitted: true;
+} | {
+    admitted: false;
+    violations: AdmissionViolation[];
+};
+export interface AdmissionInput {
+    intent: Intent;
+    plan: Plan;
+    tools: ToolSpec[];
+}
+/** One rule. Pure over its input and whatever deps it closed over; returns the violations it found. */
+export type AdmissionRule = (input: AdmissionInput) => Promise<AdmissionViolation[]> | AdmissionViolation[];
+export interface PlanAdmission {
+    admit(input: AdmissionInput): Promise<AdmissionVerdict>;
+}
+/** Compose rules into the port. Every rule runs; the verdict carries every violation, so a re-plan is
+ *  told everything at once rather than one thing per round. */
+export declare function planAdmission(rules: readonly AdmissionRule[]): PlanAdmission;
+/** Letters only — "Missio Nexus", "missio-nexus" and the label of `missionexus.org` are one word to a person. */
+export declare const squash: (s: string) => string;
+/**
+ * AN INSTRUCTION IS ANSWERED BY AN ACT. A tool that declares a capability declares the verbs that name it
+ * (`ToolSpec.verbs`). A sentence that OPENS with one of those verbs is an instruction, and a plan for it
+ * that contains no capability-bearing step is a read pretending to act — the plan that told a person
+ * "nothing was sent" about a payment they asked for. Which act is not judged here (a message and a
+ * payment both open with "send"); that a step ACTS is.
+ */
+/** What a tool ESTABLISHES (spec 367 §6), with the declared default: a read establishes who was meant; an act
+ *  establishes its outcome unless its contract says it only submits. */
+export declare function outcomeClassOf(t: ToolSpec): 'lookup' | 'submission' | 'authoritative';
+export declare const instructionNeedsAct: AdmissionRule;
+/** A step that consumes `{ $ref: name }` must follow a step that provides `ref: name` (spec 367 §4:
+ *  typed unresolved dependencies — a later step may depend on an earlier one, never on nothing). */
+export declare const dependenciesProvided: AdmissionRule;
+/**
+ * Spec 370 P3 — a branch must be DECIDABLE and an edge must point BACKWARD. `when.ref` names a result an
+ * earlier step binds (`ref`); `after` names ids of earlier steps. A branch on a result nobody produces would
+ * be decided by absence — which is a guess dressed as a condition — and an edge to a later step is a cycle.
+ */
+export declare const branchesDecidable: AdmissionRule;
+/**
+ * Spec 371 — THE QUESTION MUST BE ANSWERED BY THE READ THAT ANSWERS IT. A read declares the fact words a
+ * question uses to name what it establishes (`answers`: "balance", "how much"). When the sentence names
+ * such a fact and an exposed tool answers it, a plan without that tool is answering something else — a
+ * survey of receipts for a balance question. The rule reads declarations only, and it says which tool.
+ */
+export declare const questionAnsweredByRead: AdmissionRule;
+/** A step naming a tool this agent does not expose. The loop refuses it anyway (`unknown_tool`); as a rule it
+ *  lets an eval and a re-plan see WHICH capability was missing. */
+export declare const capabilitiesAvailable: AdmissionRule;
+/** A PLACEHOLDER IS NOT AN ARGUMENT. "<UNKNOWN>", "TBD", "n/a" inside a step is a value the person would be
+ *  asked to sign over. Omit the argument and it is asked for; a placeholder is refused. */
+export declare const noPlaceholders: AdmissionRule;
+/**
+ * THE SUBJECT THE SENTENCE NAMES MUST BE IN THE STEP. A tool that declares a `subject` argument (spec 366)
+ * is answered by the agent that argument names. When the sentence contains the name of an agent the asker
+ * KNOWS — from their own links, supplied by the harness, never guessed from the directory — and the step
+ * leaves the subject empty, the step would run against the addressee's own records and answer for the
+ * wrong agent. That is the Missio Nexus incident, as a rule.
+ */
+export declare function subjectNamedInAsk(knownNames: (intent: Intent) => Promise<Array<{
+    name: string;
+    agent: string;
+}>>): AdmissionRule;
+/**
+ * Spec 379 (appendix M4) — AN OUTSIDE AGENT MAY ANSWER, NEVER ACT. A step whose `executor` is outside this
+ * deployment (the caller says which — an https card URL, an address not served here) may run only a
+ * tool that exercises no capability: its answer is an observation. A value-moving or record-changing
+ * step aimed at an outside agent is refused at admission, before any planner or verifier spends anything.
+ */
+export declare function externalExecutorsReadOnly(isExternal: (executor: string) => boolean): AdmissionRule;
+//# sourceMappingURL=admission.d.ts.map

package/dist/admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.d.ts","sourceRoot":"","sources":["../src/admission.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEzD,mGAAmG;AACnG,MAAM,MAAM,aAAa,GACrB,0BAA0B,GAC1B,yBAAyB,GACzB,wBAAwB,GACxB,4BAA4B,GAC5B,0BAA0B,GAC1B,yBAAyB,GACzB,oBAAoB,GACpB,uBAAuB,GACvB,uBAAuB,CAAC;AAE5B,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,aAAa,CAAC;IACpB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,QAAQ,EAAE,QAAQ,GAAG,KAAK,GAAG,SAAS,GAAG,QAAQ,CAAC;CACnD;AAED,MAAM,MAAM,gBAAgB,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,UAAU,EAAE,kBAAkB,EAAE,CAAA;CAAE,CAAC;AAE1G,MAAM,WAAW,cAAc;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,QAAQ,EAAE,CAAA;CAAE;AAEjF,uGAAuG;AACvG,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,kBAAkB,EAAE,CAAC,GAAG,kBAAkB,EAAE,CAAC;AAE5G,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACzD;AAED;+DAC+D;AAC/D,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,aAAa,CAO5E;AAGD,iHAAiH;AACjH,eAAO,MAAM,MAAM,MAAO,MAAM,KAAG,MAA0C,CAAC;AAQ9E;;;;;;GAMG;AACH;wEACwE;AACxE,wBAAgB,cAAc,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,eAAe,CAErF;AAED,eAAO,MAAM,mBAAmB,EAAE,aAoBjC,CAAC;AAEF;oGACoG;AACpG,eAAO,MAAM,oBAAoB,EAAE,aAqBlC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAgB/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAWpC,CAAC;AAEF;mEACmE;AACnE,eAAO,MAAM,qBAAqB,EAAE,aAGnC,CAAC;AAEF;2FAC2F;AAC3F,eAAO,MAAM,cAAc,EAAE,aAG8Q,CAAC;AAE5S;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,GAAG,aAAa,CAmBhI;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,GAAG,aAAa,CAWlG"}

package/dist/admission.js

@@ -0,0 +1,193 @@
+/** Compose rules into the port. Every rule runs; the verdict carries every violation, so a re-plan is
+ *  told everything at once rather than one thing per round. */
+export function planAdmission(rules) {
+    return {
+        async admit(input) {
+            const violations = (await Promise.all(rules.map((r) => r(input)))).flat();
+            return violations.length ? { admitted: false, violations } : { admitted: true };
+        },
+    };
+}
+const lc = (s) => s.trim().toLowerCase();
+/** Letters only — "Missio Nexus", "missio-nexus" and the label of `missionexus.org` are one word to a person. */
+export const squash = (s) => lc(s).replace(/[^a-z0-9]+/g, '');
+/** The imperative opening of a sentence, with the polite wrappers stripped: "please send…", "can you pay…",
+ *  "i want to create…" all open with the verb. A question ("who did I send money to") does not. */
+function imperativeOf(goal) {
+    return lc(goal).replace(/^(please\s+|can you\s+|could you\s+|would you\s+|i want to\s+|i'd like to\s+|i would like to\s+|go ahead and\s+)+/, '');
+}
+/**
+ * AN INSTRUCTION IS ANSWERED BY AN ACT. A tool that declares a capability declares the verbs that name it
+ * (`ToolSpec.verbs`). A sentence that OPENS with one of those verbs is an instruction, and a plan for it
+ * that contains no capability-bearing step is a read pretending to act — the plan that told a person
+ * "nothing was sent" about a payment they asked for. Which act is not judged here (a message and a
+ * payment both open with "send"); that a step ACTS is.
+ */
+/** What a tool ESTABLISHES (spec 367 §6), with the declared default: a read establishes who was meant; an act
+ *  establishes its outcome unless its contract says it only submits. */
+export function outcomeClassOf(t) {
+    return t.establishes ?? (t.capability ? 'authoritative' : 'lookup');
+}
+export const instructionNeedsAct = ({ intent, plan, tools }) => {
+    const opening = imperativeOf(intent.goal);
+    const acts = tools.filter((t) => t.capability && t.verbs?.length);
+    const claims = (t) => !!t.verbs?.some((v) => opening === lc(v) || opening.startsWith(`${lc(v)} `));
+    const named = acts.filter(claims);
+    if (!named.length)
+        return [];
+    const byId = new Map(tools.map((t) => [t.id, t]));
+    // A READ MAY CLAIM THE VERB TOO (spec 379): "ask the clock what time it is" opens with "ask", which an
+    // invitation act also claims. When a lookup in the plan declares that verb, the read IS what was
+    // instructed — consulting an outside agent — and the plan discharges the sentence by doing it.
+    if (plan.steps.some((s) => { const t = byId.get(s.toolId); return !!t && !t.capability && claims(t); }))
+        return [];
+    // The outcome rule (§6), not a "last tool" rule: a lookup may precede the act (who is "my daughter"), and
+    // a notification may follow it. What may not happen is a plan whose every step only ESTABLISHES WHO WAS
+    // MEANT — a lookup cannot discharge an instruction, however well it went.
+    const canDischarge = plan.steps.some((s) => { const t = byId.get(s.toolId); return !!t && outcomeClassOf(t) !== 'lookup'; });
+    if (canDischarge)
+        return [];
+    return [{
+            code: 'OUTCOME_NOT_ESTABLISHED', recovery: 'replan',
+            message: `"${intent.goal}" is an instruction (it opens with ${named.map((t) => `"${t.verbs[0]}"`).join(' / ')}) and every step in the plan only looks something up (${plan.steps.map((s) => s.toolId).join(', ') || 'nothing'}) — a lookup cannot establish that it was done. Plan the capability that performs it — ${named.map((t) => t.id).join(' or ')} — and pass the person's words as its arguments; it resolves who is meant itself.`,
+        }];
+};
+/** A step that consumes `{ $ref: name }` must follow a step that provides `ref: name` (spec 367 §4:
+ *  typed unresolved dependencies — a later step may depend on an earlier one, never on nothing). */
+export const dependenciesProvided = ({ plan }) => {
+    const out = [];
+    const provided = new Set();
+    plan.steps.forEach((s, i) => {
+        const refs = new Set();
+        const walk = (v) => {
+            if (!v || typeof v !== 'object')
+                return;
+            if (Array.isArray(v)) {
+                v.forEach(walk);
+                return;
+            }
+            const o = v;
+            if (typeof o.$ref === 'string')
+                refs.add(o.$ref.split('.')[0]);
+            if (typeof o.$forEach === 'string')
+                refs.add(o.$forEach.split('.')[0]);
+            Object.values(o).forEach(walk);
+        };
+        walk(s.args);
+        // The fan-out form (spec 358 W4): `forEach: { ref: 'roster.members' }` names the enumerating step by ref.
+        const fe = s.forEach;
+        if (fe && typeof fe.ref === 'string')
+            refs.add(fe.ref.split('.')[0]);
+        for (const r of refs)
+            if (!provided.has(r))
+                out.push({ code: 'DEPENDENCY_NOT_SATISFIED', recovery: 'replan', stepIndex: i, toolId: s.toolId, field: r, message: `step ${i + 1} (${s.toolId}) uses "${r}" before any step provides it — order the step that produces "${r}" first, or drop the reference.` });
+        if (s.ref)
+            provided.add(s.ref);
+    });
+    return out;
+};
+/**
+ * Spec 370 P3 — a branch must be DECIDABLE and an edge must point BACKWARD. `when.ref` names a result an
+ * earlier step binds (`ref`); `after` names ids of earlier steps. A branch on a result nobody produces would
+ * be decided by absence — which is a guess dressed as a condition — and an edge to a later step is a cycle.
+ */
+export const branchesDecidable = ({ plan }) => {
+    const out = [];
+    const provided = new Set();
+    const ids = new Set();
+    plan.steps.forEach((s, i) => {
+        const w = s.when;
+        if (w && (typeof w.ref !== 'string' || !provided.has(w.ref.split('.')[0]))) {
+            out.push({ code: 'BRANCH_UNDECIDABLE', recovery: 'replan', stepIndex: i, toolId: s.toolId, field: 'when', message: `step ${i + 1} (${s.toolId}) branches on "${String(w.ref ?? '')}", which no earlier step produces — bind the producing step with $ref first, or drop the condition.` });
+        }
+        for (const id of s.after ?? []) {
+            if (typeof id !== 'string' || !ids.has(id))
+                out.push({ code: 'BRANCH_UNDECIDABLE', recovery: 'replan', stepIndex: i, toolId: s.toolId, field: 'after', message: `step ${i + 1} (${s.toolId}) waits for "${String(id)}", which is not an earlier step's id.` });
+        }
+        if (s.ref)
+            provided.add(s.ref);
+        ids.add(s.id ?? `s${i}`);
+    });
+    return out;
+};
+/**
+ * Spec 371 — THE QUESTION MUST BE ANSWERED BY THE READ THAT ANSWERS IT. A read declares the fact words a
+ * question uses to name what it establishes (`answers`: "balance", "how much"). When the sentence names
+ * such a fact and an exposed tool answers it, a plan without that tool is answering something else — a
+ * survey of receipts for a balance question. The rule reads declarations only, and it says which tool.
+ */
+export const questionAnsweredByRead = ({ intent, plan, tools }) => {
+    const goal = ` ${lc(intent.goal).replace(/[^a-z0-9]+/g, ' ')} `;
+    const out = [];
+    const inPlan = new Set(plan.steps.map((s) => s.toolId));
+    for (const t of tools) {
+        if (!t.answers?.length || inPlan.has(t.id))
+            continue;
+        const named = t.answers.find((w) => goal.includes(` ${lc(w).replace(/[^a-z0-9]+/g, ' ')} `));
+        if (!named)
+            continue;
+        out.push({ code: 'QUESTION_NOT_ANSWERED', recovery: 'replan', toolId: t.id, field: named, message: `the sentence asks about "${named}", which ${t.id} answers, and the plan does not use it — use ${t.id} for that, not a survey of other records.` });
+    }
+    return out;
+};
+/** A step naming a tool this agent does not expose. The loop refuses it anyway (`unknown_tool`); as a rule it
+ *  lets an eval and a re-plan see WHICH capability was missing. */
+export const capabilitiesAvailable = ({ plan, tools }) => {
+    const ids = new Set(tools.map((t) => t.id));
+    return plan.steps.flatMap((s, i) => ids.has(s.toolId) ? [] : [{ code: 'CAPABILITY_UNAVAILABLE', recovery: 'refuse', stepIndex: i, toolId: s.toolId, message: `step ${i + 1} names "${s.toolId}", which this agent does not offer — choose among: ${[...ids].join(', ')}.` }]);
+};
+/** A PLACEHOLDER IS NOT AN ARGUMENT. "<UNKNOWN>", "TBD", "n/a" inside a step is a value the person would be
+ *  asked to sign over. Omit the argument and it is asked for; a placeholder is refused. */
+export const noPlaceholders = ({ plan }) => plan.steps.flatMap((s, i) => Object.entries(s.args)
+    .filter(([, v]) => typeof v === 'string' && /^<.*>$|^(unknown|tbd|n\/a|null|undefined|placeholder)$/i.test(v.trim()))
+    .map(([k, v]) => ({ code: 'UNSUPPORTED_BINDING_SOURCE', recovery: 'ask', stepIndex: i, toolId: s.toolId, field: k, message: `step ${i + 1} (${s.toolId}) carries a placeholder for "${k}" (${String(v)}); omit an argument the sentence did not give, and it will be asked for.` })));
+/**
+ * THE SUBJECT THE SENTENCE NAMES MUST BE IN THE STEP. A tool that declares a `subject` argument (spec 366)
+ * is answered by the agent that argument names. When the sentence contains the name of an agent the asker
+ * KNOWS — from their own links, supplied by the harness, never guessed from the directory — and the step
+ * leaves the subject empty, the step would run against the addressee's own records and answer for the
+ * wrong agent. That is the Missio Nexus incident, as a rule.
+ */
+export function subjectNamedInAsk(knownNames) {
+    return async ({ intent, plan, tools }) => {
+        const byId = new Map(tools.map((t) => [t.id, t]));
+        const candidates = plan.steps.map((s, i) => ({ s, i, tool: byId.get(s.toolId) }))
+            .filter(({ s, tool }) => tool?.subject && !String(s.args[tool.subject] ?? '').trim());
+        if (!candidates.length)
+            return [];
+        const goal = squash(intent.goal);
+        const names = (await knownNames(intent).catch(() => [])).filter((n) => n.name && !/^0x[0-9a-f]{40}$/i.test(n.name));
+        const named = names.filter((n) => {
+            const full = squash(n.name);
+            const label = squash(n.name.split('.')[0] ?? '');
+            return (full.length >= 4 && goal.includes(full)) || (label.length >= 4 && goal.includes(label));
+        });
+        if (!named.length)
+            return [];
+        return candidates.map(({ s, i, tool }) => ({
+            code: 'REQUIRED_ROLE_UNRESOLVED', recovery: 'resolve', stepIndex: i, toolId: s.toolId, field: tool.subject,
+            message: `the ask names ${named.map((n) => `"${n.name}"`).join(' / ')} and step ${i + 1} (${s.toolId}) names no ${tool.subject}; pass the name the person used as "${tool.subject}".`,
+        }));
+    };
+}
+/**
+ * Spec 379 (appendix M4) — AN OUTSIDE AGENT MAY ANSWER, NEVER ACT. A step whose `executor` is outside this
+ * deployment (the caller says which — an https card URL, an address not served here) may run only a
+ * tool that exercises no capability: its answer is an observation. A value-moving or record-changing
+ * step aimed at an outside agent is refused at admission, before any planner or verifier spends anything.
+ */
+export function externalExecutorsReadOnly(isExternal) {
+    return ({ plan, tools }) => {
+        const out = [];
+        plan.steps.forEach((st, i) => {
+            const ex = st.executor;
+            if (typeof ex !== 'string' || !ex || !isExternal(ex))
+                return;
+            const tool = tools.find((t) => t.id === st.toolId);
+            if (tool?.capability)
+                out.push({ code: 'EXTERNAL_EXECUTOR_ACT', recovery: 'refuse', stepIndex: i, toolId: st.toolId, field: 'executor', message: `step ${i + 1} (${st.toolId}) exercises ${tool.capability.id} and names ${ex} to run it — an outside agent may answer a question, never perform an act; run the step here or drop it.` });
+        });
+        return out;
+    };
+}
+//# sourceMappingURL=admission.js.map

package/dist/admission.js.map

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

package/dist/artifacts.d.ts

@@ -0,0 +1,137 @@
+import type { StepObservation, PlanStep } from './types.js';
+import type { RunResult } from './types.js';
+export declare const ARTIFACT_REF_TYPE: "ap.artifact-ref.v1";
+/** A result whose canonical JSON is longer than this is offloaded when a store is bound. A deployment setting. */
+export declare const OFFLOAD_THRESHOLD_CHARS = 8000;
+/** The most a summary may run to — a shape, never a body. */
+export declare const SUMMARY_MAX_CHARS = 600;
+/** The stand-in for an offloaded result: where the body is, what it is, and its shape. */
+export interface ArtifactRefV1 {
+    $artifact: typeof ARTIFACT_REF_TYPE;
+    /** The agent whose vault holds it (the acting agent — the run's addressee). */
+    agent: string;
+    /** The vault record key: `run.artifact:<runRef>:<stepRef>`. */
+    recordType: string;
+    /** sha256 of the canonical JSON of the body — the same bytes the receipt's outputDigest commits to. */
+    digest: string;
+    bytes: number;
+    toolId: string;
+    summary: string;
+    /** The few top-level FACTS the run's record and spans read off a result (a chain tx hash, a routed step's
+     *  `via`, a count) — kept on the reference so offloading a body loses no evidence. Names from a fixed list. */
+    retained?: Record<string, unknown>;
+}
+/** Top-level result keys retained on a reference: what the record, the spans and the graph cite. */
+export declare const RETAINED_RESULT_KEYS: readonly ["txHash", "via", "count", "total", "ok", "outcome"];
+/** The facts of a result whether it is whole or a reference — what a projection reads. */
+export declare function resultFactsOf(result: unknown): Record<string, unknown> | undefined;
+export declare const RUN_ARTIFACT_RECORD_PREFIX: "run.artifact:";
+export declare const runArtifactRecordKey: (runRef: string, stepRef: string) => string;
+/** The vault record an offloaded result becomes. */
+export interface RunArtifactRecordV1 {
+    type: 'ap.run-artifact.v1';
+    runRef: string;
+    stepRef: string;
+    toolId: string;
+    digest: string;
+    bytes: number;
+    at: number;
+    result: unknown;
+}
+export declare function isArtifactRef(v: unknown): v is ArtifactRefV1;
+/** Canonical JSON: keys sorted, bigints as strings — the same bytes the receipt digests. */
+export declare const canonicalJson: (v: unknown) => string;
+/**
+ * A DETERMINISTIC summary of a result: its kind and top-level shape, the length of every array, the
+ * first three items' title-like field, a count when the result declares one. Bounded, never a body,
+ * never a model's words. Two runs over the same result produce the same string.
+ */
+export declare function summarizeResult(result: unknown): string;
+/** The port the app binds to the acting agent's vault door. Failures throw — an artifact that could not be
+ *  written is a step whose result stays in the record whole, and the caller says so (never a silent drop). */
+export interface ArtifactStore {
+    put(record: RunArtifactRecordV1, agent: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    get(ref: ArtifactRefV1): Promise<RunArtifactRecordV1 | null>;
+}
+export interface OffloadReport {
+    stepRef: string;
+    toolId: string;
+    bytes: number;
+    recordType: string;
+    ok: boolean;
+    error?: string;
+}
+/**
+ * The record / checkpoint form of a run's observations: every result whose canonical JSON exceeds the
+ * threshold is written to the store and replaced by its reference. The receipts are untouched (their
+ * digests already commit to the full output). A write that fails leaves the result whole and is reported.
+ */
+export declare function offloadObservations(steps: ReadonlyArray<StepObservation>, opts: {
+    runRef: string;
+    agent: string;
+    store: ArtifactStore;
+    threshold?: number;
+    now?: number;
+}): Promise<{
+    steps: StepObservation[];
+    offloaded: OffloadReport[];
+}>;
+/** The record form of a whole RunResult (steps offloaded; everything else as it was). */
+export declare function offloadRunResult<T extends Pick<RunResult, 'steps'>>(result: T, opts: Parameters<typeof offloadObservations>[1]): Promise<{
+    result: T;
+    offloaded: OffloadReport[];
+}>;
+/** The step references a plan's remaining steps reach through `$ref` (`{ $ref: 'name.path' }` — the name is
+ *  the producing step's `ref` or `id`). */
+export declare function refsReachedBy(steps: ReadonlyArray<PlanStep>): Set<string>;
+/**
+ * The inverse, on a resume: a completed step whose result is a reference gets its body back from the store
+ * ONLY when a remaining step's `$ref` reaches it (by the step's `ref`, `id` or stepRef). A body nobody will
+ * read stays a reference. A missing artifact is an error the caller surfaces — a resume that guessed a
+ * result would be a resume that lied.
+ */
+export declare function rehydrateObservations<T extends {
+    stepRef: string;
+    result?: unknown;
+}>(completed: ReadonlyArray<T>, plan: {
+    steps: ReadonlyArray<PlanStep>;
+}, store: ArtifactStore): Promise<{
+    completed: T[];
+    rehydrated: string[];
+}>;
+/**
+ * Spec 391 W2 — what a RE-PLAN sees of prior observations: a body over the threshold becomes its summary (a
+ * reference keeps its own). A planner deciding what comes next needs what a step was and how big, not 40 KB
+ * of it in the prompt.
+ */
+export declare function compactObservations(observations: ReadonlyArray<StepObservation>, threshold?: number): StepObservation[];
+export interface EvidenceItemV1 {
+    tool: string;
+    result: unknown; /** A summary stood in for the body. */
+    summarized?: boolean;
+}
+export interface FittedEvidenceV1 {
+    items: EvidenceItemV1[];
+    /** Characters of the fitted evidence, and of the whole. */
+    chars: number;
+    of: number;
+    /** Every step whose body was replaced by its summary, in order — for the trace and the governor. */
+    dropped: Array<{
+        tool: string;
+        stepRef?: string;
+        bytes: number;
+    }>;
+}
+/**
+ * The composer's evidence, FITTED to a budget instead of sliced: successful observations in order; a
+ * reference contributes its summary; a body that fits is kept whole; a body that would push the whole
+ * past the cap is replaced by its summary and recorded as dropped. The first item is always kept whole
+ * when it fits alone — an answer with no evidence is not an answer.
+ */
+export declare function fitEvidence(observations: ReadonlyArray<StepObservation>, cap: number): FittedEvidenceV1;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

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