@volter/world-core 2.0.37 → 3.0.0

package/dist/src/runtime.js

@@ -0,0 +1,104 @@
+// @volter/world-core/runtime — the kernel itself and the vendor-independent runtime libraries: the log and the tree
+// read and written directly, checkpoints, branches, landing and receipts, the head, the stores, the runtime's scopes and
+// clocks, and the plugin contract's surfaces. It is the runtime's, the CLI's, the host's and the tooling's. A Protocol 3
+// pack never imports it: its contract is the root, `@volter/world-core` (docs/contributing/architecture.md, "The pack
+// contract: the kernel's root"). Removed v1 entry points fail explicitly. Conformance and validation tooling lives in
+// @volter/world-tooling, a dev dependency.
+// Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
+export { clearRegistry, getPack, hasPack, listPacks, packOf, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from "./packRegistry.js";
+// The DELIVER verb (`emit`) — vendor-agnostic engine + CLI glue; packs declare a TwinEmitter
+// (their event catalog, endpoints-from-state, and signed synthesis) on `TwinPack.emitter`.
+export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
+export { WORLD_CLOCK_ENV, worldNow } from "./world-clock.js";
+export { WORLD_ENV_NAMES_ENV, worldEnvValue } from "./world-env.js";
+export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from "./twin-fetch.js";
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
+export { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
+export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
+export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
+export { deliverEvents, fillEnvelope, signEvent, signEventAll, verifyEvent } from "./events.js";
+export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from "./signing.js";
+export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
+// The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client
+// routes every live vendor call through. The MECHANISM is here; the per-vendor ceiling/window/
+// weights are DATA the pack declares (`TwinPack.rateBudget` / `declareRateBudget`). Exported so an
+// operator can inspect spend (`snapshot`) and a caller can catch `RateBudgetError` by type; there
+// is deliberately no export that disables the guard, and a vendor with no declaration falls back
+// to `DEFAULT_RATE_BUDGET` rather than to no limit at all.
+export { DEFAULT_RATE_BUDGET, MAX_RATE_BUDGET_CEILING, MAX_RATE_BUDGET_WINDOW_MS, MIN_RATE_BUDGET_WEIGHT, MIN_RATE_BUDGET_WINDOW_MS, RateBudget, RateBudgetError, declareRateBudget, hasRateBudgetDeclaration, listRateBudgets, priceCall, rateBudgetPath, rateBudgetPolicy, rateBudgetWeight, resetToSeconds, assertBudgetGuardIntact, } from "./rateBudget.js";
+export { GenericWorldStateSchema, WorldActorSchema, WorldExternalRefSchema, WorldServiceEventSchema, WorldSubjectSchema, } from "./schemas.js";
+// NOTE: source books (event→tracker-source mapping) moved OUT of the world — it was
+// the last tracker coupling. It now lives at `@volter/tracker/world-source-books`,
+// so `@volter/world-core` is a pure twin runtime.
+export { loadWorldConfig, } from "./worldConfig.js";
+export { DELTA_TYPE_SUFFIX, diffSubjectFields, hashFieldValue, subjectKey, deltaAfterFields } from "./hash.js";
+export { appendDurable, appendEvent, createEvent, emptyGenericState, genericWorldReducer, listEvents, loadState, projectionLockPath, readJsonFile, rebuildGenericState, rebuildState, 
+// Scrub: delete pulled data at rest (TWIN-45) — the honest, plain-`rm` counterpart to
+// sync pull's fold-into-the-log. See docs/concepts/data-and-keys.md for the full data-at-rest story.
+scrubService, scrubWorld, stateDirName, 
+// Opt-in structured stderr logging (VOLTER_TWIN_LOG=1) for the audit trail. Public so a
+// CONNECTOR can say on the same stream when the vendor handed it a truncated page — a
+// silent shortfall is the one thing a pull must never pass off as the whole resource.
+twinLog, 
+// The kernel's cross-process mutual-exclusion primitive (exclusive-create lockfile with
+// stale-holder reclaim). Public so world-runtime can guard concurrent `upWorld` claims of
+// one instance dir with the SAME lock semantics the event log uses (TWIN-36).
+withFileLock, worldPaths, worldStateRoot, 
+// Where another pack's store is in a World (architecture A3), and the variable the runtime names its data directory in.
+ownerStoreRoots, WORLD_DATA_ENV, } from "./storage.js";
+// The pluggable persistence seam: the sync WorldStore interface, its fs (default) and
+// in-memory implementations, the active-store injection point, and the async
+// hydrate/flush boundary a serverless (Durable Object / KV / redis) entry uses.
+export { FsWorldStore, MemoryWorldStore, getActiveWorldStore, setActiveWorldStore, withWorldStore, hydrateInto, flushFrom, } from "./world-store.js";
+export { SqlWorldStore } from "./world-store-sql.js";
+// The blob seam (runtime contract R11): byte storage behind byte-carrying handlers, so a
+// serverless namespace puts bytes in object storage while local worlds keep today's layout.
+export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActiveBlobStore, withBlobStore, readBlobRange, } from "./blob-store.js";
+export { applyTwinWrite, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, callerForHeader, callerFromHeader, journalTwinRequest, readTwinRequestJournalFrom, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, recordedInput, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
+export { createTwinProxy } from "./proxy.js";
+export { forkTwin, isFork, readForkMeta, } from "./fork.js";
+export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
+// ── Operator control plane (R19/R20): remote refs, queue lifecycle, push ledger,
+// apply leases, plan, status. (the twins architecture notes)
+// The CHANGESET primitive + the ledger DIFF (docs/concepts/the-model.md v0) — "commit" and
+// "diff" for operational reality: a cross-service base marker, the ledger delta since it, and
+// the content-addressed, replayable changeset over that delta. State-level by construction
+// (it reads the same per-service action ledgers `actions.ts` writes); `volter-world` supplies
+// world discovery and thin verbs on top.
+export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from "./changeset.js";
+export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets } from "./pack-assets.js";
+export { installedPackageDir, packRepository, isDerivedPack, vendorPackageDir, vendorOfPackModule } from "./pack-paths.js";
+// The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
+export * as git from "./git/index.js";
+// S3's wire (contract "S3's wire is a kernel library too"): its XML, CORS, lifecycle, delete batches, ETags, body bytes.
+export * as s3 from "./s3/wire.js";
+// The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
+// The placeholder remote (contract section of that name): the seed is a pull, never a pending write.
+export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from "./placeholder-remote.js";
+export { aliasesFrom, ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from "./log.js";
+export { sealCredential, openSealedCredential, MemoryCredentialStorage, keySealer, transitSealer } from "./credential.js";
+export { validateRemoteOrigin, buildRemoteExecute } from "./executor.js";
+export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRoot, registerAuthStrategy, registerStateSystem, rootPath, runChecks, stateSystemFor, writeRoot } from "./state-system.js";
+export { observeAppends } from "./actions.js";
+export { appendActionIfAbsent, appendActionOccurrence } from "./actions.js";
+// the head and the fold (company contract "The head", "Refresh is the kernel's fold")
+export { answerVendorErrors, performEntries, performAtHead, deployableEntries, headOf, boundRoot, loadChecks, loadCheck, openRootCredential, resealRootCredential, destinationOf, openSealedRecord, sealsThroughVault, rootCustody, sealingKey, setCheckLoader, setSealingKeySource, setSealer, currentSealer, openSealedAt, userKek, userKekPath, vendorOf, worldRootOf, RefusedWriteError, VendorWriteError, HeadError } from "./head.js";
+export { observeResource, observeResources, collectObservations, foldObservations } from "./observe.js";
+export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from "./log.js";
+export { referenceField, registerReferences, packReferences, resolveReferences } from "./references.js";
+// the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
+export { serveHttp, serveStream, nodeBuiltin, WORLD_BOOT_PATH } from "./serve-http.js";
+// two runtime-neutral helpers for a serve path: a file as a Response, a page's client bundle
+export { fileResponse, contentTypeOf } from "./file-response.js";
+export { bundleClient, filePathOf } from "./client-bundle.js";
+// the brand's tokens and faces for a Volter page (the console, the site, the UI kit), fetched at build
+export { brandTokensResponse } from "./brand-tokens.js";
+export { multipartBoundary, multipartParts } from "./multipart.js";
+export { corsHeaders, withCors } from "./cors.js";
+export { vendorFetch, VendorUnreachableError } from "./vendor-call.js";
+export { closeManagedDatabases, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, WORLD_CLOCK_SETTING, worldClockSql } from "./managed-database.js";
+export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobSize, resourceChain, writeResourceBlob } from "./resource-blob.js";
+export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from "./ancestry.js";
+export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from "./history.js";
+export { foldHistory } from "./log.js";
+export { volterHome } from "./volter-home.js";

package/dist/src/s3/wire.d.ts

@@ -0,0 +1,60 @@
+export declare function esc(s: string | number): string;
+/** An element and its children or text. */
+export declare const x: (tag: string, inner: string | number | string[]) => string;
+export declare const doc: (root: string, inner: string[]) => string;
+export declare const xmlAnswer: (body: string, status?: number, headers?: Record<string, string>) => Response;
+export declare function unesc(s: string): string;
+/** Every element of a tag's text in an XML body, unescaped. */
+export declare const allOf: (xml: string, tag: string) => string[];
+/** The first. */
+export declare const oneOf: (xml: string, tag: string) => string | undefined;
+export type CorsRule = {
+    id?: string;
+    allowedOrigins: string[];
+    allowedMethods: string[];
+    allowedHeaders: string[];
+    exposeHeaders: string[];
+    maxAgeSeconds?: number;
+};
+export declare function parseCors(xml: string): CorsRule[];
+export declare function corsXml(rules: CorsRule[]): string;
+/** The first rule that allows the origin, the method and the headers a preflight asks for. */
+export declare function corsRuleFor(rules: CorsRule[], origin: string, method: string, requested: string[]): CorsRule | undefined;
+/** The Access-Control-* headers a matching rule gives an answer ("AllowedOrigins: Specifies the value for the
+ *  Access-Control-Allow-Origin header", and likewise for the methods, headers, exposed headers and max age). */
+export declare function corsHeaders(rule: CorsRule, origin: string, requested: string[], preflight: boolean): Record<string, string>;
+export declare const requestedHeaders: (request: Request) => string[];
+/** A rule's prefix is sent in its Filter or, in S3's older form, on the rule itself, or not at all (R2's lifecycle page
+ *  sends a transition rule with neither, for the whole bucket); it is answered as it was sent. A
+ *  transition moves an object to Infrequent Access (Object lifecycles: "transition objects to Infrequent Access storage
+ *  after 30 days", its example `Transitions: [{ Days: 30, StorageClass: "STANDARD_IA" }]`). */
+export type LifecycleRule = {
+    id: string;
+    enabled: boolean;
+    prefix: string;
+    prefixOnRule?: boolean;
+    noPrefix?: boolean;
+    expireDays?: number;
+    expireDate?: string;
+    abortMultipartDays?: number;
+    transitions?: Array<{
+        days?: number;
+        date?: string;
+        storageClass: string;
+    }>;
+};
+export declare function parseLifecycle(xml: string): LifecycleRule[];
+export declare function lifecycleXml(rules: LifecycleRule[]): string;
+export declare function parseDelete(xml: string): {
+    keys: string[];
+    quiet: boolean;
+};
+export declare const locationConstraintOf: (xml: string) => string | undefined;
+export declare const md5Etag: (bytes: Uint8Array) => string;
+export declare function withBytes(request: Request): Promise<Request>;
+export declare const bytesOf: (request: Request) => Uint8Array;
+/** Concatenate exact wire bytes; no text conversion is involved in multipart assembly. */
+export declare function concatBytes(parts: readonly Uint8Array[]): Uint8Array;
+export type ChecksumAlgorithm = 'MD5' | 'SHA1' | 'SHA256' | 'CRC32' | 'CRC32C' | 'CRC64NVME';
+/** S3's base64 digest; CRC bytes are big-endian on the wire. No streaming framing is decoded here. */
+export declare function checksum(algorithm: ChecksumAlgorithm, bytes: Uint8Array): string;

package/dist/src/s3/wire.js

@@ -0,0 +1,157 @@
+// S3'S WIRE — the XML bodies S3 answers and reads, a bucket's CORS and lifecycle documents, a delete batch, an object's
+// ETag, and a request's body kept as its bytes (docs/contributing/architecture.md, "Other wires": S3's wire is a kernel
+// library, as Redis's command core is). Every vendor that speaks S3's API speaks this wire: AWS S3 itself, Cloudflare
+// R2, and the S3-compatible stores that follow. What differs between them (where a request's account and bucket are,
+// what they refuse, what they implement) is each pack's own. Moved here from the cloudflare pack's R2 lane, which had it
+// ported from the aws pack's S3 code; a pack may import neither (B4). Importing this module does nothing.
+import { createHash } from 'node:crypto';
+// ── XML ──────────────────────────────────────────────────────────────────────────────────────
+const DECL = '<?xml version="1.0" encoding="UTF-8"?>';
+const NS = 'http://s3.amazonaws.com/doc/2006-03-01/';
+export function esc(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+/** An element and its children or text. */
+export const x = (tag, inner) => `<${tag}>${Array.isArray(inner) ? inner.join('') : esc(inner)}</${tag}>`;
+export const doc = (root, inner) => `${DECL}<${root} xmlns="${NS}">${inner.join('')}</${root}>`;
+export const xmlAnswer = (body, status = 200, headers = {}) => new Response(body, { status, headers: { 'content-type': 'application/xml', ...headers } });
+export function unesc(s) {
+    return s.replace(/&(?:lt|gt|quot|apos|amp|#\d+|#x[0-9a-fA-F]+);/g, decodeEntity);
+}
+/** One XML entity, named or numeric, as its character. */
+function decodeEntity(m) {
+    const named = { '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'", '&amp;': '&' };
+    if (named[m])
+        return named[m];
+    const body = m.slice(2, -1);
+    const code = body[0] === 'x' ? Number.parseInt(body.slice(1), 16) : Number(body);
+    return Number.isInteger(code) && code >= 0 && code <= 0x10ffff ? String.fromCodePoint(code) : m;
+}
+/** Every element of a tag's text in an XML body, unescaped. */
+export const allOf = (xml, tag) => [...xml.matchAll(new RegExp(`<${tag}>([\\s\\S]*?)<\\/${tag}>`, 'g'))].map((m) => unesc(m[1].trim()));
+/** The first. */
+export const oneOf = (xml, tag) => allOf(xml, tag)[0];
+export function parseCors(xml) {
+    return [...xml.matchAll(/<CORSRule>([\s\S]*?)<\/CORSRule>/g)].map((m) => {
+        const b = m[1];
+        const id = oneOf(b, 'ID');
+        const age = oneOf(b, 'MaxAgeSeconds');
+        return { ...(id ? { id } : {}), allowedOrigins: allOf(b, 'AllowedOrigin'), allowedMethods: allOf(b, 'AllowedMethod'), allowedHeaders: allOf(b, 'AllowedHeader'), exposeHeaders: allOf(b, 'ExposeHeader'), ...(age ? { maxAgeSeconds: Number(age) } : {}) };
+    });
+}
+export function corsXml(rules) {
+    return doc('CORSConfiguration', rules.map((r) => x('CORSRule', [
+        ...(r.id ? [x('ID', r.id)] : []), ...r.allowedOrigins.map((o) => x('AllowedOrigin', o)), ...r.allowedMethods.map((m) => x('AllowedMethod', m)),
+        ...r.allowedHeaders.map((h) => x('AllowedHeader', h)), ...r.exposeHeaders.map((h) => x('ExposeHeader', h)), ...(r.maxAgeSeconds !== undefined ? [x('MaxAgeSeconds', r.maxAgeSeconds)] : []),
+    ])));
+}
+function wildMatch(pattern, value, fold) {
+    const p = fold ? pattern.toLowerCase() : pattern;
+    const v = fold ? value.toLowerCase() : value;
+    const star = p.indexOf('*');
+    if (star < 0)
+        return p === v;
+    return v.length >= p.length - 1 && v.startsWith(p.slice(0, star)) && v.endsWith(p.slice(star + 1));
+}
+/** The first rule that allows the origin, the method and the headers a preflight asks for. */
+export function corsRuleFor(rules, origin, method, requested) {
+    return rules.find((r) => r.allowedOrigins.some((o) => wildMatch(o, origin, false))
+        && r.allowedMethods.some((m) => m === '*' || m.toUpperCase() === method.toUpperCase())
+        && requested.every((h) => r.allowedHeaders.some((a) => wildMatch(a, h, true))));
+}
+/** The Access-Control-* headers a matching rule gives an answer ("AllowedOrigins: Specifies the value for the
+ *  Access-Control-Allow-Origin header", and likewise for the methods, headers, exposed headers and max age). */
+export function corsHeaders(rule, origin, requested, preflight) {
+    return {
+        'access-control-allow-origin': origin,
+        'access-control-allow-methods': rule.allowedMethods.join(', '),
+        vary: 'Origin, Access-Control-Request-Headers, Access-Control-Request-Method',
+        ...(preflight && requested.length ? { 'access-control-allow-headers': requested.join(', ') } : {}),
+        ...(preflight && rule.maxAgeSeconds !== undefined ? { 'access-control-max-age': String(rule.maxAgeSeconds) } : {}),
+        ...(rule.exposeHeaders.length ? { 'access-control-expose-headers': rule.exposeHeaders.join(', ') } : {}),
+    };
+}
+export const requestedHeaders = (request) => (request.headers.get('access-control-request-headers') ?? '').split(',').map((h) => h.trim()).filter(Boolean);
+export function parseLifecycle(xml) {
+    return [...xml.matchAll(/<Rule>([\s\S]*?)<\/Rule>/g)].map((m) => {
+        const b = m[1];
+        const expiration = /<Expiration>([\s\S]*?)<\/Expiration>/.exec(b)?.[1];
+        const abort = /<AbortIncompleteMultipartUpload>([\s\S]*?)<\/AbortIncompleteMultipartUpload>/.exec(b)?.[1];
+        const days = expiration ? oneOf(expiration, 'Days') : undefined;
+        const date = expiration ? oneOf(expiration, 'Date') : undefined;
+        const after = abort ? oneOf(abort, 'DaysAfterInitiation') : undefined;
+        const transitions = [...b.matchAll(/<Transition>([\s\S]*?)<\/Transition>/g)].map((x) => {
+            const d = oneOf(x[1], 'Days');
+            const on = oneOf(x[1], 'Date');
+            return { ...(d !== undefined ? { days: Number(d) } : {}), ...(on !== undefined ? { date: on } : {}), storageClass: oneOf(x[1], 'StorageClass') ?? '' };
+        });
+        return {
+            id: oneOf(b, 'ID') ?? '', enabled: (oneOf(b, 'Status') ?? 'Enabled') === 'Enabled', prefix: oneOf(b, 'Prefix') ?? '', ...(/<Filter>/.test(b) ? {} : /<Prefix>/.test(b) ? { prefixOnRule: true } : { noPrefix: true }),
+            ...(days ? { expireDays: Number(days) } : {}), ...(date ? { expireDate: date } : {}), ...(after ? { abortMultipartDays: Number(after) } : {}), ...(transitions.length ? { transitions } : {}),
+        };
+    });
+}
+export function lifecycleXml(rules) {
+    return doc('LifecycleConfiguration', rules.map((r) => x('Rule', [
+        x('ID', r.id), ...(r.noPrefix ? [] : [r.prefixOnRule ? x('Prefix', r.prefix) : x('Filter', [x('Prefix', r.prefix)])]), x('Status', r.enabled ? 'Enabled' : 'Disabled'),
+        ...(r.transitions ?? []).map((tr) => x('Transition', [...(tr.date !== undefined ? [x('Date', tr.date)] : [x('Days', tr.days ?? 0)]), x('StorageClass', tr.storageClass)])),
+        ...(r.expireDays !== undefined ? [x('Expiration', [x('Days', r.expireDays)])] : r.expireDate !== undefined ? [x('Expiration', [x('Date', r.expireDate)])] : []),
+        ...(r.abortMultipartDays !== undefined ? [x('AbortIncompleteMultipartUpload', [x('DaysAfterInitiation', r.abortMultipartDays)])] : []),
+    ])));
+}
+// ── bodies ───────────────────────────────────────────────────────────────────────────────────
+export function parseDelete(xml) {
+    return { keys: [...xml.matchAll(/<Object>([\s\S]*?)<\/Object>/g)].map((m) => oneOf(m[1], 'Key') ?? ''), quiet: /<Quiet>\s*true\s*<\/Quiet>/i.test(xml) };
+}
+export const locationConstraintOf = (xml) => oneOf(xml, 'LocationConstraint');
+export const md5Etag = (bytes) => `"${createHash('md5').update(bytes).digest('hex')}"`;
+/** A request's body as the bytes it carried. The derived dispatch reads a body as text to find its parameters, which no
+ *  binary object survives, so the lane's fetch reads the bytes first and keeps them here for the handler. */
+const BODIES = new WeakMap();
+export async function withBytes(request) {
+    if (request.method === 'GET' || request.method === 'HEAD' || request.method === 'OPTIONS')
+        return request;
+    const bytes = new Uint8Array(await request.arrayBuffer());
+    const kept = new Request(request.url, { method: request.method, headers: request.headers, body: bytes });
+    BODIES.set(kept, bytes);
+    return kept;
+}
+export const bytesOf = (request) => BODIES.get(request) ?? new Uint8Array(0);
+/** Concatenate exact wire bytes; no text conversion is involved in multipart assembly. */
+export function concatBytes(parts) {
+    const out = new Uint8Array(parts.reduce((size, part) => size + part.byteLength, 0));
+    let offset = 0;
+    for (const part of parts) {
+        out.set(part, offset);
+        offset += part.byteLength;
+    }
+    return out;
+}
+/** S3's base64 digest; CRC bytes are big-endian on the wire. No streaming framing is decoded here. */
+export function checksum(algorithm, bytes) {
+    if (algorithm === 'MD5' || algorithm === 'SHA1' || algorithm === 'SHA256') {
+        return createHash(algorithm.toLowerCase()).update(bytes).digest('base64');
+    }
+    if (algorithm === 'CRC64NVME') {
+        // AWS's reflected NVME polynomial: aws-checksums/tests/crc64_test.c.
+        let crc = 0xffffffffffffffffn;
+        for (const byte of bytes) {
+            crc ^= BigInt(byte);
+            for (let bit = 0; bit < 8; bit++)
+                crc = (crc >> 1n) ^ (crc & 1n ? 0x9a6c9329ac4bc9b5n : 0n);
+        }
+        const out = new Uint8Array(8);
+        new DataView(out.buffer).setBigUint64(0, crc ^ 0xffffffffffffffffn, false);
+        return Buffer.from(out).toString('base64');
+    }
+    const polynomial = algorithm === 'CRC32C' ? 0x82f63b78 : 0xedb88320;
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit++)
+            crc = (crc >>> 1) ^ (crc & 1 ? polynomial : 0);
+    }
+    const out = new Uint8Array(4);
+    new DataView(out.buffer).setUint32(0, (crc ^ 0xffffffff) >>> 0, false);
+    return Buffer.from(out).toString('base64');
+}

package/dist/src/scenario.d.ts

@@ -19,6 +19,9 @@ export type PackScenarioAdapter<Req> = {
      *  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;
+    /** Whether the request admits a handler's answer (OpenAI's `tool_choice: 'none'` admits no tool call): a handler whose
+     *  answer it does not admit is passed over, and the next that matches answers, else the stub. Absent, every answer. */
+    admits?: (req: Req, respond: unknown) => boolean;
     /** 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

package/dist/src/scenario.js

@@ -231,6 +231,8 @@ export class ScenarioEngine {
                 continue;
             if (!this.matches(r.handler, req, scope))
                 continue;
+            if ("respond" in r.handler && this.adapter.admits && !this.adapter.admits(req, r.handler.respond))
+                continue;
             if (r.handler.once)
                 scope.onceFired.add(r.id);
             if (r.handler.advancePhase !== undefined)

package/dist/src/schema-sample.d.ts

@@ -0,0 +1 @@
+export declare function sampleFromSchema(schema: unknown, name?: string): unknown;

package/dist/src/schema-sample.js

@@ -0,0 +1,21 @@
+export function sampleFromSchema(schema, name = 'value') {
+    const s = (schema && typeof schema === 'object' ? schema : {});
+    if (Array.isArray(s.enum) && s.enum.length)
+        return s.enum[0];
+    if (s.const !== undefined)
+        return s.const;
+    for (const k of ['anyOf', 'oneOf', 'allOf'])
+        if (Array.isArray(s[k]) && s[k].length)
+            return sampleFromSchema(s[k][0], name);
+    const raw = Array.isArray(s.type) ? s.type.find((t) => String(t).toLowerCase() !== 'null') : s.type;
+    const type = typeof raw === 'string' ? raw.toLowerCase() : s.properties ? 'object' : s.items ? 'array' : undefined;
+    switch (type) {
+        case 'object': return Object.fromEntries(Object.entries(s.properties ?? {}).map(([k, v]) => [k, sampleFromSchema(v, k)]));
+        case 'array': return [sampleFromSchema(s.items, name)];
+        case 'integer':
+        case 'number': return typeof s.minimum === 'number' ? s.minimum : 0;
+        case 'boolean': return false;
+        case 'null': return null;
+        default: return s.format === 'date-time' ? '2026-01-01T00:00:00Z' : s.format === 'email' ? 'twin@example.com' : s.format === 'uri' ? 'https://example.com/' : `twin-stub ${name}`;
+    }
+}

package/dist/src/sealed-box.d.ts

@@ -0,0 +1,14 @@
+/** A key pair from a seed: the secret key is SHA-256 of the seed (X25519 clamps it), the public key its X25519 point. */
+export declare function sealedBoxKeyPair(seed: string): {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+/** A sealed box opened with the recipient's key pair: the plaintext, or undefined when it is not one for this key (its
+ *  MAC does not hold). */
+export declare function sealedBoxOpen(sealed: Uint8Array, keyPair: {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}): Uint8Array | undefined;
+/** A sealed box for a recipient's public key, as a client makes one (`gh secret set`, libsodium's `crypto_box_seal`): a
+ *  fresh ephemeral key pair from `seed` (random when none is given), then `ephemeral_pk || mac || ciphertext`. */
+export declare function sealedBoxSeal(message: Uint8Array, recipientPublicKey: Uint8Array, seed?: string): Uint8Array;

package/dist/src/sealed-box.js

@@ -0,0 +1,225 @@
+// SEALED BOXES — libsodium's `crypto_box_seal` opened, for a vendor whose API takes a secret encrypted to a public key it
+// published (GitHub's Actions secrets: "Secrets must be encrypted using the libsodium sealed box", with the repository's
+// public key; `gh secret set` does it). The twin holds the key pair, derived from a seed, so it can decrypt what its
+// runner must receive, as the vendor does. Everything here is deterministic: X25519 from Node, and HSalsa20, XSalsa20,
+// Poly1305 and BLAKE2b written from their specifications (the kernel takes no dependency for them: B1).
+//
+// A sealed box is `ephemeral_pk (32) || mac (16) || ciphertext`; its nonce is BLAKE2b-192(ephemeral_pk || recipient_pk),
+// its key crypto_box_beforenm(ephemeral_pk, recipient_sk) = HSalsa20(X25519(sk, epk), 0), and its body XSalsa20-Poly1305
+// (https://doc.libsodium.org/public-key_cryptography/sealed_boxes, "Algorithm details").
+// a namespace, never named imports: signing.ts reaches this from the kernel a browser client bundles, and the browser's
+// `node:crypto` polyfill has no X25519 (signing.ts, the same rule)
+import * as nodeCrypto from 'node:crypto';
+const PKCS8_X25519 = Buffer.from('302e020100300506032b656e04220420', 'hex');
+const SPKI_X25519 = Buffer.from('302a300506032b656e032100', 'hex');
+/** A key pair from a seed: the secret key is SHA-256 of the seed (X25519 clamps it), the public key its X25519 point. */
+export function sealedBoxKeyPair(seed) {
+    const secretKey = new Uint8Array(nodeCrypto.createHash('sha256').update(`sealed-box:${seed}`).digest());
+    const priv = nodeCrypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519, secretKey]), format: 'der', type: 'pkcs8' });
+    const spki = nodeCrypto.createPublicKey(priv).export({ type: 'spki', format: 'der' });
+    return { publicKey: new Uint8Array(spki.subarray(spki.length - 32)), secretKey };
+}
+function x25519(secretKey, publicKey) {
+    const privateKey = nodeCrypto.createPrivateKey({ key: Buffer.concat([PKCS8_X25519, secretKey]), format: 'der', type: 'pkcs8' });
+    const pub = nodeCrypto.createPublicKey({ key: Buffer.concat([SPKI_X25519, publicKey]), format: 'der', type: 'spki' });
+    return new Uint8Array(nodeCrypto.diffieHellman({ privateKey, publicKey: pub }));
+}
+// ── Salsa20 (https://cr.yp.to/snuffle/spec.pdf) ─────────────────────────────────────────────
+const rotl = (v, c) => ((v << c) | (v >>> (32 - c))) >>> 0;
+const u32 = (b, i) => (b[i] | (b[i + 1] << 8) | (b[i + 2] << 16) | (b[i + 3] << 24)) >>> 0;
+const SIGMA = new TextEncoder().encode('expand 32-byte k');
+/** The Salsa20 state for a key, a 16-byte input (nonce and counter, or HSalsa20's nonce) and the constants. */
+function state(key, input) {
+    const s = new Uint32Array(16);
+    s[0] = u32(SIGMA, 0);
+    s[5] = u32(SIGMA, 4);
+    s[10] = u32(SIGMA, 8);
+    s[15] = u32(SIGMA, 12);
+    for (let i = 0; i < 4; i++) {
+        s[1 + i] = u32(key, i * 4);
+        s[11 + i] = u32(key, 16 + i * 4);
+    }
+    for (let i = 0; i < 4; i++)
+        s[6 + i] = u32(input, i * 4);
+    return s;
+}
+/** Twenty rounds (ten double rounds) over a state, in place. */
+function rounds(x) {
+    for (let i = 0; i < 10; i++) {
+        x[4] ^= rotl((x[0] + x[12]) >>> 0, 7);
+        x[8] ^= rotl((x[4] + x[0]) >>> 0, 9);
+        x[12] ^= rotl((x[8] + x[4]) >>> 0, 13);
+        x[0] ^= rotl((x[12] + x[8]) >>> 0, 18);
+        x[9] ^= rotl((x[5] + x[1]) >>> 0, 7);
+        x[13] ^= rotl((x[9] + x[5]) >>> 0, 9);
+        x[1] ^= rotl((x[13] + x[9]) >>> 0, 13);
+        x[5] ^= rotl((x[1] + x[13]) >>> 0, 18);
+        x[14] ^= rotl((x[10] + x[6]) >>> 0, 7);
+        x[2] ^= rotl((x[14] + x[10]) >>> 0, 9);
+        x[6] ^= rotl((x[2] + x[14]) >>> 0, 13);
+        x[10] ^= rotl((x[6] + x[2]) >>> 0, 18);
+        x[3] ^= rotl((x[15] + x[11]) >>> 0, 7);
+        x[7] ^= rotl((x[3] + x[15]) >>> 0, 9);
+        x[11] ^= rotl((x[7] + x[3]) >>> 0, 13);
+        x[15] ^= rotl((x[11] + x[7]) >>> 0, 18);
+        x[1] ^= rotl((x[0] + x[3]) >>> 0, 7);
+        x[2] ^= rotl((x[1] + x[0]) >>> 0, 9);
+        x[3] ^= rotl((x[2] + x[1]) >>> 0, 13);
+        x[0] ^= rotl((x[3] + x[2]) >>> 0, 18);
+        x[6] ^= rotl((x[5] + x[4]) >>> 0, 7);
+        x[7] ^= rotl((x[6] + x[5]) >>> 0, 9);
+        x[4] ^= rotl((x[7] + x[6]) >>> 0, 13);
+        x[5] ^= rotl((x[4] + x[7]) >>> 0, 18);
+        x[11] ^= rotl((x[10] + x[9]) >>> 0, 7);
+        x[8] ^= rotl((x[11] + x[10]) >>> 0, 9);
+        x[9] ^= rotl((x[8] + x[11]) >>> 0, 13);
+        x[10] ^= rotl((x[9] + x[8]) >>> 0, 18);
+        x[12] ^= rotl((x[15] + x[14]) >>> 0, 7);
+        x[13] ^= rotl((x[12] + x[15]) >>> 0, 9);
+        x[14] ^= rotl((x[13] + x[12]) >>> 0, 13);
+        x[15] ^= rotl((x[14] + x[13]) >>> 0, 18);
+    }
+}
+const put32 = (out, at, v) => { out[at] = v & 255; out[at + 1] = (v >>> 8) & 255; out[at + 2] = (v >>> 16) & 255; out[at + 3] = (v >>> 24) & 255; };
+/** HSalsa20: a 32-byte subkey from a key and a 16-byte nonce (the rounds' words 0, 5, 10, 15, 6, 7, 8, 9, not added). */
+function hsalsa20(key, nonce16) {
+    const x = state(key, nonce16);
+    rounds(x);
+    const out = new Uint8Array(32);
+    [0, 5, 10, 15, 6, 7, 8, 9].forEach((w, i) => put32(out, i * 4, x[w]));
+    return out;
+}
+/** The XSalsa20 keystream of `length` bytes for a key and a 24-byte nonce. */
+function xsalsa20Stream(key, nonce24, length) {
+    const sub = hsalsa20(key, nonce24.subarray(0, 16));
+    const out = new Uint8Array(length);
+    const input = new Uint8Array(16);
+    input.set(nonce24.subarray(16, 24), 0);
+    for (let block = 0, at = 0; at < length; block++, at += 64) {
+        put32(input, 8, block >>> 0);
+        put32(input, 12, Math.floor(block / 0x100000000) >>> 0);
+        const s = state(sub, input);
+        const x = s.slice();
+        rounds(x);
+        const bytes = new Uint8Array(64);
+        for (let i = 0; i < 16; i++)
+            put32(bytes, i * 4, (x[i] + s[i]) >>> 0);
+        out.set(bytes.subarray(0, Math.min(64, length - at)), at);
+    }
+    return out;
+}
+// ── Poly1305 (RFC 8439 section 2.5) ─────────────────────────────────────────────────────────
+function poly1305(key, message) {
+    const le = (b) => b.reduceRight((acc, v) => (acc << 8n) | BigInt(v), 0n);
+    const r = le(key.subarray(0, 16)) & 0x0ffffffc0ffffffc0ffffffc0fffffffn;
+    const s = le(key.subarray(16, 32));
+    const p = (1n << 130n) - 5n;
+    let acc = 0n;
+    for (let i = 0; i < message.length; i += 16) {
+        const chunk = message.subarray(i, i + 16);
+        const n = le(chunk) + (1n << BigInt(8 * chunk.length));
+        acc = ((acc + n) * r) % p;
+    }
+    acc = (acc + s) & ((1n << 128n) - 1n);
+    const out = new Uint8Array(16);
+    for (let i = 0; i < 16; i++) {
+        out[i] = Number(acc & 255n);
+        acc >>= 8n;
+    }
+    return out;
+}
+// ── BLAKE2b (RFC 7693), for the sealed box's 24-byte nonce ────────────────────────────────────
+const IV = [0x6a09e667f3bcc908n, 0xbb67ae8584caa73bn, 0x3c6ef372fe94f82bn, 0xa54ff53a5f1d36f1n, 0x510e527fade682d1n, 0x9b05688c2b3e6c1fn, 0x1f83d9abfb41bd6bn, 0x5be0cd19137e2179n];
+const SIGMA_B = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15], [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+    [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4], [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+    [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13], [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+    [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11], [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+    [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5], [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+];
+const M64 = (1n << 64n) - 1n;
+const rotr64 = (v, c) => ((v >> c) | (v << (64n - c))) & M64;
+function blake2b(input, outlen) {
+    const h = IV.slice();
+    h[0] ^= 0x01010000n ^ BigInt(outlen);
+    const blocks = Math.max(1, Math.ceil(input.length / 128));
+    for (let b = 0; b < blocks; b++) {
+        const chunk = new Uint8Array(128);
+        chunk.set(input.subarray(b * 128, b * 128 + 128));
+        const m = [];
+        for (let i = 0; i < 16; i++) {
+            let w = 0n;
+            for (let j = 7; j >= 0; j--)
+                w = (w << 8n) | BigInt(chunk[i * 8 + j]);
+            m.push(w);
+        }
+        const last = b === blocks - 1;
+        const t = BigInt(last ? input.length : (b + 1) * 128);
+        const v = [...h, ...IV];
+        v[12] ^= t & M64;
+        v[13] ^= t >> 64n;
+        if (last)
+            v[14] ^= M64;
+        const g = (a, bb, c, d, x, y) => {
+            v[a] = (v[a] + v[bb] + x) & M64;
+            v[d] = rotr64(v[d] ^ v[a], 32n);
+            v[c] = (v[c] + v[d]) & M64;
+            v[bb] = rotr64(v[bb] ^ v[c], 24n);
+            v[a] = (v[a] + v[bb] + y) & M64;
+            v[d] = rotr64(v[d] ^ v[a], 16n);
+            v[c] = (v[c] + v[d]) & M64;
+            v[bb] = rotr64(v[bb] ^ v[c], 63n);
+        };
+        for (let r = 0; r < 12; r++) {
+            const s = SIGMA_B[r % 10];
+            g(0, 4, 8, 12, m[s[0]], m[s[1]]);
+            g(1, 5, 9, 13, m[s[2]], m[s[3]]);
+            g(2, 6, 10, 14, m[s[4]], m[s[5]]);
+            g(3, 7, 11, 15, m[s[6]], m[s[7]]);
+            g(0, 5, 10, 15, m[s[8]], m[s[9]]);
+            g(1, 6, 11, 12, m[s[10]], m[s[11]]);
+            g(2, 7, 8, 13, m[s[12]], m[s[13]]);
+            g(3, 4, 9, 14, m[s[14]], m[s[15]]);
+        }
+        for (let i = 0; i < 8; i++)
+            h[i] = h[i] ^ v[i] ^ v[i + 8];
+    }
+    const out = new Uint8Array(outlen);
+    for (let i = 0; i < outlen; i++)
+        out[i] = Number((h[i >> 3] >> BigInt(8 * (i & 7))) & 255n);
+    return out;
+}
+/** A sealed box opened with the recipient's key pair: the plaintext, or undefined when it is not one for this key (its
+ *  MAC does not hold). */
+export function sealedBoxOpen(sealed, keyPair) {
+    if (sealed.length < 48)
+        return undefined;
+    const epk = sealed.subarray(0, 32);
+    const mac = sealed.subarray(32, 48);
+    const body = sealed.subarray(48);
+    const nonce = blake2b(new Uint8Array([...epk, ...keyPair.publicKey]), 24);
+    const key = hsalsa20(x25519(keyPair.secretKey, epk), new Uint8Array(16));
+    const stream = xsalsa20Stream(key, nonce, 32 + body.length);
+    const expected = poly1305(stream.subarray(0, 32), body);
+    let diff = 0;
+    for (let i = 0; i < 16; i++)
+        diff |= expected[i] ^ mac[i];
+    if (diff !== 0)
+        return undefined;
+    const out = new Uint8Array(body.length);
+    for (let i = 0; i < body.length; i++)
+        out[i] = body[i] ^ stream[32 + i];
+    return out;
+}
+/** A sealed box for a recipient's public key, as a client makes one (`gh secret set`, libsodium's `crypto_box_seal`): a
+ *  fresh ephemeral key pair from `seed` (random when none is given), then `ephemeral_pk || mac || ciphertext`. */
+export function sealedBoxSeal(message, recipientPublicKey, seed) {
+    const ephemeral = sealedBoxKeyPair(seed ?? nodeCrypto.randomBytes(32).toString('hex'));
+    const nonce = blake2b(new Uint8Array([...ephemeral.publicKey, ...recipientPublicKey]), 24);
+    const key = hsalsa20(x25519(ephemeral.secretKey, recipientPublicKey), new Uint8Array(16));
+    const stream = xsalsa20Stream(key, nonce, 32 + message.length);
+    const body = new Uint8Array(message.length);
+    for (let i = 0; i < message.length; i++)
+        body[i] = message[i] ^ stream[32 + i];
+    return new Uint8Array([...ephemeral.publicKey, ...poly1305(stream.subarray(0, 32), body), ...body]);
+}