@astrosheep/keiyaku 4.5.23 → 4.5.24

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/SKILL.md

@@ -49,6 +49,24 @@ vocabulary, while an explicit empty default permits none. A nested call can use
 only actions permitted by its direct parent Soul. Use `status <aku/...|@alias>`
 to inspect the born worker's frozen effective actions.
 
+## Answer Schemas
+
+For a schema-bearing call or tell through the public API, pass the schema
+directly — `{ schema: z.object({ claim: z.string() }) }` — importing `z` from
+the package root next to `Akuma`. Any Standard Schema v1 value works the same
+way, and the explicit `Schema.zod(...)` and `Schema.json(...)` forms remain
+available for callers who want them.
+
+Keep an answer contract inside simple JSON shape vocabulary: objects, arrays,
+strings, numbers, booleans, enums, literals, and optional or nullable fields.
+Do not attach `.max`, `.min`, `.regex`, `.refine`, `.transform`, or other
+constraint methods. The provider must satisfy the contract, and a fragile or
+unrepresentable constraint fails the loop after submission; the seam refuses
+such a schema at submission and names the offending keyword instead. Enforce
+bounds, formats, and cross-field rules in ordinary caller code after the answer
+arrives, and treat a full JSON Schema through `Schema.json(...)` as the explicit
+waiver a caller signs only when it owns that risk.
+
 ## Akuma Names
 
 An Akuma name selects a reusable worker configuration, not an individual worker.

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/references/automation.md

@@ -53,14 +53,13 @@ investigation, not as a supposedly fresh judge of its own earlier answer.
 ## Public Entry And A Single Structured Turn
 
 Run an ESM script (`.mjs`) in a project where `@astrosheep/keiyaku` resolves.
-The Zod examples also need `zod` available to the script. A globally installed
-CLI alone does not establish Node package resolution for an arbitrary script.
+Import `z` from the package root; a globally installed CLI alone does not
+establish Node package resolution for an arbitrary script.
 Use `keiyaku ls aku/` to select an available Archetype; names and upstream model
 availability are installation-specific.
 
 ```js
-import { Akuma, Schema, World } from "@astrosheep/keiyaku";
-import { z } from "zod";
+import { Akuma, World, z } from "@astrosheep/keiyaku";
 
 const root = await World.at(process.cwd());
 const archetype = process.env.AKUMA_ARCHETYPE;
@@ -74,11 +73,11 @@ const worker = await Akuma.birth(archetype, {
 console.error("worker", worker.id); // Keep the complete AkuId.
 await worker.idle(); // Let the prompt-free birth Body settle before a schema Tell.
 
-const Finding = Schema.zod(z.object({
+const Finding = z.object({
   claim: z.string(),
   evidence: z.array(z.object({ path: z.string(), observation: z.string() })),
   unknowns: z.array(z.string()),
-}).strict());
+});
 
 const finding = await worker.tell(
   "Read the repository guidance and relevant owner documents. Read only; " +
@@ -90,9 +89,19 @@ console.log(JSON.stringify(finding, null, 2));
 ```
 
 `birth` does not submit a prompt. Plain `tell` returns answer text; schema
-`tell` returns the decoded value, not a JSON string to scrape. For a JSON
-Schema and a custom decoder, use `Schema.json(document, decode)` instead of
-`Schema.zod(...)`.
+`tell` returns the decoded value, not a JSON string to scrape. Pass the schema
+directly; any Standard Schema v1 value works the same way. The explicit
+`Schema.zod(...)` wrapper still works, and `Schema.json(document, decode)` is
+the escape hatch for a caller-owned JSON Schema and custom decoder.
+
+Keep an answer contract inside simple JSON shape vocabulary: objects, arrays,
+strings, numbers, booleans, enums, literals, and optional or nullable fields.
+Do not attach `.max`, `.min`, `.regex`, `.refine`, `.transform`, or other
+constraint methods. The provider must satisfy the contract, and a fragile or
+unrepresentable constraint fails the loop after submission; the seam refuses
+such a schema at submission and names the offending keyword instead. Enforce
+bounds, formats, and cross-field rules in ordinary caller code after the answer
+arrives.
 
 Schema makes shape machine-usable, not claims true. Include evidence and
 unknowns in the requested value; acceptance still needs a suitable judge.
@@ -106,14 +115,14 @@ the prompts, schemas, routing, and selection to the task rather than always
 running this exact pipeline.
 
 ```js
-const Claims = Schema.zod(z.object({
-  claims: z.array(z.object({ id: z.string(), text: z.string() })).max(12),
-}).strict());
-const Verdict = Schema.zod(z.object({
+const Claims = z.object({
+  claims: z.array(z.object({ id: z.string(), text: z.string() })),
+});
+const Verdict = z.object({
   verdict: z.enum(["supported", "contradicted", "unknown"]),
   evidence: z.array(z.object({ path: z.string(), observation: z.string() })),
   reason: z.string(),
-}).strict());
+});
 
 // Caller-owned concurrency helper, not a Keiyaku API.
 async function mapSettled(items, concurrency, run) {
@@ -145,6 +154,9 @@ const { claims } = await worker.tell(
 if (new Set(claims.map(c => c.id)).size !== claims.length) {
   throw new Error("Duplicate claim ids");
 }
+if (claims.length > 12) {
+  throw new Error("Claim list exceeded the 12-claim budget");
+}
 
 async function freshJudge(prompt) {
   const judge = await Akuma.birth(archetype, { root, cwd: process.cwd(), readonly: true });
@@ -200,6 +212,13 @@ pairwise comparisons, experiment queues, or adaptive sampling instead.
 - `idle({ timeoutMs })` stops waiting at its timeout, not the worker. A
   `Promise.race` timeout also does not cancel a Tell. Use explicit lifecycle
   operations when you intend to interrupt or stop work.
+- `idle()` resolves an `AkumaIdleResult` saying why it returned, so there is
+  no need to re-poll `status()` to distinguish the outcomes. A completed wait
+  resolves `{ kind: "idle", status, reason }` with `reason` naming the settled
+  life (`"asleep"`, `"killed"`, `"hung"`, `"untidy"`, or `"stranded"`); a
+  passed deadline resolves `{ kind: "timeout", status, reason }` with `reason`
+  naming what was still outstanding as `{ running, pendingTell }`. Both arms
+  carry the final observed `status`.
 - Keep input ids, AkuIds, terminal results, failures, and completed stages in
   caller-owned artifacts if the run must survive its orchestrator process.
   On return, `Akuma.select(root, savedId)` reconnects synchronously; `status()`

package/build/src/akuma/akuma-handle.js

@@ -33,10 +33,13 @@ async function takeLeashUntilSignal(paths, bodySequence, signal, unbounded = fal
 export async function settleAkumaKill(paths, signal, retainLeash = false) {
     const request = await requestStop(paths, new Date().toISOString(), signal);
     if (request.kind !== "requested") {
+        // A witnessed Body was already settled: the kill witness Heart recorded is
+        // the kill evidence, not a stop outcome.
+        const evidence = request.kind === "witnessed" ? "killed" : request.kind;
         if (!retainLeash)
-            return { evidence: request.kind };
+            return { evidence };
         const leash = await acquireLeash(paths, signal === undefined ? {} : { signal });
-        return leash === null ? { evidence: "unavailable" } : { evidence: request.kind, leash };
+        return leash === null ? { evidence: "unavailable" } : { evidence, leash };
     }
     const target = request.body;
     const waited = await takeLeashUntilSignal(paths, target.sequence, signal);

package/build/src/akuma/akuma-instance.d.ts

@@ -5,10 +5,22 @@ import { type AkuId } from "./identity.js";
 import { type ActivityHistory } from "./projection.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
-import { type Schema } from "./schema.js";
+import { type Schema, type StandardSchemaV1 } from "./schema.js";
 export type AkumaIdleOptions = Readonly<{
     timeoutMs?: number;
 }>;
+export type AkumaIdleResult = Readonly<{
+    kind: "idle";
+    status: AkumaStatus;
+    reason: Exclude<AkumaStatus["life"], "running">;
+}> | Readonly<{
+    kind: "timeout";
+    status: AkumaStatus;
+    reason: Readonly<{
+        running: boolean;
+        pendingTell: boolean;
+    }>;
+}>;
 export type AkumaHistoryOptions = Readonly<{
     before?: number;
     since?: number;
@@ -26,7 +38,7 @@ export type AkumaBirthInput = Readonly<{
     allowed?: readonly AllowedAction[];
 }>;
 export type AkumaTellOptions<T> = Readonly<{
-    schema: Schema<T>;
+    schema: Schema<T> | StandardSchemaV1<T>;
     interrupt?: boolean;
     initiator?: string;
 }>;
@@ -45,7 +57,7 @@ export declare class Akuma {
     interrupt(text: string, options?: AkumaSignalOptions & Readonly<{
         initiator?: string;
     }>): Promise<InterruptReceipt>;
-    idle(options?: AkumaIdleOptions): Promise<void>;
+    idle(options?: AkumaIdleOptions): Promise<AkumaIdleResult>;
     history(options?: AkumaHistoryOptions): Promise<ActivityHistory>;
     kill(options?: AkumaSignalOptions): Promise<KillEvidence>;
 }

package/build/src/akuma/akuma-instance.js

@@ -12,7 +12,7 @@ import { parseAkuId, pathsForAkuId } from "./identity.js";
 import { birthAkuma, launchAkuma } from "./publication.js";
 import { projectTurns, selectHistory } from "./projection.js";
 import { settings as readSettings } from "../settings.js";
-import { schemaJsonText } from "./schema.js";
+import { schemaFromStandard, schemaJsonText } from "./schema.js";
 import { abortable } from "./abort.js";
 const HISTORY_LIMIT = 12;
 function signalOption(value) {
@@ -25,6 +25,15 @@ function signalOption(value) {
 function wait(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));
 }
+function pendingTellOf(status) {
+    return status.timeline.entries.some((entry) => entry.kind === "row" && entry.row.kind === "tell" && entry.row.state === "pending");
+}
+function idleResult(status) {
+    const pendingTell = pendingTellOf(status);
+    if (status.life !== "running" && !pendingTell)
+        return { kind: "idle", status, reason: status.life };
+    return { kind: "timeout", status, reason: { running: status.life === "running", pendingTell } };
+}
 function recordedTell(result) {
     if (result.wake.kind === "failed")
         throw new AkumaProviderError(result.wake.diagnostic);
@@ -35,12 +44,12 @@ async function recordPlainTell(id, root, body, tellId, initiator) {
     return recordedTell(admitted);
 }
 async function recordSchemaTell(input) {
-    const { id, body, tellId, options, root } = input;
-    if (options.interrupt === true) {
+    const { id, body, tellId, schema, root } = input;
+    if (input.interrupt === true) {
         const interrupted = await new AkumaHandle(id, root).interrupt(body, {
             tellId,
-            schemaJson: schemaJsonText(options.schema),
-            ...(options.initiator === undefined ? {} : { initiator: options.initiator }),
+            schemaJson: schemaJsonText(schema),
+            ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
         });
         if (interrupted.kind === "unavailable") {
             throw new AkumaProviderError(`schema interrupt unavailable: ${interrupted.evidence}`);
@@ -48,8 +57,8 @@ async function recordSchemaTell(input) {
         return recordedTell(interrupted.tell);
     }
     const admitted = await new AkumaHandle(id, root).tell(body, tellId, undefined, undefined, {
-        schemaJson: schemaJsonText(options.schema),
-        ...(options.initiator === undefined ? {} : { initiator: options.initiator }),
+        schemaJson: schemaJsonText(schema),
+        ...(input.initiator === undefined ? {} : { initiator: input.initiator }),
     });
     return recordedTell(admitted);
 }
@@ -135,19 +144,23 @@ export class Akuma {
         if (typeof text !== "string")
             throw new TypeError("Akuma tell text must be a string");
         const tellId = randomUUID();
-        const recorded = options === undefined || !("schema" in options)
+        const schemaOptions = options !== undefined && "schema" in options ? options : undefined;
+        const schema = schemaOptions === undefined ? undefined : schemaFromStandard(schemaOptions.schema);
+        const recorded = schemaOptions === undefined || schema === undefined
             ? await recordPlainTell(this.id, this.root, text, tellId, options?.initiator)
             : await recordSchemaTell({
                 id: this.id,
                 body: text,
                 tellId,
-                options,
+                schema,
                 root: this.root,
+                ...(schemaOptions.interrupt === undefined ? {} : { interrupt: schemaOptions.interrupt }),
+                ...(schemaOptions.initiator === undefined ? {} : { initiator: schemaOptions.initiator }),
             });
         const outcome = await awaitTellOutcome(this.paths, recorded.tellId);
         if (outcome.kind !== "answered")
             outcomeError(outcome);
-        if (options === undefined || !("schema" in options))
+        if (schema === undefined)
             return outcome.answer;
         const raw = outcome.answerJson ?? outcome.answer;
         let parsed;
@@ -158,7 +171,7 @@ export class Akuma {
             throw new AkumaDecodeError(error instanceof Error ? error.message : "Answer is not valid JSON", outcome.answer);
         }
         try {
-            return options.schema.decode(parsed);
+            return schema.decode(parsed);
         }
         catch (error) {
             throw new AkumaDecodeError(error instanceof Error ? error.message : "Answer failed schema decode", outcome.answer);
@@ -194,8 +207,9 @@ export class Akuma {
         const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
         for (;;) {
             const observed = await bornStatus(this.paths, this.id, { aperture: "monitoring" });
-            if (defaultWaitComplete(observed.status) || (deadline !== undefined && performance.now() >= deadline))
-                return;
+            if (defaultWaitComplete(observed.status) || (deadline !== undefined && performance.now() >= deadline)) {
+                return idleResult(observed.status);
+            }
             await wait(deadline === undefined ? POLL_MS : Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
         }
     }

package/build/src/akuma/akuma.d.ts

@@ -427,6 +427,7 @@ export declare const akumaStatusSchema: z.ZodObject<{
 export type AkumaStatus = z.infer<typeof akumaStatusSchema>;
 export declare function parseAkumaStatus(value: unknown): AkumaStatus;
 export { defaultWaitComplete } from "./akuma-observe.js";
+export { withoutReportedChanges } from "./projection.js";
 export type { ReadonlyRestraint } from "./provider-recipe.js";
 export type * from "./projection.js";
 export type UnbornAkumaListRow = Readonly<{

package/build/src/akuma/akuma.js

@@ -36,6 +36,7 @@ export function parseAkumaStatus(value) {
     return akumaStatusSchema.parse(value);
 }
 export { defaultWaitComplete } from "./akuma-observe.js";
+export { withoutReportedChanges } from "./projection.js";
 export { AkumaNotBornError } from "./akuma-errors.js";
 export function wait(milliseconds) {
     return new Promise((resolve) => setTimeout(resolve, milliseconds));

package/build/src/akuma/fleet-execution.d.ts

@@ -30,6 +30,8 @@ export type WaitExecutionInput = Readonly<{
     signal?: AbortSignal;
     /** Resolves one Akuma's identity facts; consulted once per Akuma a viewer first sees. */
     identity?: (id: AkumaStatus["id"]) => Promise<WaitIdentityFacts>;
+    /** The selected set in the caller's order; a viewer's head and scoreboard follow it. */
+    selectionOrder?: readonly AkumaStatus["id"][];
     /** Reports the frozen selected set before the first round, so a viewer can fix its layout. */
     onSelected?: (selected: readonly WaitSelectedAkuma[]) => void;
     /** Reports every observation round to a live viewer; absent keeps the cheap completion probe. */

package/build/src/akuma/fleet-execution.js

@@ -87,20 +87,37 @@ function delay(milliseconds, signal) {
             signal?.addEventListener("abort", abort, { once: true });
     });
 }
+/** Canonical ids in the caller's selection order, appending any id the caller never named. */
+function selectionOrderedIds(ids, order) {
+    const present = new Set(ids);
+    const seen = new Set();
+    const ordered = [];
+    for (const id of order) {
+        if (present.has(id) && !seen.has(id)) {
+            seen.add(id);
+            ordered.push(id);
+        }
+    }
+    for (const id of ids) {
+        if (!seen.has(id)) {
+            seen.add(id);
+            ordered.push(id);
+        }
+    }
+    return ordered;
+}
 export async function executeWaitAkuma(input) {
     const deadline = input.timeoutMs === undefined ? undefined : performance.now() + input.timeoutMs;
     // Identity facts are read once per observed Akuma, not once per 100ms round.
     const facts = new Map();
     if (input.onSelected !== undefined) {
-        const selected = [];
         for (const id of input.ids) {
             input.signal?.throwIfAborted();
             const known = input.identity === undefined ? undefined : await input.identity(id);
-            const resolved = known ?? { contract: NO_DISPATCH_ASSOCIATION };
-            facts.set(id, resolved);
-            selected.push({ id, ...resolved });
+            facts.set(id, known ?? { contract: NO_DISPATCH_ASSOCIATION });
         }
-        input.onSelected(selected);
+        const ordered = input.selectionOrder === undefined ? input.ids : selectionOrderedIds(input.ids, input.selectionOrder);
+        input.onSelected(ordered.map((id) => ({ id, ...facts.get(id) })));
     }
     const observeRound = async (statuses) => {
         if (input.observe === undefined)

package/build/src/akuma/heart/index.d.ts

@@ -55,6 +55,9 @@ export declare function readKill(paths: AkumaPaths, bodySequence: number): Promi
 export declare function requestStop(paths: AkumaPaths, at: string, signal?: AbortSignal): Promise<Readonly<{
     kind: "requested";
     body: BodyFact;
+}> | Readonly<{
+    kind: "witnessed";
+    body: BodyFact;
 }> | Readonly<{
     kind: "already-killed" | "already-stopped";
     body: BodyFact;

package/build/src/akuma/heart/index.js

@@ -1,5 +1,5 @@
 import { parsePublicHistoryId } from "../identity.js";
-import { answeredTurnFact, endBodyFact, finishBodyFact, insertActivityFact, insertTurnEndFact, insertTurnStartFact, insertPauseControl, insertSessionFact, insertStopControl, killFactForBody, latestBodyFact, latestKillFact, latestSessionFact, lastAnsweredTurnFact, pauseFact, sessionFactForCoordinate, stopFact, turnFact, } from "./rows.js";
+import { answeredTurnFact, endBodyFact, finishBodyFact, deleteStopControl, insertActivityFact, insertTurnEndFact, insertTurnStartFact, insertPauseControl, insertKillFact, insertSessionFact, insertStopControl, killFactForBody, latestBodyFact, latestKillFact, latestSessionFact, lastAnsweredTurnFact, pauseFact, sessionFactForCoordinate, stopFact, turnFact, } from "./rows.js";
 import { insertTellDeliveryFact, dispositionSnapshotProven, insertTellBindingFact, insertTellDispositionSnapshot, insertTellFact, insertTellReceiptFact, insertUndeliveredTellReceipts, latestOpenTellDisposition, openBoundTurns, openTellDispositionIds, pendingTellFacts, hasPendingTell, resolveTellDispositionSnapshot, tellDispositionResolved, tellFact, tellIdsForFence, } from "./tells.js";
 import { activityFactSlice, statusFacts, lastActivityAt as readLastActivityAt, pruneActivityFacts, } from "./timeline.js";
 import { isHeartAbsent, readSealFromLeash, withHeartTransaction, withReadOnlyHeart } from "./storage.js";
@@ -180,8 +180,18 @@ export async function requestStop(paths, at, signal) {
             throw new Error("Akuma has no Body to kill");
         if (latestKillFact(heart)?.bodySequence === body.sequence)
             return { kind: "already-killed", body };
-        if (body.end !== undefined)
+        if (body.end !== undefined) {
+            // A stranded Body is already explicitly settled: kill witnesses it in
+            // place rather than requesting a stop from a dead process. A normally
+            // exited Body remains already-stopped, and hung custody is untouched.
+            if (body.hung === undefined && body.end !== "exited") {
+                insertKillFact(heart, body.sequence, at);
+                if (stopFact(heart)?.bodySequence === body.sequence)
+                    deleteStopControl(heart);
+                return { kind: "witnessed", body };
+            }
             return { kind: "already-stopped", body };
+        }
         const existing = stopFact(heart);
         if (existing !== null && existing.bodySequence !== body.sequence) {
             throw new Error("Akuma stop target is not the latest Body");

package/build/src/akuma/index.d.ts

@@ -1,8 +1,8 @@
 export { Akuma } from "./akuma-instance.js";
-export type { AkumaBirthInput, AkumaHistoryOptions, AkumaIdleOptions, AkumaSignalOptions, AkumaTellOptions, } from "./akuma-instance.js";
+export type { AkumaBirthInput, AkumaHistoryOptions, AkumaIdleOptions, AkumaIdleResult, AkumaSignalOptions, AkumaTellOptions, } from "./akuma-instance.js";
 export type { InterruptReceipt, KillEvidence } from "./akuma.js";
 export { Schema } from "./schema.js";
-export type { JsonSchema, JsonSchemaDocument } from "./schema.js";
+export type { JsonSchema, JsonSchemaDocument, StandardSchemaV1, SchemaLike } from "./schema.js";
 export type { AkuId } from "./identity.js";
 export type { AkumaStatus } from "./akuma.js";
 export type { ActivityHistory, ActivityRow } from "./projection.js";

package/build/src/akuma/projection-read.d.ts

@@ -1,4 +1,6 @@
 import type { ActivitySnapshot, TurnLedger } from "./projection.js";
+/** Present the same snapshot without its reported-change summary. */
+export declare function withoutReportedChanges(snapshot: ActivitySnapshot): ActivitySnapshot;
 import type { HistoryCursor, HistoryPage } from "./projection.js";
 export declare function ordinarySnapshotBudget(ordinaryBudget?: number): Readonly<{
     tail: number;

package/build/src/akuma/projection-read.js

@@ -2,6 +2,10 @@ const DEFAULT_TAIL = 3;
 const DEFAULT_VOICE = 3;
 const REPORTED_CHANGE_LIMIT = 5;
 const EMPTY_REPORTED = { reportedChanges: [], reportedChangesOmitted: 0 };
+/** Present the same snapshot without its reported-change summary. */
+export function withoutReportedChanges(snapshot) {
+    return { ...snapshot, reportedChanges: [], reportedChangesOmitted: 0 };
+}
 function assembleEntries(ledger, window, selected) {
     const windowRows = new Set(window);
     const result = [];

package/build/src/akuma/projection.d.ts

@@ -958,4 +958,4 @@ export type TurnLedger = Readonly<{
 }>;
 /** Fold the retained fact timeline into Turn-owned rows without inventing provider facts. */
 export declare function projectTurns(facts: readonly TimelineFact[], retained?: RetainedWindow): TurnLedger;
-export { ordinarySnapshotBudget, selectHistory, selectSnapshot } from "./projection-read.js";
+export { ordinarySnapshotBudget, selectHistory, selectSnapshot, withoutReportedChanges } from "./projection-read.js";

package/build/src/akuma/projection.js

@@ -406,4 +406,4 @@ export function projectTurns(facts, retained = {
     }
     return finishLedger(state, retained);
 }
-export { ordinarySnapshotBudget, selectHistory, selectSnapshot } from "./projection-read.js";
+export { ordinarySnapshotBudget, selectHistory, selectSnapshot, withoutReportedChanges } from "./projection-read.js";

package/build/src/akuma/schema.d.ts

@@ -3,12 +3,52 @@ export type JsonSchemaDocument = Readonly<{
     readonly [key: string]: unknown;
 }>;
 export type JsonSchema = JsonSchemaDocument;
+export type StandardResult<Output> = Readonly<{
+    readonly value: Output;
+    readonly issues?: undefined;
+}> | Readonly<{
+    readonly issues: readonly Readonly<{
+        readonly message: string;
+    }>[];
+}>;
+/** Structural Standard Schema v1 marker; no runtime dependency on a library. */
+export type StandardSchemaV1<Output = unknown> = Readonly<{
+    readonly "~standard": Readonly<{
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: Readonly<{
+            readonly input: unknown;
+            readonly output: Output;
+        }> | undefined;
+        readonly jsonSchema?: Readonly<{
+            readonly output: (options: Readonly<{
+                readonly target: string;
+            }>) => unknown;
+        }> | undefined;
+    }>;
+}>;
+/** The schema forms a Tell answer contract accepts. */
+export type SchemaLike<T> = Schema<T> | StandardSchemaV1<T>;
 export declare class Schema<T> {
     readonly jsonSchema: JsonSchemaDocument;
     readonly decode: (value: unknown) => T;
     private constructor();
     static zod<Output>(schema: ZodType<Output>): Schema<Output>;
     static json<Output>(schema: JsonSchemaDocument, decode: (value: unknown) => Output): Schema<Output>;
+    /**
+     * Bless a Standard Schema v1 value as a real Schema: validate the marker,
+     * project a JSON Schema document, refuse shapes outside the simple
+     * vocabulary, and decode at the boundary. The class owns this path so every
+     * normalized schema is born through the constructor rather than around it.
+     */
+    static standard<Output>(value: StandardSchemaV1<Output>): Schema<Output>;
 }
+/**
+ * Normalize a Tell answer contract to the internal Schema. The package's own
+ * Schema passes through; anything else delegates to the class's own blessing
+ * path, so inferred output types keep flowing from a genuine Schema instance.
+ */
+export declare function schemaFromStandard<T>(value: SchemaLike<T>): Schema<T>;
 /** Internal neutral serialization for Heart/provider forwarding. */
 export declare function schemaJsonText(schema: Schema<unknown>): string;

package/build/src/akuma/schema.js

@@ -1,5 +1,25 @@
 import { toJSONSchema } from "zod";
 const SCHEMA_JSON_MAX_BYTES = 65_536;
+/**
+ * Keywords a provider answer contract may carry. Provider failures from
+ * fragile constraints are expensive to diagnose, so the seam refuses any
+ * projected document that steps outside simple JSON shape vocabulary.
+ */
+const SIMPLE_SCHEMA_KEYWORDS = new Set([
+    "type",
+    "properties",
+    "required",
+    "items",
+    "enum",
+    "const",
+    "anyOf",
+    "additionalProperties",
+    "description",
+    "title",
+    "$schema",
+    "$defs",
+    "$ref",
+]);
 function isPlainObject(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return false;
@@ -26,6 +46,38 @@ function assertJsonValue(value, path) {
     }
     throw new TypeError(`${path} contains a non-JSON value`);
 }
+/**
+ * Walk every subschema position and refuse a keyword outside the blessed shape
+ * vocabulary. Property names and enum/const data are not keywords, so their
+ * keys are never judged.
+ */
+function assertSimpleSchema(value, path) {
+    if (!isPlainObject(value))
+        throw new TypeError(`${path} must be a JSON Schema object`);
+    for (const [key, entry] of Object.entries(value)) {
+        if (!SIMPLE_SCHEMA_KEYWORDS.has(key)) {
+            throw new TypeError(`provider answer contract uses unsupported JSON Schema keyword "${key}" at ${path}; ` +
+                "provider answer contracts carry simple shapes only");
+        }
+        if (key === "properties" || key === "$defs") {
+            for (const [name, subschema] of Object.entries(entry)) {
+                assertSimpleSchema(subschema, `${path}.${key}.${name}`);
+            }
+        }
+        else if (key === "items") {
+            if (Array.isArray(entry))
+                entry.forEach((subschema, index) => assertSimpleSchema(subschema, `${path}.items[${index}]`));
+            else
+                assertSimpleSchema(entry, `${path}.items`);
+        }
+        else if (key === "anyOf") {
+            entry.forEach((subschema, index) => assertSimpleSchema(subschema, `${path}.anyOf[${index}]`));
+        }
+        else if (key === "additionalProperties" && typeof entry !== "boolean") {
+            assertSimpleSchema(entry, `${path}.additionalProperties`);
+        }
+    }
+}
 function sortValue(value) {
     if (Array.isArray(value))
         return value.map(sortValue);
@@ -62,6 +114,44 @@ function canonicalDocument(value, label) {
     }
     return { json: freezeValue(JSON.parse(jsonText)), jsonText };
 }
+function standardMarker(value) {
+    const marker = typeof value === "object" && value !== null ? value["~standard"] : undefined;
+    if (typeof marker !== "object" ||
+        marker === null ||
+        marker.version !== 1 ||
+        typeof marker.vendor !== "string" ||
+        typeof marker.validate !== "function") {
+        throw new TypeError("schema must be a Schema or a Standard Schema v1 value");
+    }
+    return marker;
+}
+/** Project a Standard Schema value to a JSON Schema document, or refuse honestly. */
+function projectStandardSchema(value, marker) {
+    if (marker.vendor === "zod") {
+        return toJSONSchema(value, { target: "draft-07", unrepresentable: "throw", cycles: "throw" });
+    }
+    const converter = marker.jsonSchema;
+    if (converter !== undefined && typeof converter.output === "function") {
+        return converter.output({ target: "draft-07" });
+    }
+    const method = value.toJSONSchema;
+    if (typeof method === "function") {
+        return method.call(value, { target: "draft-07" });
+    }
+    throw new TypeError(`schema vendor "${marker.vendor}" does not carry a JSON Schema projection; ` +
+        "pass a JSON Schema document and decoder to Schema.json instead");
+}
+function decodeStandard(value, marker) {
+    const result = marker.validate(value);
+    if (result instanceof Promise || (typeof result === "object" && result !== null && "then" in result)) {
+        throw new TypeError(`schema vendor "${marker.vendor}" validates asynchronously`);
+    }
+    if ("issues" in result && result.issues !== undefined) {
+        const detail = result.issues.map((issue) => issue.message).join("; ");
+        throw new Error(detail.length === 0 ? "Standard Schema validation failed" : detail);
+    }
+    return result.value;
+}
 export class Schema {
     jsonSchema;
     decode;
@@ -72,6 +162,7 @@ export class Schema {
     }
     static zod(schema) {
         const payload = toJSONSchema(schema, { target: "draft-07", unrepresentable: "throw", cycles: "throw" });
+        assertSimpleSchema(payload, "$");
         const canonical = canonicalDocument(payload, "Zod JSON Schema");
         return new Schema(canonical.json, (value) => schema.parse(value));
     }
@@ -82,6 +173,29 @@ export class Schema {
         const canonical = canonicalDocument(document, "JSON Schema");
         return new Schema(canonical.json, decode);
     }
+    /**
+     * Bless a Standard Schema v1 value as a real Schema: validate the marker,
+     * project a JSON Schema document, refuse shapes outside the simple
+     * vocabulary, and decode at the boundary. The class owns this path so every
+     * normalized schema is born through the constructor rather than around it.
+     */
+    static standard(value) {
+        const marker = standardMarker(value);
+        const payload = projectStandardSchema(value, marker);
+        assertSimpleSchema(payload, "$");
+        const canonical = canonicalDocument(payload, `${marker.vendor} JSON Schema`);
+        return new Schema(canonical.json, (input) => decodeStandard(input, marker));
+    }
+}
+/**
+ * Normalize a Tell answer contract to the internal Schema. The package's own
+ * Schema passes through; anything else delegates to the class's own blessing
+ * path, so inferred output types keep flowing from a genuine Schema instance.
+ */
+export function schemaFromStandard(value) {
+    if (value instanceof Schema)
+        return value;
+    return Schema.standard(value);
 }
 /** Internal neutral serialization for Heart/provider forwarding. */
 export function schemaJsonText(schema) {