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

package/dist/index.js

@@ -1,7 +1,48 @@
 // @agenticprimitives/orchestration — public API. The Ring-0 agentic loop: the intent→plan→execute→observe
 // model, the Planner + ToolInvoker PORTS, and `runIntent`. Pure leaf — no transport, no LLM SDK, no chain.
-// The LLM binding lives in `@agenticprimitives/orchestration-anthropic` (behind the Planner port). ADR-0044.
+// The LLM bindings live in sibling adapters behind the Planner port (`orchestration-anthropic`,
+// `orchestration-openai-compat`). ADR-0044, spec 377.
 export { PACKAGE_NAME, PACKAGE_STATUS, SPEC_REF, OrchestrationError } from './types.js';
-export { createRuleBasedPlanner } from './planner.js';
-export { runIntent } from './loop.js';
+export { createRuleBasedPlanner, renderContinuation } from './planner.js';
+export { deriveArgs, untrustedArgs } from './derivation.js';
+// Spec 377 §2 — the plan-shape convention on a vendor's wire, shared by every LLM adapter.
+export { wireNameFor, toolNameMap, planStepFromToolArgs } from './planner-wire.js';
+export { isToolInvocationResult, observed, describeObservation } from './tool-invoker.js';
+export { runIntent, RETRIEVAL_STEP_REF, CONTINUE_STEP_ID, CONTINUE_TOOL } from './loop.js';
+export { planAdmission, externalExecutorsReadOnly, instructionNeedsAct, noPlaceholders, subjectNamedInAsk, dependenciesProvided, branchesDecidable, questionAnsweredByRead, numbersFromTheWords, numbersSaid, partiesDistinct, actingPartyFromTheWords, kindNamedIsChartered, capabilitiesAvailable, outcomeClassOf, squash as squashLabel } from './admission.js';
+// Spec 350 §3.4 — a tool may ask the person for what it lacks; the run suspends with the prompt.
+export { InputRequired, isInputRequired, inputsFor, dataFor, signatureFor, receiptPending } from './input.js';
+export { TerminalDenial } from './durable.js';
+// Spec 370 P6 — the run record and its replay (verdicts re-derived, tools never re-run).
+export { recordOf, runMarks, replayingInvoker, replayRun, completedFromRecord } from './record.js';
+// Spec 408 §2.3 — the digest of the plan as written, bound by a mandate and presented on every step.
+export { planDigest, planStepAsWritten } from './plan-digest.js';
+// Spec 381 — the run, exported: firewalled spans + the durable half for the vault. Pure projections of a record.
+export { spansOf, assertFirewalled, otlpTracesOf, receiptDigest, provenanceOf, runProvenanceRecordKey, SPAN_ATTRIBUTE_ALLOWLIST, RUN_PROVENANCE_RECORD_PREFIX, provIds, traceIdOf, spanIdOf, PROV_ID_BASE, stageSpansOf, assertMetricsFirewalled } from './spans.js';
+// Spec 390 W4 — the run as metrics: four instruments from one record, the OTLP metrics body beside the traces body.
+export { metricsOf, otlpMetricsOf, STEP_DURATION_BOUNDS_MS } from './metrics.js';
+// Spec 414 A1 — the trace from the door: door, model calls, variant, starting state, harness-capability engagements.
+export { engagementsOf, variantDigestOf, plannerCapabilityOf, addUsage } from './trace-facts.js';
+export { traceIdFor } from './spans.js';
+// Spec 390 W2 — W3C Trace Context on the wire: parse, format, tracestate members. Correlation, never trust.
+export { parseTraceparent, formatTraceparent, withTracestateMember, tracestateMember, traceContextOf } from './trace-context.js';
+// Spec 391 — offloaded artifacts and fitted evidence: what outlives a turn is a reference; nothing is cut silently.
+export { ARTIFACT_REF_TYPE, OFFLOAD_THRESHOLD_CHARS, SUMMARY_MAX_CHARS, RUN_ARTIFACT_RECORD_PREFIX, runArtifactRecordKey, isArtifactRef, canonicalJson, summarizeResult, offloadObservations, offloadRunResult, refsReachedBy, rehydrateObservations, fitEvidence, compactObservations, resultFactsOf, RETAINED_RESULT_KEYS } from './artifacts.js';
+// Spec 387 W2 / spec 399 §4 — the flow trace: a run's story on its task, folded from RunEvents + the planner summary. Evidence, never authority.
+export { buildFlowTrace, flowIdOf, referralOf, summarizeOutput } from './flow-trace.js';
+// Spec 410 §3 — reconcile before every retry, per effect kind.
+export { reconcileByTool } from './reconcile.js';
+// Spec 410 §6 — conformance for open intents: what the stated outcome entails, before anything is offered.
+export { outcomeConformance, conformEffects, statedOutcomeOf, classifyOpenIntent } from './conformance.js';
+// Spec 415 A4 — skill selection by declared vocabulary (`skill-selection/rules`): chooses with a margin or holds.
+export { selectByDeclaredUtterances, tokensOf, overlap, DEFAULT_DECLARED_SELECTION, groundInLexicon, decideFromGrounding, selectByOntology, selectByJudgment, DEFAULT_JUDGMENT_SELECTION, SELECTION_JUDGE, NEEDS_CLARIFICATION, NEEDS_SEVERAL, SELECTION_JUDGE_FAST, SELECTION_JUDGE_FAST_V3, SELECTION_JUDGE_LOGPROB, selectByOntologyFirst, foldSelectionAbstentions, calibrateByTemperature, conformalSetOf, OUTSIDE_DOMAIN, selectByOntologyThenJudgment, proposeFromGrounding, selectByProposalThenJudgment, DEFAULT_PROPOSAL, selectByFramedJudgment, DEFAULT_FRAMED_SELECTION, FRAMED_JUDGE } from './selection.js';
+// Spec 414 §3.4 J1–J13 — the judgment capability: typed questions, a distribution per question, a declared decision rule.
+export { judgeQuestions, judgeQuestionsAveraged, logprobChoiceDecisionModel, applyDecisionRule, explainAnswer, answerOf, outcomesOf, shapeOf, structuredCallDecisionModel, NOT_APPLICABLE } from './judgment.js';
+// Spec 416 §4f — the inferred intent: the request read into the ontology's terms + what is known of the asker.
+export { inferIntent, renderReading, skillCard } from './intent.js';
+export { outcomeGraphOf, consumedClassesOf, edgesOf, edgeKey, edgeByParty, upstreamInputsOf, downstreamOf, absenceStatement, planOptionsAround, choosePlanAround, PLAN_CHOICE_JUDGE, planForPicked, OUTCOME_JUDGE_SELECTIVE, glossOf, planForOutcome, selectByOutcome, outcomeSteps, OUTCOME_JUDGE, DEFAULT_OUTCOME_PARAMS, DEFAULT_OUTCOME_BOUNDS } from './outcome.js';
+// Spec 416 §4h — answer quality, judged by typed yes-no questions over (request, skill card, answer); numbers only.
+export { judgeAnswerQuality, judgeOutcomeDelivered, OUTCOME_CHECK_JUDGE, ANSWER_QUALITY_JUDGE, ANSWER_QUALITY_RUBRIC, judgeAnswerPreference, ANSWER_PREFERENCE_JUDGE } from './answer-quality.js';
+// Spec 420 §2 — goal regression over situations (pure; transitions and facts supplied).
+export { checkPlan, completePlan, transitionsHold } from './regression.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,2GAA2G;AAC3G,6GAA6G;AAE7G,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAYxF,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAKtD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/input.d.ts

@@ -0,0 +1,165 @@
+import type { StepReceipt } from './authority.js';
+export type InputFieldType = 'text' | 'address' | 'number' | 'boolean' | 'choice' | 'credential';
+export interface InputFieldV1 {
+    name: string;
+    label: string;
+    type: InputFieldType;
+    required?: boolean;
+    /** For `choice`. `hint` is what a person needs to tell two candidates APART — a label alone
+     *  ("Nathan") is not a choice, it is the same word four times. */
+    choices?: Array<{
+        value: string;
+        label: string;
+        hint?: string;
+    }>;
+    /** For `choice`: the listed candidates are not the only possible answers, so the surface MUST also let
+     *  the person type one. Set whenever the question itself admits that what they want may not be listed —
+     *  a prompt saying "give it in full" beside a radio list with no text box is a dead end with
+     *  instructions. */
+    allowOther?: boolean;
+    /** For `text`: a regular-expression source the surface may validate against before submitting. */
+    pattern?: string;
+    hint?: string;
+}
+/** A follow-up the surface may offer when a question has no good answer among what is on hand — "ask
+ *  them for a way to reach it". The surface PREFILLS it; it never sends it. A question that leads
+ *  nowhere is a dead end, and the way out is usually another ask the person did not know to phrase. */
+export interface InputSuggestionV1 {
+    label: string;
+    /** The ask to prefill, in the person's own voice. */
+    message: string;
+}
+/**
+ * Spec 374 — WHAT ANOTHER AGENT OWES THIS RUN. A step whose subject is another agent was sent there (spec
+ * 366); that agent could not finish it for this asker and parked it for its own steward. This run holds
+ * the record — a `Commitment` in spec 340's sense: debtor, creditor, content, conditions, its own
+ * lifecycle — and waits. Evidence of where the act stands; never authority for it: no gate reads it.
+ */
+export interface CommitmentRefV1 {
+    /** The debtor's operation identity for this request — the correlation the answer will name. */
+    id: string;
+    /** Who owes the act (the subject's agent). */
+    debtor: string;
+    /** Who is owed it (the asker's agent). */
+    creditor: string;
+    content: {
+        capability: string;
+        args: Record<string, unknown>;
+        goal: string;
+    };
+    /** In words: "a steward of missio-nexus.org finishes it". */
+    conditions: string;
+    /** Spec 340 `CommitmentState`, the four this record can observe. `proposed` = asked and parked. */
+    state: 'proposed' | 'active' | 'discharged' | 'void';
+    /** The debtor's run, where the act actually waits. */
+    at: {
+        agent: string;
+        name?: string;
+        runRef: string;
+    };
+}
+export type InputRequestV1 = {
+    kind: 'data';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    fields: InputFieldV1[];
+    suggest?: InputSuggestionV1;
+    /** Spec 385 — when this is an AMBIGUITY choice, the scope the answer confirms (word + capability + arg),
+     *  so the trusted resume that supplies it can be remembered as a scoped preference. Display/memory only. */
+    scope?: {
+        word: string;
+        capability: string;
+        arg: string;
+    };
+    /** Spec 397 — the question is ANOTHER agent's (a routed step's target asked it): where it waits, and the step
+     *  there the answer is for. The resume continues THAT run with the answer; this run only relays. */
+    at?: {
+        agent: string;
+        name?: string;
+        runRef: string;
+        stepRef?: string;
+    };
+}
+/** Spec 374 — the run waits on another agent's steward; only the debtor's answer resumes it. */
+ | {
+    kind: 'commitment';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    commitment: CommitmentRefV1;
+}
+/** Spec 374 W2 — THE SUBJECT'S AUTHORITY REQUEST, RELAYED: the step was routed to another agent, which
+ *  asked for a mandate the ASKER can grant (they steward it). The asker's surface mints it exactly as it
+ *  would for a local step; on resume the mandate travels to the subject's parked run. `authority` is
+ *  the receiver's own request, carried whole; `at` is where the step waits. */
+ | {
+    kind: 'authority';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    authority: Record<string, unknown>;
+    at: {
+        agent: string;
+        name?: string;
+        runRef: string;
+    };
+} | {
+    kind: 'signature';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    /** The digest to sign, and who must sign it (the connected credential's address, or the SA it custodies). */
+    digest: string;
+    signer: string;
+    /** What is being signed, in the open — the surface shows it; the tool re-derives it on resume. */
+    payload?: unknown;
+} | {
+    kind: 'confirmation';
+    stepRef: string;
+    toolId: string;
+    prompt: string;
+    summary: unknown;
+};
+/** What comes back. Keyed by the step that asked; a tool reads its own via `inputsFor`. */
+export interface SuppliedInputV1 {
+    stepRef: string;
+    /** Answers to a `data` request, by field name. A `credential` field's value is the surface's own
+     *  description of the connected credential, in whatever shape the tool documented. */
+    data?: Record<string, unknown>;
+    /** The answer to a `signature` request. `payload` echoes what was signed when the tool needs it back. */
+    signature?: {
+        digest: string;
+        signer: string;
+        signature: string;
+        payload?: unknown;
+    };
+    /** The answer to a `confirmation` request. */
+    confirmed?: boolean;
+    /** Spec 374 — the answer to a `commitment` request: what the debtor's agent delivered when its parked
+     *  run finished. `outcome` is the debtor's word; `result` is the step's result when it answered. */
+    delivered?: {
+        outcome: 'answer' | 'refused' | 'error';
+        result?: unknown;
+        said?: string;
+        receipts?: unknown[];
+        runRef?: string;
+    };
+}
+/** Thrown by a tool invoker to suspend the run with a prompt. The loop recognises this class and ONLY this
+ *  class — any other throw is a step failure. */
+export declare class InputRequired extends Error {
+    readonly request: InputRequestV1;
+    constructor(request: InputRequestV1);
+}
+export declare function isInputRequired(e: unknown): e is InputRequired;
+/** The inputs supplied for one step (a resume may answer several steps at once). */
+export declare function inputsFor(supplied: readonly SuppliedInputV1[] | undefined, stepRef: string): SuppliedInputV1[];
+/** The merged `data` answers for a step (later entries win). */
+export declare function dataFor(supplied: readonly SuppliedInputV1[] | undefined, stepRef: string): Record<string, unknown>;
+/** The supplied signature over `digest` for a step, if any. Case-insensitive on the digest. */
+export declare function signatureFor(supplied: readonly SuppliedInputV1[] | undefined, stepRef: string, digest?: string): SuppliedInputV1['signature'] | undefined;
+/** What a `suspended` receipt carries about the prompt — the kind and, for a signature, the digest; never
+ *  the answers (those are the person's, and they arrive on the resume). */
+export declare function receiptPending(req: InputRequestV1): NonNullable<StepReceipt['pendingInput']>;
+//# sourceMappingURL=input.d.ts.map

package/dist/input.d.ts.map

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

package/dist/input.js

@@ -0,0 +1,33 @@
+/** Thrown by a tool invoker to suspend the run with a prompt. The loop recognises this class and ONLY this
+ *  class — any other throw is a step failure. */
+export class InputRequired extends Error {
+    request;
+    constructor(request) {
+        super(`input required: ${request.kind} for ${request.toolId} (${request.stepRef})`);
+        this.name = 'InputRequired';
+        this.request = request;
+    }
+}
+export function isInputRequired(e) {
+    return e instanceof InputRequired || (typeof e === 'object' && e !== null && e.name === 'InputRequired' && 'request' in e);
+}
+/** The inputs supplied for one step (a resume may answer several steps at once). */
+export function inputsFor(supplied, stepRef) {
+    return (supplied ?? []).filter((s) => s.stepRef === stepRef);
+}
+/** The merged `data` answers for a step (later entries win). */
+export function dataFor(supplied, stepRef) {
+    return Object.assign({}, ...inputsFor(supplied, stepRef).map((s) => s.data ?? {}));
+}
+/** The supplied signature over `digest` for a step, if any. Case-insensitive on the digest. */
+export function signatureFor(supplied, stepRef, digest) {
+    return inputsFor(supplied, stepRef)
+        .map((s) => s.signature)
+        .find((s) => !!s && (digest === undefined || s.digest.toLowerCase() === digest.toLowerCase()));
+}
+/** What a `suspended` receipt carries about the prompt — the kind and, for a signature, the digest; never
+ *  the answers (those are the person's, and they arrive on the resume). */
+export function receiptPending(req) {
+    return { kind: req.kind, ...(req.kind === 'signature' ? { digest: req.digest, signer: req.signer } : {}), ...(req.kind === 'data' ? { fields: req.fields.map((f) => f.name) } : {}) };
+}
+//# sourceMappingURL=input.js.map

package/dist/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../src/input.ts"],"names":[],"mappings":"AAyHA;iDACiD;AACjD,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,OAAO,CAAiB;IACjC,YAAY,OAAuB;QACjC,KAAK,CAAC,mBAAmB,OAAO,CAAC,IAAI,QAAQ,OAAO,CAAC,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC;QACpF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,eAAe,CAAC,CAAU;IACxC,OAAO,CAAC,YAAY,aAAa,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAuB,CAAC,IAAI,KAAK,eAAe,IAAI,SAAS,IAAI,CAAC,CAAC,CAAC;AACpJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CAAC,QAAgD,EAAE,OAAe;IACzF,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC;AAC/D,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,OAAO,CAAC,QAAgD,EAAE,OAAe;IACvF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;AACrF,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,YAAY,CAAC,QAAgD,EAAE,OAAe,EAAE,MAAe;IAC7G,OAAO,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC;SAChC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;SACvB,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;AACnG,CAAC;AAED;2EAC2E;AAC3E,MAAM,UAAU,cAAc,CAAC,GAAmB;IAChD,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACxL,CAAC"}

package/dist/intent.d.ts

@@ -0,0 +1,37 @@
+import type { DomainLexiconV1, GroundingV1, JudgmentCandidateV1, OntologyCandidateV1 } from './selection.js';
+/** What the agent knows about who is asking — gathered by the harness from what it already holds. Labels and ids only. */
+export interface AskerContextV1 {
+    /** The asker's standing toward this agent. */
+    relation?: 'self' | 'steward' | 'member' | 'stranger';
+    /** Skills this asker used here recently, most frequent first (tool ids with counts). */
+    recentSkills?: ReadonlyArray<{
+        id: string;
+        times: number;
+    }>;
+    /** What the person's own agent remembers about them that bears on a request — short tags ("faith journey: new
+     *  believer", "poker: intermediate"), never a record's text. Present only at the person's own agent. */
+    memoryTags?: readonly string[];
+    /** Spec 417 — domain classes the asker already HOLDS (class IRIs of their typed records, or a comparison's seeded
+     *  state): a chain does not re-produce what is in hand. Classes only, never the records. */
+    heldClasses?: readonly string[];
+}
+export interface InferredIntentReadingV1 {
+    /** Classes the request's words name, with the term that named each. */
+    names: GroundingV1[];
+    /** Spec 418 D4 — the asker's OFFICE, from their memory tags grounded in the lexicon's role classes (a class that declares
+     *  `uses`), with the capabilities that role typically uses: a prior the judge weighs, never a filter. */
+    offices?: Array<{
+        iri: string;
+        uses: string[];
+    }>;
+    /** Classes sharing a semantic cluster with a named one (not named themselves). */
+    near: string[];
+    asker?: AskerContextV1;
+}
+/** Read the request into the ontology's terms (and carry what is known of the asker). */
+export declare function inferIntent(ask: string, candidates: ReadonlyArray<OntologyCandidateV1>, lexicon?: DomainLexiconV1, asker?: AskerContextV1): InferredIntentReadingV1;
+/** The reading as the judge sees it — labels, not IRIs; short. */
+export declare function renderReading(ask: string, reading: InferredIntentReadingV1, labelOf: (iri: string) => string): string;
+/** A skill's CARD in the ontology's terms: one line of purpose, what it produces, what it is not for. */
+export declare function skillCard(c: JudgmentCandidateV1): string;
+//# sourceMappingURL=intent.d.ts.map

package/dist/intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intent.d.ts","sourceRoot":"","sources":["../src/intent.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAG7G,0HAA0H;AAC1H,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;IACtD,wFAAwF;IACxF,YAAY,CAAC,EAAE,aAAa,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D;4GACwG;IACxG,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;gGAC4F;IAC5F,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,uEAAuE;IACvE,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB;6GACyG;IACzG,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACjD,kFAAkF;IAClF,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,uBAAuB,CAYnK;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,MAAM,CAYrH;AAED,yGAAyG;AACzG,wBAAgB,SAAS,CAAC,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAMxD"}

package/dist/intent.js

@@ -0,0 +1,46 @@
+import { groundInLexicon } from './selection.js';
+/** Read the request into the ontology's terms (and carry what is known of the asker). */
+export function inferIntent(ask, candidates, lexicon, asker) {
+    const names = groundInLexicon(ask, candidates, lexicon);
+    const named = new Set(names.map((g) => g.iri));
+    const clustersOf = new Map((lexicon ?? []).map((e) => [e.iri, e.clusters]));
+    const clusters = new Set([...named].flatMap((iri) => clustersOf.get(iri) ?? []));
+    const near = (lexicon ?? []).filter((e) => !named.has(e.iri) && e.clusters.some((c) => clusters.has(c))).map((e) => e.iri).sort();
+    // The asker's office: their memory tags grounded in the role classes only (a role word in the request is the request's).
+    const roles = (lexicon ?? []).filter((e) => e.uses?.length);
+    const offices = asker?.memoryTags?.length && roles.length
+        ? groundInLexicon(asker.memoryTags.join(' . '), [], roles).map((g) => ({ iri: g.iri, uses: [...(roles.find((e) => e.iri === g.iri)?.uses ?? [])] }))
+        : [];
+    return { names, near, ...(offices.length ? { offices } : {}), ...(asker ? { asker } : {}) };
+}
+/** The reading as the judge sees it — labels, not IRIs; short. */
+export function renderReading(ask, reading, labelOf) {
+    const lines = [`Request: ${ask}`];
+    if (reading.names.length)
+        lines.push(`It names (domain terms): ${reading.names.map((g) => `${labelOf(g.iri)} ("${g.term}")`).join('; ')}.`);
+    else
+        lines.push('It names no term of this domain\'s vocabulary.');
+    if (reading.near.length)
+        lines.push(`Nearby in the domain: ${reading.near.slice(0, 8).map(labelOf).join(', ')}.`);
+    const a = reading.asker;
+    if (a?.relation)
+        lines.push(`Asked by: ${a.relation === 'self' ? 'the agent\'s own principal' : `a ${a.relation} of this agent`}.`);
+    if (a?.recentSkills?.length)
+        lines.push(`This asker recently used: ${a.recentSkills.slice(0, 4).map((s) => `${s.id} (${s.times}×)`).join(', ')}.`);
+    if (a?.memoryTags?.length)
+        lines.push(`Known about the asker: ${a.memoryTags.slice(0, 6).join('; ')}.`);
+    for (const o of reading.offices ?? [])
+        lines.push(`The asker's role: ${labelOf(o.iri)} — a role that typically uses ${o.uses.join(', ')}.`);
+    if (a?.heldClasses?.length)
+        lines.push(`The asker already holds: ${a.heldClasses.slice(0, 8).map(labelOf).join(', ')}.`);
+    return lines.join('\n');
+}
+/** A skill's CARD in the ontology's terms: one line of purpose, what it produces, what it is not for. */
+export function skillCard(c) {
+    const purpose = c.description.split(/\bNOT for\b/i)[0].replace(/\s+/g, ' ').trim();
+    const oneLine = purpose.length > 180 ? `${purpose.slice(0, 177).replace(/\s+\S*$/, '')}…` : purpose;
+    const produces = (c.covers ?? []).map((k) => k.label).join(', ');
+    const notFor = (c.excludes ?? []).map((k) => k.label).join(', ');
+    return `${oneLine}${produces ? ` Produces: ${produces}.` : ''}${notFor ? ` Not for: ${notFor}.` : ''}`;
+}
+//# sourceMappingURL=intent.js.map

package/dist/intent.js.map

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

package/dist/judgment.d.ts

@@ -0,0 +1,131 @@
+import type { StructuredCallLike } from './selection.js';
+export declare const NOT_APPLICABLE = "n/a";
+export type JudgmentQuestionV1 = {
+    id: string;
+    kind: 'yes-no';
+    statement: string;
+} | {
+    id: string;
+    kind: 'scale';
+    question: string; /** worst → best */
+    levels: ReadonlyArray<{
+        id: string;
+        describe: string;
+    }>;
+    notApplicable?: string;
+} | {
+    id: string;
+    kind: 'choice';
+    question: string;
+    options: ReadonlyArray<{
+        id: string;
+        describe: string;
+    }>;
+    /** Outcomes that are not options — e.g. "ask the person", "needs several" — listed after the options, never
+     *  shuffled or renamed. */
+    alsoOutcomes?: ReadonlyArray<{
+        id: string;
+        describe: string;
+    }>;
+    /** Describes when NONE of the options applies; present ⇒ `n/a` is an outcome. */ notApplicable?: string;
+};
+/** One question's answer: the normalised distribution over its outcomes, the top outcome, and how far it leads. */
+export interface JudgmentAnswerV1 {
+    id: string;
+    kind: JudgmentQuestionV1['kind'];
+    distribution: Record<string, number>;
+    top: string;
+    /** P(top). */
+    confidence: number;
+    /** P(top) − P(runner-up). */
+    lead: number;
+    /** Scale only: the expected level index (0 = worst), over the applicable levels. */
+    expectedLevel?: number;
+}
+export interface JudgmentV1 {
+    /** The binding that decided (J3), e.g. `ap.decision-model.structured-call.v1`. */
+    judge: {
+        name: string;
+        kind: 'model' | 'mechanical' | 'human';
+    };
+    answers: Record<string, JudgmentAnswerV1>;
+    /** Questions the binding answered in a shape that could not be read as a distribution (J8: said, never guessed). */
+    unreadable: string[];
+    /** The binding failed outright (the provider refused, timed out, called nothing): no answers. */
+    error?: string;
+    /** For each unreadable question, the SHAPE of what came back (types and field names, never values) — so "malformed"
+     *  can be diagnosed without recording anything the judge read or wrote. */
+    received?: Record<string, string>;
+}
+/** Raw distributions from a binding, per question id, before normalisation. */
+export type RawDistributionsV1 = Record<string, Record<string, number>>;
+/** THE DECISION-MODEL PORT (J13): a frozen state + typed questions in, one distribution per question out. A binding
+ *  may add `received`: the shape of anything it could not read (never values). */
+export interface DecisionModelPort {
+    readonly name: string;
+    readonly kind: 'model' | 'mechanical' | 'human';
+    decide(state: string, questions: ReadonlyArray<JudgmentQuestionV1>): Promise<{
+        distributions: RawDistributionsV1;
+        received?: Record<string, string>;
+    }>;
+}
+/** The shape of a value — types and field names only, never a value. */
+export declare function shapeOf(v: unknown, depth?: number): string;
+/** The outcomes a question admits, in order. */
+export declare function outcomesOf(q: JudgmentQuestionV1): string[];
+/** Normalise one raw distribution over a question's outcomes. Unknown keys and non-finite / negative values are
+ *  dropped; an all-zero answer is unreadable (null). Deterministic tie-break by outcome order. */
+export declare function answerOf(q: JudgmentQuestionV1, raw: Record<string, number> | undefined): JudgmentAnswerV1 | null;
+/** Ask a decision model the questions about one state. A failed binding is `error`, never an answer (J8). */
+export declare function judgeQuestions(state: string, questions: ReadonlyArray<JudgmentQuestionV1>, port: DecisionModelPort): Promise<JudgmentV1>;
+/** THE DECLARED DECISION RULE over a choice/scale answer: take the top only when it is an option (not n/a), carries at
+ *  least `floor`, and leads the runner-up (n/a included) by `margin`. Otherwise abstain, naming why. */
+export interface DecisionRuleV1 {
+    floor: number;
+    margin: number;
+}
+export type DecisionV1 = {
+    decided: string;
+} | {
+    decided: null;
+    because: 'not-applicable' | 'below-floor' | 'no-margin' | 'unreadable';
+};
+export declare function applyDecisionRule(answer: JudgmentAnswerV1 | undefined, rule: DecisionRuleV1): DecisionV1;
+/** J10 — the explanation is COMPOSED from the numbers, never generated. */
+export declare function explainAnswer(answer: JudgmentAnswerV1, label?: (outcome: string) => string): string;
+/**
+ * A decision model bound to one forced structured call. The tool's schema has, per question, an array of
+ * `{outcome, p}` with `outcome` an enum of that question's outcomes — and NOTHING ELSE: no reason, no text (J10).
+ * `name` is recorded on every judgment (J3); it should change whenever the prompt or the model changes (J5).
+ */
+export declare function structuredCallDecisionModel(call: StructuredCallLike, opts: {
+    name: string;
+    maxTokens?: number;
+    /** A `scratch` field, FIRST in the schema, where the model may reason before the numbers — for a model that does not
+     *  reason internally (measured 2026-09-26: numbers-only cost Claude Haiku 12 points and its calibration; Gemini, which
+     *  thinks, lost nothing). Discarded here, never returned, never recorded (J7, J10). */
+    privateReasoning?: boolean;
+    /** The questions go in the SYSTEM prompt and the state last, so the prefix is the same on every call for the same
+     *  questions — what a provider's prompt cache keys on. (The default puts the state first.) */
+    stablePrefix?: boolean;
+}): DecisionModelPort;
+export interface AveragedJudgmentV1 extends JudgmentV1 {
+    /** How many permutations were asked and how many answered (an unanswered one is left out of the average, and said). */
+    permutations: {
+        asked: number;
+        answered: number;
+    };
+}
+export declare function judgeQuestionsAveraged(state: string, questions: ReadonlyArray<JudgmentQuestionV1>, port: DecisionModelPort, opts: {
+    permutations: number;
+}): Promise<AveragedJudgmentV1>;
+/** The host call: one letter among `letters`, each letter's reported log-probability. */
+export type LogprobChoiceLike = (input: {
+    system: string;
+    user: string;
+    letters: readonly string[];
+}) => Promise<Record<string, number>>;
+export declare function logprobChoiceDecisionModel(choose: LogprobChoiceLike, opts: {
+    name: string;
+}): DecisionModelPort;
+//# sourceMappingURL=judgment.d.ts.map

package/dist/judgment.d.ts.map

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