@volter/world-core 2.0.37 → 3.0.1

package/src/index.ts

@@ -1,336 +1,89 @@
-// @volter/world-core — the shared state kernel and vendor-independent runtime libraries.
-// Protocol-2 packs read the checkpointed tree and write through the head's state system.
-// The kernel owns logs, branches, landing and receipts; each pack owns its vendor's wire
-// and resource semantics. See docs/concepts/the-model.md and docs/contributing/architecture.md.
-// Compatibility exports below are not a second state model. Refer to their implementations
-// before using older operator helpers; removed v1 entry points fail explicitly.
-// Conformance/validation tooling (capability + spec + recorded-diff + UI harnesses and
-// the spec derivers) is NOT part of the runtime kernel — it lives in @volter/world-tooling,
-// a dev dependency. A twin runs without it; only tests and the conformance scripts use it.
-// Pack registry — vendor twins self-describe (TwinPack) so tooling discovers them.
-export { clearRegistry, getPack, hasPack, listPacks, registerPack, pullPosture, assertContinuousPullAllowed, pullOnSchedule, resolvePullVendor, DEFAULT_PULL_POSTURE, DEFAULT_PULL_TRIGGER, PROTOCOL_VERSION, PROTOCOL_MAJOR, protocolStanding } from './packRegistry.ts';
-export type { PackTransport, PullPosture, PullTrigger, PullVendor, RoundTripWrite, TwinPack } from './packRegistry.ts';
-// 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.ts';
-export { WORLD_CLOCK_ENV, worldNow } from './world-clock.ts';
-export { WORLD_ENV_NAMES_ENV, worldEnvValue } from './world-env.ts';
-export { createTwinFetchFromHandler, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, twinPublicBase, withRequestScopes } from './twin-fetch.ts';
-export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
-export { compileSurface, createDerivedFetch, matchOperation } from './derived.ts';
-export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
-export type { Traceparent } from './trace-context.ts';
-export type { DerivedCall, DerivedCoreOutcome, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface } from './derived.ts';
-export { bindSemantics, coreFor, crossCutting, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.ts';
-export type { Actor, CoreScope, DerivedManifest, ErrorSpec, FieldRule, Handler, HandlerContext, ResourceDecl, WriteHookContext, ScreenDecl, Semantics, SemanticsContext, StateField, Transition, TransitionObserver } from './derived-core.ts';
-export type { RemoteExecute, RemoteExecuteRequest, RemoteExecuteResponse } from './remote-execute.ts';
-export type { TwinFetchAdapterConfig, TwinFetchHandlerRequest, TwinFetchHandlerResult, TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
-export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';
-export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from './emit.ts';
-export type { EmitDeliveryResult, EmitEndpoint, EmitReport, EmittableEvent, SynthesizedDelivery, TwinEmitter } from './emit.ts';
-// 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.ts';
-export type {
-  RateBudgetDeclaration,
-  RateBudgetErrorKind,
-  RateBudgetOptions,
-  RateBudgetPolicy,
-  RateBudgetReservation,
-  RateBudgetSnapshot,
-  RateBudgetWeightRule,
-} from './rateBudget.ts';
-export {
-  GenericWorldStateSchema,
-  WorldActorSchema,
-  WorldExternalRefSchema,
-  WorldServiceEventSchema,
-  WorldSubjectSchema,
-} from './schemas.ts';
-// 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.ts';
-export type {
-  WorldConfig,
-  WorldServiceConfig,
-} from './worldConfig.ts';
-export {
-  DELTA_TYPE_SUFFIX,
-  diffSubjectFields,
-  hashFieldValue,
-  subjectKey, deltaAfterFields } from './hash.ts';
-export type {
-  FieldChange,
-  SubjectFields,
-} from './hash.ts';
-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.ts';
-export type {
-  AppendEventResult,
-  CommitQueuedEventsResult,
-  GenericWorldState,
-  EnqueueEventResult,
-  QueuedWorldServiceEvent,
-  WorldPaths,
-  WorldReducer,
-  WorldServiceEvent,
-} from './types.ts';
-export type { ScrubResult } from './storage.ts';
-// 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.ts';
-export type { WorldStore, WorldStat, HydrationSource, HydrationSink } from './world-store.ts';
-export type { CheckLoader } from './head.ts';
-export { SqlWorldStore } from './world-store-sql.ts';
-export type { SqlExec } from './world-store-sql.ts';
-// 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.ts';
-export type { BlobStore } from './blob-store.ts';
-export {
-  applyTwinWrite,
-  applyTwinWriteAtomic,
-  createTwinServer,
-  CALLER_HEADER,
-  journalTwinRequest,
-  twinRequestJournalFailures,
-  twinRequestCredentials,
-  readTwinRequestJournal,
-  resolveTwinRead,
-  twinRequestJournalEnabled,
-  twinRequestJournalPath,
-  readTwinRequestJournalFrom,
-  type TwinRequestJournalCursor,
-  twinResources,
-} from './serve.ts';
-export type {
-  AtomicTwinWriteDecision,
-  TwinRequestJournalEntry,
-  TwinResource,
-  TwinWriteInput,
-  TwinWriteResult,
-} from './serve.ts';
-export { createTwinProxy } from './proxy.ts';
-export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.ts';
-export {
-  forkTwin,
-  isFork,
-  readForkMeta,
-} from './fork.ts';
-export type { ForkMeta } from './fork.ts';
-export {
-  appendAction,
-  appendTransactionCommit,
-  checkPrecondition,
-  confirmAction,
-  listActions,
-  listTransactionCommits,
-  pendingActions,
-  pushablePendingActions,
-  isTwinBookkeeping,
-  pendingTransactionCommits,
-  projectResources,
-  projectOwnerResources,
-  OwnerStoreAmbiguousError,
-  revertAction,
-  TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.ts';
-export type {
-  ActionProjection,
-  ProjectedDelivery,
-  ProjectedResource,
-  ProjectedResourcePatch,
-  ProjectedResourceRef,
-  TwinAction,
-  TwinActionOp,
-  TwinActionPrecondition,
-  TwinActionPreconditionOp,
-  TwinActionRevertSpec,
-  TwinTransactionCommit,
-  TwinTransactionCommitOp,
-  TwinTransactionPrecondition,
-  TwinTransactionRevertSpec,
-} from './actions.ts';
-// ── 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.ts';
-export type {
-  ApplyReceipt,
-  RebaseActionResult,
-  RebaseReport,
-  RebaseTarget,
-  Changeset,
-  ChangesetAction,
-  ChangesetApplication,
-  CompensationEntry,
-  ChangesetApproval,
-  ChangesetReadiness,
-  ChangesetVerification,
-  ChangesetVerifier,
-  ChangesetVerifierResult,
-  LedgerDelta,
-  LedgerPosition,
-  LedgerRef,
-  ReplayActionResult,
-  ReplayReport,
-  ReplayTarget,
-  VendorSummary,
-  WorldMarker,
-} from './changeset.ts';
-export { getActivePackAssets, setActivePackAssets, packAsset, assetContentType, confinedAssetPath, LocalPackAssets, BindingPackAssets, type PackAssetStore } from './pack-assets.ts';
-
-// The git plane (contract "The git plane is a kernel library"): objects, packs, refs, smart HTTP.
-export * as git from './git/index.ts';
+// @volter/world-core — the pack contract (docs/contributing/architecture.md, "The pack contract: the kernel's root").
+// This root is everything a Protocol 3 pack may import from the kernel, and nothing else: the manifest's and the
+// descriptor's types, the handler contract, the derived fetch and core a pack's fetch.ts builds, the serve factory's
+// pieces, the kernel's deterministic helpers and the scenario grammar. The kernel itself (the log and the tree read
+// and written directly, the head, the stores, the runtime's scopes) and the plugin contract's surfaces are
+// `@volter/world-core/runtime`, which a pack never imports.
+import { bindSemantics as bindAny, type CoreScope, type Handler } from './derived-core.ts';
+import type { DerivedHandler, DerivedSurface } from './derived.ts';
+import type { DerivedManifest } from './derived-core.ts';
+import { packOf as packOfAny, registerPack as registerAny, type PackDescriptor } from './packRegistry.ts';
 
-// The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
+// ── the descriptor ─────────────────────────────────────────────────────────────────────────────
+export type { PackDescriptor, PackTransport } from './packRegistry.ts';
+/** The descriptor a manifest declares, with its vendor ("The descriptor"); given the pack's generated surface (a vendor of
+ *  lanes: each lane's manifest and surface), with the real-system adapters the kernel derives from them. */
+export const packOf = (
+  manifest: { vendor: string; descriptor?: Omit<PackDescriptor, 'vendor'> },
+  surface?: DerivedSurface | Record<string, { manifest: DerivedManifest; surface: DerivedSurface }>,
+): PackDescriptor => packOfAny(manifest, surface);
+/** The pack registered, so the World finds it. */
+export const registerPack = (pack: PackDescriptor): PackDescriptor => registerAny(pack);
 
-// 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.ts';
+// ── the manifest ───────────────────────────────────────────────────────────────────────────────
+export type { Actor, CoreScope, DerivedManifest, ErrorSpec, LaneRoute, LanesDecl, VendorManifest, FieldRule, ResourceDecl, ScreenDecl, SeedCall, StateField, Transition } from './derived-core.ts';
+export type { ApplicationAnswer, EndpointsDecl, EventRender, EventScheme, EventsDecl, EventTransport, EventValues, EventWrite } from './events.ts';
+export { verifyEvent } from './events.ts';
+export { deriveStateSystem, deriveVendorStateSystem } from './derived-real.ts';
+export type { IngestDecl } from './derived-core.ts';
+export type { SocketDecl, SocketEngine, SocketSession } from './sockets.ts';
+export { machinePool, type ExecSpec, type MachinePool, type MachineProcess, type MachineRun, type MachineSpec } from './machines.ts';
+export type { CorsDecl } from './cors.ts';
 
-export { 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.ts';
-export type { BranchMeta, Entry, EntryOp, Receipt } from './log.ts';
-export { sealCredential, openSealedCredential, MemoryCredentialStorage, keySealer, transitSealer, type Rewrapped, type Sealer, type TransitSealerOptions, type SealedByVault, type SealedUnderKey } from './credential.ts';
-export type { CredentialPayload, CredentialStorage, SealedCredential } from './credential.ts';
-export { validateRemoteOrigin, buildRemoteExecute, type CredentialCustody } from './executor.ts';
-export type { TwinAuthStrategy } from './executor.ts';
-export { clearRoot, authStrategyFor, clearStateSystems, NO_SECRETS_CHECK, readRoot, registerAuthStrategy, registerStateSystem, rootPath, runChecks, stateSystemFor, writeRoot } from './state-system.ts';
-export type { Check, CheckVerdict, DeployPolicy, RootConfig, StateSystemAdapters } from './state-system.ts';
-export { observeAppends } from './actions.ts';
-export { appendActionIfAbsent, appendActionOccurrence } from './actions.ts';
+// ── the handler contract ───────────────────────────────────────────────────────────────────────
+export type { Handler, HandlerContext, WriteHookContext } from './derived-core.ts';
+export type { MultipartPart } from './multipart.ts';
+/** A pack's handlers, by operationId, bound to the manifest: each is answered over the contract's context. */
+export const bindSemantics = (m: Parameters<typeof bindAny>[0], handlers: Record<string, Handler>, scope: CoreScope = {}): Record<string, DerivedHandler> => bindAny(m, handlers as never, scope);
 
-// PROTOCOL 2 — 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.ts';
-export type { BoundRoot, DeployReport, Head, PerformAction, PerformContext, PushOutcome } from './head.ts';
-export { observeResource, observeResources, collectObservations, foldObservations } from './observe.ts';
-export type { ObservedResource, ObserveReport, Observation } from './observe.ts';
-export { readTreeMap, readParentTreeMap, treeStamp, treeChangesSince, originEntries, appendOriginEntry, originLogPath, isUrlParent, parentPosition, positionAt, splitsBatch, assertBatchBoundary } from './log.ts';
+// ── the derived fetch ──────────────────────────────────────────────────────────────────────────
+export { createPackFetch, createVendorFetch, type LanePart, type PackFetchOptions, type PackParts, type PackScenario } from './pack-fetch.ts';
+export { createDerivedFetch } from './derived.ts';
+export type { DerivedCall, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedSurface } from './derived.ts';
+export { coreFor, crossCutting, derivedRequestScopes, vendorError } from './derived-core.ts';
+export { answerVendorErrors, RefusedWriteError } from './head.ts';
+// a GraphQL API's resolvers (`semantics/graphql.ts`), and the error one answers with the vendor's type
+export { GraphqlError, type GraphqlPart, type GraphqlResolver } from './graphql-wire.ts';
+// what `ctx.vendorFetch` throws when the other vendor cannot be reached (a vendor's call to another as its own behaviour)
+export { VendorUnreachableError } from './vendor-call.ts';
+export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER } from './request-scope.ts';
 
-// v1 left the kernel (contract "Just like Neon", 5): the names a protocol 1 pack still imports throw on
-// their first call, so the catalog stays importable and a pack out of date fails loudly.
-export * from './v1-removed.ts';
-export { referenceField, registerReferences, packReferences, resolveReferences, type ReferenceDeclaration } from './references.ts';
-// the HTTP server seam: the one place the serve path meets the runtime (Bun or Node)
-export { serveHttp, nodeBuiltin, WORLD_BOOT_PATH, type HttpServer, type ServeHttpOptions, type HttpHandler } from './serve-http.ts';
-// two runtime-neutral helpers for a pack's serve path: a file as a Response, a mirror's client bundle
-export { fileResponse, contentTypeOf } from './file-response.ts';
-export { bundleClient, filePathOf } from './client-bundle.ts';
-// 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.ts';
+// ── the serve factory ──────────────────────────────────────────────────────────────────────────
+export { serveHttp, serveStream, type HttpHandler, type HttpServer, type ServeHttpOptions } from './serve-http.ts';
+export type { TwinStream, TwinStreamConnection, TwinStreamSink } from './twin-fetch.ts';
+export { statefulTwinManifest, twinManifest } from './scenario.ts';
+export { assetContentType, packAsset } from './pack-assets.ts';
+export { bytesResponse, contentTypeOf, fileResponse } from './file-response.ts';
 
-export { readResourceBlob, readResourceBlobRange, resourceBlobSize, resourceChain } from './resource-blob.ts';
-export { mirrorShellUnder } from './mirror-shell.ts';
-
-export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withStateRemoval } from './ancestry.ts';
+// ── the kernel's deterministic helpers ─────────────────────────────────────────────────────────
+export { certificateOf, digest, digestBytes, equalSecrets, oauth1BaseString, oauth1Encode, oauth1Header, oauth1Signature, hmac, jwks, jwtDecode, jwtSign, jwtVerify, keyId, lettersFrom, md5, publicKeyOf, sha256, signWith, SIGNING_ALGORITHMS, uuidFrom, verifyWith } from './signing.ts';
+export type { HandlerCrypto, Jwk, Jwks, JwtVerdict, SigningKey } from './signing.ts';
+export { blobDigest } from './blob-store.ts';
+// compressed bytes a wire carries (a SARIF upload), over web streams
+export { gunzip, gzip } from './bytes.ts';
+// a row's own fields, where the tree's reserved ones (id, type, updatedAt) shadow the vendor's of the same name
+export { ownFields } from './log.ts';
+export type { TwinResource } from './serve.ts';
+// the people a vendor's pages sign in (a `_person` row with its password's hash)
+export { passwordHash, personOf, personWith, recordPerson, type Person } from './people.ts';
+// the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
+export { EngineDatabaseError, EngineUnavailableError, quoteIdent, worldClockSql } from './managed-database.ts';
+export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
+export type { Mail, SmtpRoute } from './smtp.ts';
+// S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")
+export * as s3 from './s3/wire.ts';
+export * as clickhouse from './clickhouse/index.ts';
+export { sampleFromSchema } from './schema-sample.ts';
+export * as openaiWire from './openai-wire.ts';
+export * as anthropicWire from './anthropic-wire.ts';
+export * as protobuf from './protobuf.ts';
+export * as grpc from './grpc-wire.ts';
+export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.ts';
+export { placeholderPng } from './placeholder-image.ts';
+export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.ts';
+export * as redis from './redis/index.ts';
+export * as git from './git/index.ts';
 
-export { captureHistory, captureParentHistory, historyChanges, historyAtInstant, historyDigest, historyEntries, historyLength, historyPrefix, inheritedHistory, originHead, publishOriginHistory, readHistoryView } from './history.ts';
-export type { HistoryView, HistoryLayout, HistoryReference, HistoryOrigin } from './history.ts';
-export { foldHistory } from './log.ts';
-export { volterHome } from './volter-home.ts';
+// ── the scenario grammar (architecture, "Behaviour") ───────────────────────────────────────────
+export { parseScenarioDocument, scenarioFaultResult, ScenarioEngine, ScenarioError } from './scenario.ts';
+export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioExtractorSpec, ScenarioFault, ScenarioFaultResult, ScenarioFeatures, ScenarioHandler, ScenarioMatcher, ScenarioMissRecord, ScenarioStatus } from './scenario.ts';

package/src/log.ts

@@ -20,11 +20,11 @@
 // and the fold skips a branch entry whose id the parent already holds. Nothing is suppressed,
 // rebound or quarantined by a bookkeeping row; `unpushed` is the branch log minus what the parent
 // holds. The parent log accepts the v1 observed-event rows too (`toEntry` reads a delta event as
-// an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a protocol 1
-// pack's own fold of the logs keeps working while it is deprecated.
+// an entry; a non-delta observation folds nothing and is kept for `listEvents`), so a World whose
+// log was written in that form still reads.
 import { captureHistory, historyChanges, historyEntryTime, historyEntries, historyLength, historyPrefix, inheritedHistory, inheritedHistoryKey, originHead, readHistoryView, replaceHistoryOrigin, saveHistoryView, validateHistoryOrigin, type HistoryLayout } from './history.ts';
 import { dirname, join } from 'node:path';
-import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock } from './ancestry.ts';
+import { canonicalStatePath, checkParent, commitParentPin, pinParent, withAncestryLock, withHistoryLock } from './ancestry.ts';
 import { resolveReferences } from './references.ts';
 import { hashFieldValue } from './hash.ts';
 import type { SubjectFields } from './hash.ts';
@@ -180,7 +180,9 @@ export function readBranchMeta(service: string, root?: string): BranchMeta | nul
 }
 
 export function writeBranchMeta(service: string, meta: BranchMeta, root?: string): void {
-  withAncestryLock(() => {
+  // Under the branch's own history lock (a capture of its parent's nests inside it, child before ancestor); only the
+  // pin and the pointer's publication take the coordinator.
+  withHistoryLock(worldPaths(service, root).dir, () => {
     if (meta.parent && (!Number.isInteger(meta.parent.position) || meta.parent.position < 0)) throw new Error('Invalid branch position');
     const path = branchMetaPath(service, root);
     const old = readBranchMeta(service, root);
@@ -195,6 +197,7 @@ export function writeBranchMeta(service: string, meta: BranchMeta, root?: string
     const previousParents = [...(old?.previousParents ?? [])];
     if (old?.parent?.directory && old.parent.generation) previousParents.push({ directory: old.parent.directory, generation: old.parent.generation });
     if (previousParents.length) meta = { ...meta, previousParents: [...new Map(previousParents.map(p => [p.directory, p])).values()] };
+    let local: { directory: string; view: string; generation?: string } | undefined;
     if (meta.parent && !isUrlParent(meta.parent.at)) {
       const directory = canonicalStatePath(worldPaths(service, meta.parent.at).dir);
       const view = meta.parent.view ?? captureHistory(service, meta.parent.at).view;
@@ -202,9 +205,8 @@ export function writeBranchMeta(service: string, meta: BranchMeta, root?: string
       if (meta.parent.viewDirectory && canonicalStatePath(viewDirectory) !== canonicalStatePath(worldPaths(service, root).dir)) throw new Error('Composed history view must belong to this branch');
       const descriptor = readHistoryView(viewDirectory, view);
       historyPrefix(descriptor, meta.parent.position);
-      const parent = meta.parent;
-      const generation = pinParent(directory, path, parent.generation);
-      meta = { ...meta, parent: { ...parent, view, at: canonicalStatePath(parent.at), directory, generation } };
+      // the parent the view was captured from: a parent removed or re-created since is refused at the pin
+      local = { directory, view, generation: meta.parent.generation ?? (viewDirectory === directory ? descriptor.owner.generation : undefined) };
     }
     if (meta.parent && isUrlParent(meta.parent.at) && !meta.parent.view) {
       const head = originHead(service, root);
@@ -214,9 +216,16 @@ export function writeBranchMeta(service: string, meta: BranchMeta, root?: string
         meta = { ...meta, parent: { ...meta.parent, view: empty.view } };
       } else throw new Error('Origin has no completed immutable history view');
     }
-    getActiveWorldStore().mkdir(dirname(path));
-    getActiveWorldStore().writeAtomic(path, `${JSON.stringify(meta, null, 2)}\n`);
-    if (meta.parent?.directory && !isUrlParent(meta.parent.at)) commitParentPin(meta.parent.directory, path);
+    withAncestryLock(() => {
+      if (local && meta.parent) {
+        const parent = meta.parent;
+        const generation = pinParent(local.directory, path, local.generation);
+        meta = { ...meta, parent: { ...parent, view: local.view, at: canonicalStatePath(parent.at), directory: local.directory, generation } };
+      }
+      getActiveWorldStore().mkdir(dirname(path));
+      getActiveWorldStore().writeAtomic(path, `${JSON.stringify(meta, null, 2)}\n`);
+      if (meta.parent?.directory && !isUrlParent(meta.parent.at)) commitParentPin(meta.parent.directory, path);
+    });
   });
 }
 
@@ -288,7 +297,7 @@ export function appendOriginEntry(entry: Entry, root?: string): { appended: bool
   const path = originLogPath(entry.service, root);
   const store = getActiveWorldStore();
   store.mkdir(dirname(path));
-  return withAncestryLock(() => store.withLock(`${path}.lock`, () => {
+  return withHistoryLock(worldPaths(entry.service, root).dir, () => store.withLock(`${path}.lock`, () => {
     if (readRows<{ id?: string }>(path).some((r) => r.id === entry.id)) return { appended: false };
     store.append(path, `${JSON.stringify(entry)}\n`);
     return { appended: true };
@@ -433,7 +442,7 @@ export function readTree(service: string, root?: string, opts: { until?: string;
 /** The upstream view for observation diffing, without this root's local overlay. Inherited
  *  history keeps its own layout: an ancestor's local writes are part of our pinned base. */
 export function readParentTreeMap(service: string, root?: string): Tree {
-  return withAncestryLock(() => {
+  return withHistoryLock(worldPaths(service, root).dir, () => {
     const inherited = inheritedHistory(service, root);
     const own = ownParentEntries(service, root);
     return foldHistory([...(inherited ? historyEntries(inherited) : []), ...own], {
@@ -505,11 +514,11 @@ function currentTree(service: string, root?: string): { tree: Tree; memo?: TreeM
   let memos = treeMemos.get(store);
   if (!memos) { memos = new Map(); treeMemos.set(store, memos); }
   const slot = `${service}\u0000${root ?? ''}`;
-  // A hit needs no coordinator: a memo is only ever stored from a fold made under it, and while the
+  // A hit needs no lock: a memo is only ever stored from a fold made under the history lock, and while the
   // facts still match that fold, nothing was written since. A writer mid-batch has moved them.
   const unlocked = memos.get(slot);
   if (unlocked && unlocked.parentKey === parentKeyOf(service, root) && unlocked.branchKey === statKey(branchLogPath(service, root))) return { tree: unlocked.tree, memo: unlocked };
-  return withAncestryLock(() => {
+  return withHistoryLock(worldPaths(service, root).dir, () => {
     const parentKey = parentKeyOf(service, root); const branchKey = statKey(branchLogPath(service, root));
     const held = memos.get(slot);
     if (held && held.parentKey === parentKey && held.branchKey === branchKey) return { tree: held.tree, memo: held };
@@ -571,7 +580,7 @@ export function treeChangesSince(service: string, root: string | undefined, sinc
 }
 
 function readTreeMapFull(service: string, root?: string, opts: { until?: string; at?: number; view?: string } = {}): Tree {
-  return withAncestryLock(() => {
+  return withHistoryLock(worldPaths(service, root).dir, () => {
   if (opts.at !== undefined || opts.view !== undefined) {
     const view = opts.view ? readHistoryView(worldPaths(service, root).dir, opts.view) : captureHistory(service, root).descriptor;
     const at = opts.at ?? historyLength(view.layout);
@@ -616,7 +625,7 @@ function readTreeMapFull(service: string, root?: string, opts: { until?: string;
   });
 }
 export function cutCheckpoint(service: string, root?: string): void {
-  return withAncestryLock(() => {
+  return withHistoryLock(worldPaths(service, root).dir, () => {
   dropCheckpoint(service, root);
   const subjects = [...readTreeMap(service, root).values()];
   const inherited = inheritedHistory(service, root); const own = ownParentEntries(service, root);
@@ -695,7 +704,7 @@ export function appendParentEntry(entry: Entry, root?: string): { appended: bool
   const path = parentLogPath(entry.service, root);
   const store = getActiveWorldStore();
   store.mkdir(dirname(path));
-  return withAncestryLock(() => store.withLock(`${path}.lock`, () => {
+  return withHistoryLock(worldPaths(entry.service, root).dir, () => store.withLock(`${path}.lock`, () => {
     let indexes = parentIdIndex.get(store);
     if (!indexes) { indexes = new Map(); parentIdIndex.set(store, indexes); }
     let index = indexes.get(path);
@@ -726,7 +735,7 @@ export function wholeLog(service: string, root?: string): Entry[] {
  * result, never a stop. An unbranched world (no pointer) has nothing to rebase.
  */
 export function rebaseBranch(service: string, root?: string, opts: { origin?: boolean } = {}): { moved: boolean; from: number; to: number; conflicts: Array<{ entryId: string; subject: { type: string; id: string }; field: string; op: string; expected?: unknown; actual?: unknown }> } {
-  return withAncestryLock(() => {
+  return withHistoryLock(worldPaths(service, root).dir, () => {
   const meta = readBranchMeta(service, root);
   if (!meta?.parent) return { moved: false, from: 0, to: 0, conflicts: [] };
   if (opts.origin && !meta.origin) throw new Error('This local fork has no tracked origin; clone the origin before branching');