feat: implement durable output knowledge and overlay architecture

.github/workflows/mutation-tests.yml

@@ -6,7 +6,7 @@ on:
   workflow_dispatch:
     inputs:
       target:
-        description: Optional exact governed target ID; blank runs all 25
+        description: Optional exact governed target ID; blank runs all governed targets
         required: false
         type: string
 
@@ -78,7 +78,9 @@ jobs:
     name: Mutation / ${{ matrix.target }}
     needs: prepare
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    # Match the PR workflow: complete governed targets (including the durable
+    # live lookup target) legitimately exceed 20 minutes without omitting mutants.
+    timeout-minutes: 45
     permissions:
       contents: read
     strategy:

docs/_schemas/page.schema.json

@@ -6,8 +6,26 @@
   "properties": {
     "id": { "type": "string", "description": "Stable slug, never changes" },
     "title": { "type": "string" },
-    "kind": { "type": "string", "enum": ["package", "infra", "spec", "guide", "conformance", "reference", "meta"] },
-    "domain": { "type": ["string", "null"], "enum": ["sdk", "wallet", "network", "content", "overlays", "messaging", "middleware", "helpers", "infra", null] },
+    "kind": {
+      "type": "string",
+      "enum": ["package", "infra", "spec", "guide", "conformance", "reference", "meta"]
+    },
+    "domain": {
+      "type": ["string", "null"],
+      "enum": [
+        "application",
+        "sdk",
+        "wallet",
+        "network",
+        "content",
+        "overlays",
+        "messaging",
+        "middleware",
+        "helpers",
+        "infra",
+        null
+      ]
+    },
     "version": { "type": "string" },
     "source_repo": { "type": "string" },
     "source_commit": { "type": "string" },

docs/about/versioning.md

@@ -107,6 +107,15 @@ disagreement, missing API pages, and stale generated output. After an authorized
 publication, the release-sync change advances the recorded published baseline;
 merging a candidate record never publishes it.
 
+A new, unpublished package uses `publishedVersion: null` and
+`releaseType: initial`, with an exact source version and substantive API and
+migration documentation. Registry verification must confirm an explicit npm
+not-found response; authentication, network and server failures are not proof of
+absence. If the package already exists, reconcile its actual published baseline
+before the release gate can pass. Never invent a `0.0.0` publication to register a
+new package. An initial candidate still requires the protected publication workflow
+and explicit publication authorization.
+
 Do not promise a GitHub Release, npm dist-tag, changelog format, cadence, or
 support window that the workflow does not actually enforce.
 

docs/guides/compiled-package-examples.md

@@ -3,8 +3,8 @@ id: compiled-package-examples
 title: 'Compiled Package Boundary Examples'
 kind: guide
 version: '1.0.0'
-last_updated: '2026-09-08'
-last_verified: '2026-09-08'
+last_updated: '2026-09-30'
+last_verified: '2026-09-30'
 review_cadence_days: 30
 status: stable
 tags: [guide, typescript, packages, consumers, examples]
@@ -59,7 +59,7 @@ void exampleDidDocument
 void acceptDidLookup
 ```
 
-The compiler combines the *selected* fences into one consumer module, and on a
+The compiler combines the _selected_ fences into one consumer module, and on a
 pull request it selects only the fences whose import closure reaches a changed
 package. So an earlier fence's imports are available only when that fence
 happened to be selected too, and a fence that leans on one is broken by any
@@ -187,3 +187,117 @@ pnpm docs:examples
 The command requires built package outputs and network access only when the
 clean temporary consumer's external dependencies are not already present in
 the pnpm store. It never publishes or deploys an artifact.
+
+## Durable lookup provider
+
+This unpublished candidate composes the portable provider, Node storage and
+optional dual-format HTTP adapter. Creation and reopening are deliberately
+separate: callers retain the epoch, signed manifest, immutable binding and storage
+configuration as described in the [provider guide](durable-live-lookup.md).
+
+```ts compile
+// example-id: durable-lookup-provider
+import {
+  LookupProviderService as ExampleLookupProvider,
+  LookupSessionCodec as ExampleLookupCodec,
+  type LookupProviderOptions as ExampleLookupOptions
+} from '@bsv/output-knowledge/lookup'
+import {
+  SQLiteLookupIndex as ExampleLookupIndex,
+  SQLiteLookupSessions as ExampleLookupSessions
+} from '@bsv/output-knowledge/lookup/sqlite'
+import {
+  createOutputLookupRouter as exampleLookupRouter,
+  type OutputLookupRouteOptions as ExampleLookupRoutes
+} from '@bsv/overlay-express/output-lookup'
+import type ExampleLookupHost from '@bsv/overlay-express'
+
+function reopenExampleLookupStorage(path: string, codec: ExampleLookupCodec, now: () => string) {
+  const index = ExampleLookupIndex.open(path, 'records', { service: 'records' })
+  const sessions = ExampleLookupSessions.open(index, codec, now)
+  return { index, sessions }
+}
+
+function composeExampleLookup(
+  options: ExampleLookupOptions,
+  routes: Omit<ExampleLookupRoutes, 'companion'>
+) {
+  const companion = new ExampleLookupProvider(options)
+  return { companion, router: exampleLookupRouter({ ...routes, companion }) }
+}
+
+function configureExampleLookupHost(
+  host: ExampleLookupHost,
+  options: ExampleLookupOptions,
+  routes: Omit<ExampleLookupRoutes, 'companion' | 'authenticate' | 'handleHandshake'>
+) {
+  const companion = new ExampleLookupProvider(options)
+  host.configureOutputLookup({ ...routes, companion })
+  return companion
+}
+
+void reopenExampleLookupStorage
+void composeExampleLookup
+void configureExampleLookupHost
+```
+
+## Revenue listing recognition
+
+The executable is supplied from a pinned local artifact. This example checks
+the portable exact-script API; lineage, currentness and spending are separate.
+
+```typescript compile
+// example-id: revenue-listing-codec
+import {
+  RevenueListing,
+  parseRevenueListingDescriptor,
+  revenueListingId,
+  encodeRevenueListingState,
+  decodeRevenueListingState
+} from '@bsv/sdk/script/templates/RevenueListing'
+
+export function recognizeListing(
+  program: Uint8Array,
+  script: Uint8Array,
+  descriptorInput: unknown
+) {
+  const family = new RevenueListing(program)
+  const descriptor = parseRevenueListingDescriptor(descriptorInput)
+  const state = family.decode(script, descriptor)
+  const stateBytes = encodeRevenueListingState(state)
+  return {
+    listingId: revenueListingId(descriptor),
+    state: decodeRevenueListingState(stateBytes),
+    script: family.lock(descriptor, state).toBinary()
+  }
+}
+```
+
+## Revenue listing funded signing boundary
+
+```typescript compile
+// example-id: revenue-listing-spend
+import { RevenueListing as ListingCodec } from '@bsv/sdk/script/templates/RevenueListing'
+import {
+  RevenueListingSpend,
+  type RevenueListingSigningRequest
+} from '@bsv/sdk/script/templates/RevenueListingSpend'
+import type { Transaction as FundedTransaction } from '@bsv/sdk'
+
+export function bindListingFunding(
+  codec: ListingCodec,
+  descriptor: unknown,
+  previous: unknown,
+  action: unknown,
+  funded: FundedTransaction
+) {
+  const spend = new RevenueListingSpend(codec, descriptor, previous, action)
+  const prepared = spend.prepare(funded)
+  const requests: RevenueListingSigningRequest[] = prepared.signingRequests()
+  return { plan: spend.plan(), requests, prepared }
+}
+```
+
+The caller establishes lineage first and obtains transaction signatures from an
+explicit authority. Final layout validation remains separate from full transaction
+and Script verification, private fulfillment and wallet operation recovery.