@volter/world-core 2.0.0

package/dist/src/references.d.ts

@@ -0,0 +1,18 @@
+import type { SubjectFields } from './hash.js';
+export type ReferenceDeclaration = {
+    /** the referencing subject type */
+    type: string;
+    /** the referenced subject type */
+    to: string;
+    /** the referenced subject's id, read from the referencing subject's fields (undefined: no reference) */
+    key: (fields: SubjectFields) => string | undefined;
+    /** the fields to overlay once the referenced subject's id is `vendorId` */
+    adopt: (fields: SubjectFields, vendorId: string) => SubjectFields;
+};
+/** The common case: one field holds the referenced subject's id as it is. */
+export declare function referenceField(type: string, field: string, to: string): ReferenceDeclaration;
+export declare function registerReferences(vendor: string, references: ReferenceDeclaration[]): void;
+export declare function packReferences(vendor: string): ReferenceDeclaration[];
+/** `fields` of a `type` subject with every declared reference resolved through `aliases`
+ *  (`${type}:${oldId}` → newId, as `aliasesFrom` builds it). The same object when nothing applies. */
+export declare function resolveReferences(vendor: string, type: string, fields: SubjectFields, aliases: Map<string, string>): SubjectFields;

package/dist/src/references.js

@@ -0,0 +1,27 @@
+/** The common case: one field holds the referenced subject's id as it is. */
+export function referenceField(type, field, to) {
+    return { type, to, key: (f) => (f[field] === undefined || f[field] === null ? undefined : String(f[field])), adopt: (_f, vendorId) => ({ [field]: vendorId }) };
+}
+const REGISTRY = Symbol.for('volter.references');
+const registry = () => (globalThis[REGISTRY] ??= new Map());
+export function registerReferences(vendor, references) { registry().set(vendor, references); }
+export function packReferences(vendor) { return registry().get(vendor) ?? []; }
+/** `fields` of a `type` subject with every declared reference resolved through `aliases`
+ *  (`${type}:${oldId}` → newId, as `aliasesFrom` builds it). The same object when nothing applies. */
+export function resolveReferences(vendor, type, fields, aliases) {
+    if (aliases.size === 0)
+        return fields;
+    let out = fields;
+    for (const ref of packReferences(vendor)) {
+        if (ref.type !== type)
+            continue;
+        const key = ref.key(out);
+        if (key === undefined)
+            continue;
+        const adopted = aliases.get(`${ref.to}:${key}`);
+        if (adopted === undefined || adopted === key)
+            continue;
+        out = { ...out, ...ref.adopt(out, adopted) };
+    }
+    return out;
+}

package/dist/src/remote-execute.d.ts

@@ -0,0 +1,22 @@
+export type RemoteExecuteRequest = {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    /** A JSON text, or raw bytes (a multipart upload) — the host hands either to fetch as is. */
+    body?: string | Uint8Array;
+    /** Opt into exact bytes for object/attachment downloads; JSON clients keep body text. */
+    responseType?: 'bytes';
+    /** A URL the vendor itself returned for an upload, already carrying its own authorization
+     *  (LinkedIn's video parts on www.linkedin.com/dms-uploads, Slack's upload_url, TikTok's
+     *  upload.<region>.tiktokapis.com): `path` is then that absolute URL, often on another host than
+     *  the API, and the request goes WITHOUT the sealed credential. An upload the vendor authorizes
+     *  with the API token (LinkedIn's images) is not presigned and cannot use this. */
+    presigned?: true;
+};
+export type RemoteExecuteResponse = {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    bodyBytes?: Uint8Array;
+};
+export type RemoteExecute = (request: RemoteExecuteRequest) => Promise<RemoteExecuteResponse>;

package/dist/src/remote-execute.js

@@ -0,0 +1 @@
+export {};

package/dist/src/resource-blob.d.ts

@@ -0,0 +1,10 @@
+/** Read a resource payload at this branch, then its retained ancestors. */
+export declare function readResourceBlob(service: string, key: string, root?: string): Promise<Uint8Array | null>;
+/** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
+ *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
+export declare function resourceChain(service: string, root?: string): string[];
+/** Size of a resource payload at this branch or its ancestors, or null. */
+export declare function resourceBlobSize(service: string, key: string, root?: string): Promise<number | null>;
+/** A byte range of a resource payload at this branch or its ancestors (a ranged read where the
+ *  store has one), or null when absent. */
+export declare function readResourceBlobRange(service: string, key: string, start: number, endInclusive: number, root?: string): Promise<Uint8Array | null>;

package/dist/src/resource-blob.js

@@ -0,0 +1,56 @@
+import { isAbsolute, join } from 'node:path';
+import { getActiveBlobStore, readBlobRange } from "./blob-store.js";
+import { readBranchMeta } from "./log.js";
+import { worldPaths } from "./storage.js";
+/** Read a resource payload at this branch, then its retained ancestors. */
+export async function readResourceBlob(service, key, root) {
+    assertResourceKey(key);
+    for (const dir of resourceChain(service, root)) {
+        const bytes = await getActiveBlobStore().get(join(dir, key));
+        if (bytes !== null)
+            return bytes;
+    }
+    return null;
+}
+/** A service's resources dir at this branch, then at each retained ancestor's: where a read resolves a payload, and
+ *  what a listing that mints ids covers, so a branch serves bytes its parent received and never re-mints a parent's id. */
+export function resourceChain(service, root) {
+    const out = [];
+    const seen = new Set();
+    let current = worldPaths(service, root).root;
+    for (;;) {
+        if (seen.has(current))
+            throw new Error('Cyclic resource blob ancestry');
+        seen.add(current);
+        out.push(worldPaths(service, current).resources);
+        const parent = readBranchMeta(service, current)?.parent;
+        if (!parent)
+            return out;
+        current = parent.at;
+    }
+}
+function assertResourceKey(key) {
+    if (isAbsolute(key) || key.includes('\0') || key.split(/[\\/]/).includes('..'))
+        throw new Error('Invalid relative resource blob key');
+}
+/** The key's full path at the first of this branch and its retained ancestors that holds it. */
+async function resolveResourceBlob(service, key, root) {
+    assertResourceKey(key);
+    for (const dir of resourceChain(service, root)) {
+        const path = join(dir, key);
+        if (await getActiveBlobStore().exists(path))
+            return path;
+    }
+    return null;
+}
+/** Size of a resource payload at this branch or its ancestors, or null. */
+export async function resourceBlobSize(service, key, root) {
+    const path = await resolveResourceBlob(service, key, root);
+    return path === null ? null : getActiveBlobStore().size(path);
+}
+/** A byte range of a resource payload at this branch or its ancestors (a ranged read where the
+ *  store has one), or null when absent. */
+export async function readResourceBlobRange(service, key, start, endInclusive, root) {
+    const path = await resolveResourceBlob(service, key, root);
+    return path === null ? null : readBlobRange(path, start, endInclusive);
+}

package/dist/src/scenario.d.ts

@@ -0,0 +1,197 @@
+/** A vendor-agnostic bag of facts about one request, produced by the pack's adapter. Powers
+ *  matching context, miss records (the authoring signal), and the self-teaching stub text. */
+export type ScenarioFeatures = Record<string, string | number | boolean | readonly string[]>;
+/** One matcher: does THIS request satisfy `condition`? Pure — no state, no IO. */
+export type ScenarioMatcher<Req> = (req: Req, condition: unknown) => boolean;
+/** The pack's declaration of its vocabulary — the ONLY vendor-specific surface. */
+export type PackScenarioAdapter<Req> = {
+    /** Vendor key, e.g. "anthropic" — used in errors and the manifest. */
+    vendor: string;
+    /** Extract the feature bag for miss records / stub teaching. Pure. */
+    features: (req: Req) => ScenarioFeatures;
+    /** The legal `on` keys and their per-request semantics. Pure. */
+    matchers: Record<string, ScenarioMatcher<Req>>;
+    /** Validate `on` CONDITION VALUES at load (key membership is the kernel's; VALUE typing is
+     *  the pack's — "a string nthCall silently never matches" is exactly the misfire strict
+     *  loading exists to prevent). Return an error string to refuse. */
+    validateOn?: (on: Record<string, unknown>) => string | null;
+    /** Validate a handler's `respond` payload at load; return an error string to refuse.
+     *  This is ALSO where a pack refuses success-shaped handlers on stateful routes
+     *  ("seed that through the vendor's API instead"). */
+    validateRespond?: (respond: unknown, handler: ScenarioHandler) => string | null;
+    /** The request's text corpus for `textPattern` extractors (packs with text requests). */
+    text?: (req: Req) => string;
+    /** Pack-defined extractor KINDS beyond the builtins (feature, textPattern). A pack kind with
+     *  a builtin's name OVERRIDES the builtin (e.g. a richer textPattern with flags/group).
+     *  validate returns an error string to refuse the spec at load; extract runs at serve time
+     *  and throws ScenarioError when the request cannot supply the value. */
+    extractorKinds?: Record<string, {
+        validate: (spec: Record<string, unknown>, name: string) => string | null;
+        extract: (spec: Record<string, unknown>, req: Req, name: string) => string | number;
+    }>;
+    /** The per-session scope discriminator; omitted → all requests share one "world" scope. */
+    scopeKey?: (req: Req) => string;
+    /** The VENDOR'S error envelope for a `status` fault — a 429 from this vendor looks like this
+     *  vendor's 429. Omitted → the kernel's envelope `{ error: { message, type: "twin_fault" } }`. */
+    renderFault?: (fault: ScenarioStatusFault, req: Req) => {
+        body: unknown;
+        headers?: Record<string, string>;
+    };
+};
+/** THE FAULT VOCABULARY (runtime contract R15 — outage rehearsal as a world-level value). One
+ *  grammar every pack's engine honors, so a 429 or a hung request is authored the same way for
+ *  every vendor instead of improvised per realizer:
+ *    slow   — hold the answer `ms` before serving it (the response is whatever the handler's
+ *             `respond` or the twin's own path produces; timing is not content, R9 holds);
+ *    status — answer this HTTP status instead of serving: a 4xx/5xx the vendor's own envelope
+ *             (the pack's adapter renders it; a kernel envelope when it declares none), with
+ *             `Retry-After` when `retryAfterSeconds` is set;
+ *    drop   — never answer: the request hangs until the client's own timeout ends it (what an
+ *             outage looks like from the client; a TCP reset is not something a fetch can do),
+ *             released after `holdMs` (default 300 000) so a socket is not held forever. */
+export type ScenarioFault = {
+    kind: "slow";
+    ms: number;
+} | {
+    kind: "status";
+    status: number;
+    retryAfterSeconds?: number;
+    message?: string;
+} | {
+    kind: "drop";
+    holdMs?: number;
+};
+export type ScenarioStatusFault = Extract<ScenarioFault, {
+    kind: "status";
+}>;
+/** What a `status` fault serves: the pack's rendered envelope, or the kernel's. */
+export type ScenarioFaultResult = {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+};
+export type ScenarioHandler = {
+    /** Stable id for status/telemetry; defaults to `handler-<1-based index>`. */
+    id?: string;
+    /** Conditions — ALL must hold. `{}` matches every request (an ordered catch-all). */
+    on: Record<string, unknown>;
+    /** Pack-realized response content (the pack's realizer builds the faithful envelope).
+     *  Optional only on a handler that carries a `fault` (a `slow` may still carry one; a
+     *  `status` or `drop` serves no content, so it must not). */
+    respond?: unknown;
+    /** A fault to inject when this handler fires (ScenarioFault). Same once/phase/scope
+     *  semantics as any handler — a mid-story outage is `{on, fault, once}` or `{phase}`. */
+    fault?: ScenarioFault;
+    /** Fire at most once per scope. */
+    once?: boolean;
+    /** Reserved: "world" (default) | "session" — with "session", once/phase state is per
+     *  scopeKey instead of shared. */
+    scope?: "world" | "session";
+    /** Fires only while the scope's phase equals this. Handlers without `phase` fire in any. */
+    phase?: string;
+    /** On fire, move the scope's phase — the tiny sequencing primitive that replaces
+     *  linear scripts and nthCall arithmetic. */
+    advancePhase?: string;
+};
+/** Request-derived values a `respond` payload may reference as "{{name}}" placeholders —
+ *  builtin kinds, or any kind the pack's adapter declares. Payload placeholders support the
+ *  numeric transforms `{{name|min:N}}` / `{{name|max:N}}`; a whole-string placeholder yields
+ *  the TYPED value (numbers stay numbers). */
+export type ScenarioExtractorSpec = {
+    kind: "feature";
+    feature: string;
+} | {
+    kind: "textPattern";
+    pattern: string;
+    as?: "string" | "number";
+} | ({
+    kind: string;
+} & Record<string, unknown>);
+export type ScenarioDocument = {
+    extractors?: Record<string, ScenarioExtractorSpec>;
+    handlers: ScenarioHandler[];
+};
+export type ScenarioMissRecord = {
+    features: ScenarioFeatures;
+    phase: string | undefined;
+};
+export type ScenarioDecision = {
+    kind: "handler";
+    handler: ScenarioHandler;
+    respond: unknown;
+    ruleId: string;
+    fault?: ScenarioFault;
+} | {
+    kind: "miss";
+    miss: ScenarioMissRecord;
+};
+export type ScenarioStatus = {
+    vendor: string;
+    handlers: Array<{
+        id: string;
+        phase?: string;
+        once?: boolean;
+        scope?: string;
+        matches: number;
+        source: "file" | "use";
+    }>;
+    misses: number;
+    recentMisses: ScenarioMissRecord[];
+};
+export declare class ScenarioError extends Error {
+}
+/** Strict-loud parse of a scenario DOCUMENT (the per-vendor handlers/<vendor>.json content).
+ *  The caller does file IO; this validates. Every refusal names the valid vocabulary. */
+export declare function parseScenarioDocument<Req>(raw: unknown, adapter: PackScenarioAdapter<Req>): ScenarioDocument;
+/** The engine: pure state machine over registered handlers. One instance per twin server. */
+export declare class ScenarioEngine<Req> {
+    private readonly adapter;
+    private readonly extractors;
+    private baseline;
+    private overrides;
+    private scopes;
+    private missCount;
+    private recentMisses;
+    constructor(adapter: PackScenarioAdapter<Req>, document?: ScenarioDocument);
+    /** In-process test overrides: LIFO over the baseline; returns a remover. NOT a runtime
+     *  door — nothing outside this process can reach it, by design. */
+    use(...handlers: ScenarioHandler[]): () => void;
+    /** Decide one request. Mutates scope state (calls, once, phase) exactly like serving. */
+    next(req: Req): ScenarioDecision;
+    /** Decide one request AND honor its fault: a `slow` is awaited here and the decision is
+     *  returned for the pack to serve; a `status` returns the rendered refusal to serve as-is; a
+     *  `drop` never resolves within its hold. The one call a realizer makes so every vendor's
+     *  outage reads the same. */
+    serve(req: Req, signal?: AbortSignal): Promise<ScenarioDecision | {
+        kind: "fault";
+        result: ScenarioFaultResult;
+        ruleId: string;
+    }>;
+    /** For GET /twin/scenario — active handlers with match counts, and the recent misses. */
+    status(): ScenarioStatus;
+    private scope;
+    private matches;
+    private extractValue;
+    private substitute;
+}
+export declare function scenarioFaultResult(fault: ScenarioFault, render?: () => {
+    body: unknown;
+    headers?: Record<string, string>;
+} | undefined, signal?: AbortSignal): Promise<ScenarioFaultResult | null>;
+export declare function statefulTwinManifest(input: {
+    vendor: string;
+    twinOf: string;
+    stores: string;
+    identity?: string;
+    notes?: string;
+}): Record<string, unknown>;
+/** The GET /twin manifest — the discovery door's body. Education ships INSIDE the twin:
+ *  in-world agents have no repos or skills, only HTTP. */
+export declare function twinManifest(input: {
+    vendor: string;
+    twinOf: string;
+    stateSentence: string;
+    behaviorSentence: string;
+    exampleHandler: ScenarioHandler | null;
+    engine?: ScenarioEngine<never>;
+}): Record<string, unknown>;