@bsv/output-knowledge
v0.1.1
Published
Durable BRC-192 application output knowledge and interchangeable source adapters
Readme
Application output knowledge
@bsv/output-knowledge implements the opt-in application state ports in the
proposed BRC-192–199 packet. It sits above @bsv/sdk: sources report observations,
the runtime verifies evidence and reconciles spends, and an application projector
interprets the resulting state. Signing, payments and wallet actions remain
explicit application workflows.
This implementation branch is in progress. The Bitcoin knowledge core, durable
receipt journals, progressive and live lookup client/provider, proposal host
lifecycle, revenue-listing lineage/authority and root-advertisement coordination
components are implemented. Optional SQLite persistence and authenticated Overlay
Express adapters exercise concrete service paths. Optional client proposal
acceptance verifies exact signed envelopes and retains local receipt decisions.
Optional current-channel queries, authenticated source grammar and independent
provider/generation projection are available. The optional compound SQLite
proposal/current-feed/session owner is implemented with atomic visibility fences,
future-event reservations and bounded expiry. Concrete native examples compose private publication/acquisition, historical
licensed-purchase support and independent root serving with real Engine/Mongo
and authenticated HTTP. Current optional-profile native wallet, alias, buyer/seller and authenticated
HTTP layers are assembled and exercised by complete current-profile Linux
reference compositions. Final published-source and mutation-campaign qualification
are separate acceptance gates recorded in the checkpoint inventory;
downstream application adoption follows the second review checkpoint.
The internal native private-publication foundation
now binds protected material, permanent request fences and ordered durable phases.
The optional @bsv/output-knowledge/private/node entry now composes verified
publication, actual retained Engine admission, protected lookup binding, current
publisher disclosure and bounded restart recovery. Its
installation guide separates
publication from the separately composed paid lookup and purchase/POTATOES owners.
The package version does not indicate a published or production-qualified release.
Private ledger, alias and purchase codecs capture their fixed field names once.
The native protected-payload envelope also reuses a frozen six-name field list;
its required-field loop still inspects all six fresh owned values on every open.
The native payload codec and ledger envelope-metadata reader explicitly select
the SDK string-record parser; plaintext canonical inspection remains unchanged.
Every input still receives complete ownership, prototype, symbol, descriptor,
required/unknown-field and scalar checks. Encrypted records, revision, clock,
authority and custody checks remain fresh; no record, secret or validation verdict
is retained by a grammar. Explicit historical/current profile selection is unchanged.
See the implementation record
for exact component evidence and outstanding work.
Start with durable receipt storage, protocol work and projection, and source adapters. Optional service components are described in the live provider, proposal policies and lifecycle, root coordination, and revenue-listing history.
Revenue listing history
Current BRC PR295 installations select RevenueListingProfileLineageVerifier,
RevenueListingProfilePurchaseVerifier and parseRevenueListingProfileLineagePackage
from @bsv/output-knowledge/revenue-listing. They bind the immutable descriptor
and signed reserve-stage genesis, require child-link activation, check complete
Bitcoin evidence and execute every actual input Script. Purchase verification
returns the full purchase commitment only after exact original-request association
and successor history succeed. These portable components leave asset authority,
currentness, native wallet/alias custody and private release to installed owners.
See the current-profile guide.
The final merged profile uses ordinary Bitcoin finality. Script-valid immature
histories return pending-finality; they cannot consume projected state or
authorize admission/release. The optional native pending-candidate and journaled
rejection-recovery companions retain original financial identity, deadlines and
all earlier decisions. See the
purchase custody guide
for explicit installation and independent policy/admission responsibilities.
These final-revision additions are undergoing qualification.
The same optional entry supplies RevenueListingProfileAuthority. Its asynchronous
creation preflight checks an installed BRC-100 wallet's actual identity, own fixed
child and protected signing before funding. Split and early-retirement signatures
use that child; genesis packets use a distinct BRC-77 message-signing child.
Explicit originator and synchronous authorization fences surround every wallet
await. No scalar is exported and no funds are allocated. Full economic approval,
native wallet recovery and chain authority remain separate responsibilities. See
the protected signing guide.
Historical compatible interfaces
The older interfaces below preserve the superseded pre-adoption family, including its merge and mutable schedule semantics. They are not the current BRC-197 profile.
The optional @bsv/output-knowledge/revenue-listing entry exports RevenueListingLineageVerifier, its bounded package parser, limits and types. It checks authorized genesis, both paths of every merge, immutable-view Bitcoin evidence and every exact-family covenant invocation, including mined transactions. It keeps missing history, invalid history, cancellation and local limits distinct. It does not establish asset authority, current unspentness, acquisition association or private delivery. See the history guide for composition, funded-copy merge semantics and recovery. Existing root exports remain unchanged.
That entry also exports RevenueListingAuthority and
createSoftwareRevenueListingAuthority. They bind exact transaction signatures
and seller-authorized genesis to one dedicated authority identity, with owned
requests across asynchronous signing ports. Funding remains in the wallet;
authority keys are explicitly provisioned separately. The software adapter is
a reference for dedicated-key custody, and an installed port can use another
signing implementation. Neither signs during ingestion or proves permission,
lineage, currentness or fulfillment. See the
authority guide.
The same optional entry now supplies RevenueListingPurchaseVerifier for exact
BRC-196 prepared-request association. It authenticates the frozen terms against the
original request and selected seller, checks the actual predecessor, successor
increment/state and recipient-bound receipt, then verifies the complete successor
history and every covenant. The result does not establish currentness, asset
permission, admission, private release or usability. See the history guide's
prepared-purchase section before composing it with a wallet or host.
Its optional bounded local refusal reason helps distinguish preparation and ABI
failures while preserving status/dependencies; it is not a wire or global verdict.
Private purchase custody and buyer
The private/node entry exports PrivatePurchaseContracts, PrivatePurchaseCoordinator,
PrivatePurchaseAccess, PrivatePurchaseDisclosure, purchase progress functions
SQLitePrivatePurchaseStore and SQLitePrivatePurchaseEvidence. They retain the exact preparation,
one native admission intent and first signed result, with reserved completion
capacity and current recipient checks at enqueue. They do not themselves verify
a purchase, perform topic admission, satisfy a release policy or issue a licence.
See purchase alias custody and independent currentness for the explicit new native owner, per-alias admission, optional authenticated currentAlias response and free buyer assessment. Historical owners remain separate.
See original purchase custody
before installing the separately composed host and domain owners. The complete
cumulative-proof profile installs the evidence owner before preparation, verifies
incoming and combined proof independently and preserves original financial and
delivered-result bytes. Omitted-companion behavior remains available. New native purchase installations
may explicitly select the native-observation-v1 local clock profile; it derives
bounded progress writes from their authorizing transaction observation. Existing
constructors and commits retain their default behavior. Restore each obligation
with its original authenticated profile; changing an installation is not migration
of existing custody. The explicitly selected SQLitePrivatePurchaseCommitmentStore
uses sealed version-two state and retains an independently verified full purchase
commitment through native reservation, admission and signed delivery. Historical
version-one custody and public declarations remain unchanged. This companion
still pins an exact submitted txid. The explicitly selected native alias owner retains complete raw candidates,
independent admission jobs and one full economic commitment on the original
protected ledger. Its coordinator progresses every unresolved candidate job,
selects only independently verified current-chain aliases, and commits the first
private release once. The optional asynchronous HTTP disclosure path checks
native custody and selected-chain guards in the same physical enqueue transaction.
Later alias reports preserve the exact historical signed release. A separate
buyer companion independently verifies the reported candidate and its own selected
chain through free recovery; it neither repays nor replaces the original License.
The private/node and portable private/purchase-buyer entries expose the
respective explicit companions. These components are under qualification; their
source and interface descriptions are not full runtime or Checkpoint 2 evidence.
The alias coordinator retains fixed installed-method identities while re-reading
each owner property on every currentness visit. Method replacement and getter
observation retain their original refusal and ordering behavior; no authority
verdict is cached.
BRC-197's immutable collector is one concrete exemplar of this architecture.
The purchase guide labels the earlier native six-route and authenticated
Engine/Mongo/LCH demonstrations as historical-profile evidence.
The optional portable private/purchase-buyer entry exports PrivatePurchaseBuyer,
privatePurchaseBuyerBinding and PRIVATE_PURCHASE_BUYER_INITIAL. The separate
private/purchase-wallet entry exports the current
WalletToolboxProfilePurchasePayment and historical WalletToolboxPurchasePayment
without authenticated HTTP orchestration. The current adapter explicitly binds
both frozen programs and a separate format-two plan, verifies reserve-stage
genesis and activation ancestry, and requires an active listing and same verified
chain view below height expiry before new native funding or signing. Finalized
original recovery remains read-only. Both adapters share the full native
intent/funding/layout/recovery pipeline; historical options and format-one plans
remain compatible. Fixed-child payout remittance and native alias reconciliation
remain separate integrations. Six
protected object reservations precede seller
preparation and wallet work. The small durable control journal contains no large
lineage, BEEF or delivered secret. recover reads the original wallet intent and
seller obligation; advance explicitly permits new work under the original
cutoff. The concrete native payment adapter independently verifies the complete
listing history before allocation/signing and refuses insufficient submission
capacity before signing. Delivered custody, independent validation and current
usability remain separate. Reopen the original protected owners and native action
store instead of creating another operation after a missing reply. The purchase
custody guide describes installation, wallet layout and shutdown requirements.
Domains with a same-view financial fence may additionally install
validation.fundingPreflight for signed terms. Its owned synchronous guard is
retained across awaits and checked through the native wallet effect callback.
Unsigned discovery, omitted-hook behavior and finalized read-only recovery retain
their existing paths. Bind the companion in the validation installation ID;
it does not supply alias ownership or replace independent delivered verification.
The buyer may explicitly select candidateProfile: "full-purchase-commitment-v1"
and an independently installed validation.candidateBinding verifier. That
installation reserves a seventh protected object before preparation or funding,
retains the verified full commitment beside the exact original funded candidate,
and authenticates submit/recover responses under that identity. A lost identity
write reply recovers the retained object; it cannot create another financial
operation. Historical responses and independently validated playback do not
become new preparations. Response authentication does not establish Bitcoin
alias equivalence, selected-chain currentness or License/key validity; complete
original and released transaction verification remains mandatory. This companion
does not complete the current-profile native wallet or host alias journal.
Durable progressive and live provider
The optional @bsv/output-knowledge/lookup entry composes durable snapshot/live
sessions, installed query policies, current authorization and bounded reads.
@bsv/output-knowledge/lookup/sqlite supplies the Node SQLite index and session
adapters. They preserve original Open identity, fixed history promises and whole
change groups; notification hints reduce latency while polling recovers missed
changes from other processes. The browser root remains unchanged. The portable LookupResponseDisclosure
companion optionally reauthorizes an authenticated response after signing and
uses the session adapter's shared native-enqueue gate. Supply the same current
policy and durable guards, plus an explicit control-response policy; physical
work remains bounded through cancellation. No existing wire or stored format
changes, and existing serialization remains available.
See the provider guide for creation, restart, projection, disclosure guards, HTTP mounting and retention. The optional Overlay Express adapter requires SDK 3.3.0 or SDK 4.0 and a signed matching capability. This increment does not complete topic admission, payment, private acquisition or the full BRC-192–199 reference application.
Durable root advertisement decisions
@bsv/output-knowledge/root-eviction supplies portable journal types and
RootEvictionContracts for exact signed capability selection and original-contract
recovery. The helper enforces the stricter advertised/profile limits; a coordinator
must still retain its record atomically with request intake. The separate @bsv/output-knowledge/root-eviction/serving entry supplies
RootAdvertisementServing, positive inventory derivation and
RootLookupServingDisclosure for native physical enqueue. Its independently
measured portable graph contains transaction parsing; the original small root
coordination entry preserves its existing browser limits.
The separate
@bsv/output-knowledge/root-eviction/evidence entry supplies SDKRootEvictionEvidence
for current SHIP/SLAP authentication, owner attribution and exact consuming
transactions against an installed immutable chain view. Verified facts remain
separate from requester access, restoration rights and currentness.
The Node entry @bsv/output-knowledge/root-eviction/sqlite supplies
SQLiteRootEvictionStore: bounded immutable request fences, independent suppression
bases, exact restoration, local currentness assessments, durable index intents and a
shared final synchronous response-queue gate. Explicit creation and recovery preserve
the root identity, chain and sealed capacities. This component leaves installed
requester/evidence authority, broader bans, scheduling and actual HTTP/index adapters
to the service; it does not enable a discovery endpoint by itself. See
root coordination for API
contracts, limits, crash recovery and the complete independent-root serving
demonstration.
The portable entry also supplies RootEvictionService for bounded raw-text intake
and authorized status signing. It preserves the original capability on retry,
retains before signing and verifies the exact observed result returned by the
installed signer. Returned bytes carry their observation revision for the separate
native final-enqueue guard. The component installs no automatic peer policy or
HTTP route. Existing parsed-packet journal calls and lookup work behavior remain
unchanged; cancellation retains physical signing capacity until work settles.
Root coordination, recovery and local rules
The optional root journal also implements RootEvictionCheckedStorage: checked
retention, evaluation, assessment and result reads sample the trusted clock and
recheck access, installed policy and external context inside the shared commit
gate. Their observations include the exact current head for later signing and
final enqueue. Existing deterministic methods and the local stored format remain
unchanged. See the root coordination guide for callback and service obligations.
The optional RootEvictionCoordinatedStorage companion atomically retains each
request with its original signed capability selection and reserves its narrower
advertised result limit. Explicit coordination configuration uses the sealed
root-eviction/2 format. Existing default format1 behavior remains unchanged;
upgradeCoordination is an explicit transactional migration that preserves history
and fences older open connections. Missing legacy selections are never filled
from current discovery. See the root coordination guide for storage budgets,
recovery, migration and the explicit host installation obligations.
The Node root entry also exports SQLiteRootEvictionMaintenance, an optional
trusted local recovery companion. It opens the same existing sealed database,
scans bounded pending digests and expires work using a clock and maintenance
authority checked inside the shared gate. It preserves completed actions and
original selections, requires no requester reconnection, and never grants peer
authority or changes eligibility. The host still installs a bounded startup and
periodic scheduling loop; see the root guide and compiled example. No existing
journal API or storage-format migration is required for this companion.
RootEvictionRecoveryStorage is a further optional worker companion implemented
by the SQLite journal. recoverCoordinated resolves a pending digest to its original
saved signed capability and current result under a checked local-worker guard,
without discovery or requester impersonation. It cannot adopt legacy operations
with missing selections or authorize new decisions. Independent maintenance expiry
continues even when chain/context-dependent recovery cannot proceed.
The optional root entry also exports RootEvictionScheduler. Explicit startup and
periodic bounded scans recover durable work after lost wake hints or process restart.
Manual/advisory mode is the default; automatic evaluation requires an installed
versioned policy and current guarded authority. Separate expiry and evaluation scans
preserve expiry progress while physical evidence work is stalled. Await stop()
before closing caller-owned storage; logical cancellation alone does not drain a
non-cooperating dependency. See the root coordination guide for bounds and lifecycle.
SQLiteRootEvictionLocalRules in the Node root entry adds opt-in format3 local-rule
history and complete assessment coverage, independently from peer suppression
requests. Every active rule reserves lift capacity. Unknown rule results remain
unresolved, and lifting a rule cannot grant membership until complete reassessment
and projection. Formats1/2 retain their behavior; use the explicit format2-to3
upgradeLocalRules migration and exact sealed configuration. Trusted operator
attribution, installed matchers and verified currentness remain application ports.
See the root coordination guide
for migration, bounds, retries and serving obligations.
The evidence entry also exports SDKRootAdvertisementEvidence for direct local
admission and reassessment. It verifies the exact SHIP/SLAP output, script digest,
advertiser authentication and Bitcoin evidence in the installed immutable chain
view without a peer-request envelope. Its owned facts do not establish unspentness,
local-policy approval or permission to serve. SDKRootEvictionEvidence retains
its existing request-signature and withdrawal/consumption checks using the same
underlying verifier.
WalletOutputSource consumes ordinary BRC-100 output-count pages. BRC-112
balance queries return numeric summaries, not output counts; the adapter rejects
ordinary and module balance queries before calling the wallet, emitting
observations or reporting an empty-scan completion. Use the wallet module balance API separately; balances must not be
coerced into pagination counts or interpreted as output withdrawal evidence.
Getting started
This package is an unpublished implementation candidate requiring the coordinated
SDK 3.3.0 candidate, a compatible later 3.x release, or SDK 4.0. SDK 3.0–3.2 do not contain
the output-protocol APIs imported by this package. From this TS Stack workspace, run pnpm --filter @bsv/sdk build:ts, then
pnpm --filter @bsv/output-knowledge build. Workspace consumers declare
@bsv/output-knowledge with workspace:^; external installation waits for the
separately authorized package publication. The composition example below uses
existing application-owned storage, chain verification and source configuration.
Durable receipt journal
MemoryJournal is explicitly volatile. IndexedDBJournal uses a strict
read/write transaction for receipt bytes, idempotency identity and both revisions.
SQLiteJournal, imported from @bsv/output-knowledge/sqlite, uses SQLite WAL with
synchronous=FULL. The Node-only entry is separate from browser imports. Node
22.13 or newer is required for that adapter; Node 24 is used for development.
Revisions use exact decimal U64 strings. SQLite and IndexedDB indexes store
fixed-width hexadecimal positions so lexical ordering covers the entire unsigned
range. A received batch advances received; it does not advance accepted until
its whole source group passes the runtime's acceptance barrier. The low-level
journal stores already validated local mutations; it is not itself a transaction
verifier or domain policy.
Every append compares the expected received revision. Identical mutation replay
returns its saved result before checking the expected revision. Reusing a mutation
key with different bytes returns equivocation without changing the prior record.
An uncertain append is recovered by its original key. appendJournalWithRecovery
returns a saved committed result if present; absence rethrows the original failure
so the caller can decide whether to retry that exact operation. It never assumes
rollback and never creates a replacement payment or action.
Adapters bound entry bytes, total retained bytes and entry count. Reaching a bound returns an explicit limit; it does not silently evict pending work or reset revision ordering. Browser storage is subject to browser quota and eviction: applications must request persistence where available and preserve the expected generation and checkpoint so lost storage triggers a reset. SQLite files newly created by this adapter are owner-only; the application must also protect the parent directory, backups and its existing database permissions. Use SQLite's online backup facility to include committed WAL state.
The journal can atomically retain locally generated verification replay material alongside a mutation. That material has a versioned storage frame and integrity digest, shares the entry and retention budgets, and survives the same commit as the body, key, revisions and source checkpoint. It is not a provider attestation or a new wire field. The BRC mutation body and its idempotency key remain unchanged; a replay returns the original saved material. Older body-only journal records remain readable. The protocol reducer owns validation of its local frame profile. The default Bitcoin reducer requires a policy frame on every context transition; an older body-only context requires an explicit reset instead of silently adopting the current spend policy.
Local workflow control state
@bsv/output-knowledge/operations exports OperationStateStore,
MemoryOperationStateStore and IndexedDBOperationStateStore. The separate
@bsv/output-knowledge/operations/sqlite entry exports
SQLiteOperationStateStore. These bounded local cells retain workflow control
state separately from Bitcoin receipt journals. A cell does not verify a
transaction, implement a lookup session, authorize a payment or validate an
application's state transitions. Its caller implements those rules.
Each namespace binds an immutable configuration and capacity to one mutable JSON
object with an exact decimal U64 revision. The configuration getter returns owned
binding and limit copies; a workflow adapter must check them when accepting an
injected store. Memory is volatile. SQLite uses a
WAL/FULL transaction; IndexedDB uses a strict read/write transaction. A write
compares the previous revision and replaces the entire object atomically. An
exact retry against the immediately following identical state returns replayed.
Any later revision returns conflict, even if the same value appears again.
An uncertain write is not proof of rollback: reread the saved workflow identity
and reconcile it before deciding the next operation. Never blindly repeat an
external effect because a local acknowledgement was lost.
import { SQLiteOperationStateStore } from '@bsv/output-knowledge/operations/sqlite'
// Application-owned, newly allocated identity and immutable binding.
const control = SQLiteOperationStateStore.create(path, workflowId, binding, {
phase: 'reserved',
job: '0'
})
const before = await control.read()
const result = await control.compareAndSwap(before.revision, {
phase: 'response-pending',
job: '0',
response: validatedResponse
})
// A conflict requires a reread and workflow-specific reconciliation.
// Only a successful durable commit can authorize the corresponding next step.
await control.close()
const recovered = SQLiteOperationStateStore.open(path, workflowId, binding)Use create only for a new workflow identity or an exact initialization retry.
Retrying initialization preserves the current state and rejects changed initial
values. open recovers an existing namespace; missing storage never creates a
replacement operation. Changed configuration or capacity fails. Separate workflows
use separate namespaces, whose count/lifecycle the application must bound. There
is no automatic deletion, compaction or remote write endpoint. Configuration and
state are independently bounded at 2 MiB and 4 MiB by default; callers may narrow
these limits. State values must be bounded JSON objects, and reads/writes own their
data. Checksums detect inconsistent persisted bytes and revisions; they do not
authenticate a malicious local writer or prove that an old backup is current.
Use a dedicated database name for IndexedDBOperationStateStore.create/open.
Browser eviction, rollback and private browsing can remove data. Retain an
independent application recovery expectation, request browser persistence where
available, and treat a missing expected namespace as a reset. Protect SQLite's
parent directory and backups; new files are owner-only. Restore a coherent backup
of the workflow cell and its associated receipt journal, including their WALs,
and enforce the workflow's cross-store recovery rules. Receipt and cursor must
still commit together in the receipt journal before a live cursor is used. This
storage primitive alone does not satisfy the complete BRC-193 client contract.
Protocol work and application projection
KnowledgeStore owns compare-and-swap, bounded coherent replay, mutation recovery
and accepted-revision watches. Its trusted KnowledgeReducer checks protocol
transitions and deterministic Bitcoin reconciliation. The optional prepare port
can validate new cryptographic work and return the local replay material that must
be saved atomically. reduce reconstructs previously committed state. These ports
are local authority boundaries and must never be exposed as generic remote write
endpoints. inspect provides bounded, lossless local journal replay for a protocol
worker; it contains private application data and is not a public diagnostics API.
BitcoinKnowledge supplies the default KnowledgeReducer and
OutputKnowledgeWorker. Bind one instance to one journal namespace, partition and
explicit nonFinal policy, then pass it to both KnowledgeStore and
OutputKnowledge. It validates assertions against actual transaction inputs,
retains proof checks atomically, and reconstructs committed decisions without
network access. Source groups publish only after all their required evidence
qualifies. The default produces local unknown/spent/conflicted/stale assessments. An explicit
sourceCurrentness policy can additionally retain scoped provider reports; no
source receives implicit authority to assert unspentness.
import {
BitcoinKnowledge,
KnowledgeStore,
OutputKnowledge,
SDKEvidenceVerifier
} from '@bsv/output-knowledge'
// journal is MemoryJournal, IndexedDBJournal or the separate SQLiteJournal adapter.
// partition and headerViews are trusted application configuration, never source input.
const worker = new BitcoinKnowledge({
journalId: journal.namespace,
partition,
nonFinal: false,
verifier: new SDKEvidenceVerifier(headerViews)
})
const store = new KnowledgeStore(journal, worker, { partition })
const runtime = new OutputKnowledge({ store, worker, projector })
await runtime.setContext(verificationContext)
const subscription = runtime.attach(source, sourceRequest)
await subscription.done
await runtime.flush()headerViews must resolve immutable, validated configured-chain views. A chain
context identity cannot be reused with different contents. The worker stores the
original context, receipt frontier and exact proof references; a historical recheck
uses a fresh local work deadline without extending any external authorization or
currentness deadline. The nonFinal setting is sealed in local replay metadata;
changing it requires an explicit new journal generation instead of reinterpreting
old replacements. The current reference implementation uses a new journal namespace
for that reset and retains the old journal for audit/recovery.
Complete-but-unfinished evidence blocks its input conflict/dependency component.
Other components can progress. Readiness uses the earliest valid complete support
set, including indivisible source-group prerequisites, and not worker completion.
A later context's missing evidence does not erase the earlier replacement journal.
Verification and source-ingress commits use bounded contention retries. Exhausted
verification, replay, retention or contention budgets remain explicit retryable
limits; applications can schedule another flush when resources are available.
BitcoinKnowledge.advance propagates an installed clock failure and releases its
single-pass guard. After the clock recovers, retry the same worker and store; a
failed initial clock read leaves the journal unchanged.
OutputKnowledge coordinates sources, a protocol worker and an optional domain
projector. It advances a source iterator only after receipt commits, bounds pending
ingress, and keeps source generations separate from the partition's verification
generation. A slow source cannot retain the ingress commit queue indefinitely:
protocol operations have explicit deadlines and capacity. Source adapters must
honour their cancellation signals and transport deadlines.
Domain projection has no wallet action port. The runtime snapshots its input, validates its output, and checks the active partition, generation, context and both revisions immediately before publication. Failed, cancelled and superseded projection work cannot become current. Projection records are currently materialized in memory and rebuilt from the durable journal; application projectors must be pure or supply their own explicitly authorized, durable idempotent effects. Runtime events are a bounded local notification feed, not a BRC-193 replay transport.
SDKEvidenceVerifier uses the SDK's existing Script and SPV verifier with an
application-supplied immutable validated header view. It verifies the asserted
transaction in aggregate BEEF, treats missing bytes as unresolved, and distinguishes
backend unavailability from cryptographic invalidity. EvidencePool can assemble
bounded alternative proofs from separately received dependencies. Each alternative
retains all supplying receipts and whole-group prerequisites and still requires
verification. A txid-only entry never supplies a raw-transaction arrival position.
SourceMembershipLedger retains provider scopes independently, stages replacement
snapshots, fences retired generations, and applies live membership in source order.
reconcileOutputSpends applies actual transaction input edges, historical non-final
replacement rules and current-view dependency closure. Membership is not a spend
edge, and a newly reported output cannot undo a known spend.
Publication deadlines for other state
setContext closes publication before its asynchronous commit starts. If several
context changes overlap, publication stays closed until all of them settle. A
worker or projector already in flight cannot republish an earlier context during
that interval. Await setContext before treating the requested context as
committed; flush does not finish a pending context write. A failed context
transition preserves the journal's previous committed state and still returns
its original error to the caller.
The optional OutputKnowledgeWorker.nextInvalidation(input) method returns the
earliest exclusive U64 epoch-second deadline that applies to an accepted input.
It is a pure installed local policy: it may examine the owned snapshot supplied
to it, but cannot fetch remote data, change policy during the runtime lifetime or
perform effects. Returning undefined means no additional deadline for that
snapshot. The runtime combines it with existing assessment deadlines, schedules
another worker pass, and checks it again after asynchronous projector work and
when reading a saved projection. Long deadlines use exact integer comparisons
and bounded timer intervals. A delayed timer cannot make expired state current.
The worker's advance method must commit the due invalidation through the
knowledge store. The scheduling hook does not mutate state or manufacture an
outpoint, accepted revision, proposal agreement or Bitcoin evidence. If a worker
leaves expired state unresolved, projection publication fails explicitly instead
of entering a tight automatic retry loop. Applications can retry after resolving
the worker condition. Existing workers can omit the method and retain their
current behavior; the existing store's expired-assessment error remains unchanged.
This boundary protects new publication and reads. Applications must also retire an already displayed provisional view at its known deadline and reconcile when a sleeping tab resumes. They cannot assume that a previously emitted object is revoked by modifying another object in memory. A complete proposal integration still needs installed proposal validation, retained replay interpretation, durable expiry state and visibly distinct proposal/currentness/admission labels. The runtime hook by itself supplies none of those domain guarantees.
Source equivocation and recovery
After the entire batch passes schema and trusted-session checks, BitcoinKnowledge
retains a changed observation identity, reused group identity or inconsistent
watermark as a quarantined receipt. The journal preserves the exact claim and
trusted provenance under its mutation key; its successful commit acknowledges
storage, not acceptance. No sibling in that receipt supplies new evidence,
membership, private context or currentness. The original observation remains
immutable. Independently accepted transaction facts and other providers survive.
Quarantine closes the affected source generation. Existing membership stays visible
as historical membership, with a generic reset diagnostic in pendingGroups;
configured currentness from that source becomes stale. The worker journals a local
reconciliation so watchers receive an accepted revision even when there is no new
proof work. Restart completes that pending reconciliation from retained local
material. Diagnostics never include the rejected private payload. The original
receipt remains accessible only through the partition's local journal inspection.
For a coverage-only reset without a group, the diagnostic uses a local
continuity-reset:<generation> identifier; a group-free equivocating claim uses
quarantine:<mutation-key>. These are diagnostic references, not remote group IDs.
Recovery uses a higher local source generation and a fresh snapshot. Publication swaps only after that complete seed qualifies. Late work from the old generation cannot publish, and changing generations does not permit rewriting an observation identity in the same provider epoch. Other providers keep their own continuity. Malformed or foreign-scope batches are rejected before receipt and cannot close a trusted source's generation. An ordinary transient outage is not equivocation.
Quarantine retains at most 64 receipts and at most the configured pendingBytes
(16 MiB by default), also subject to the journal's overall retention limits. A
capacity failure returns limited before partial mutation; it never deletes a
claim, advances a cursor or calls evidence invalid. Recovery after exhaustion needs
an explicit new journal namespace with the old journal retained for audit. Custom
reducers may use SourceMembershipLedger.receiveRetainingEquivocation and its
bounded quarantines() diagnostics; the lower-level receive method retains its
strict rejection behavior. Both require already schema-checked, locally bound input.
Scoped source currentness
An output observation means collection membership. To interpret a particular
source's named rules as an unspent report, explicitly configure sourceCurrentness
on BitcoinKnowledge. Select the chain, provider, service, query digest, rules
digest and access partition from trusted application configuration. The source's
rules must actually define that meaning; ordinary catalogue membership is not
sufficient. A different provider, query, rule digest or access partition receives
no authority from that selection.
const { epoch, ...sourceIdentity } = configuredScope
const worker = new BitcoinKnowledge({
journalId: journal.namespace,
partition,
nonFinal: false,
verifier,
sourceCurrentness: [
{
source: sourceIdentity,
maximumAgeSeconds: '60'
}
]
})The configured identity spans provider epochs, but every assessment retains its complete actual scope, including epoch. The currentness rule is local application policy, not a new wire field or provider-selected option. Configuration is bounded to 64 distinct rules and 4,096 retained observation identities from selected sources. Exhaustion is an explicit limit requiring a new journal generation; receipts and expiry decisions are never silently dropped.
A report requires accepted whole-group creation evidence under the active context, visible membership and intact source continuity. Pending groups, quarantine, replacement-generation staging, a changed chain context or a local conflicting or spent assessment make that source report stale. Provisional selected spends also prevent a usable unspent report. The independent local transaction assessment is retained, so source data cannot reverse Bitcoin consumption. Two providers remain two source assessments even when they report the same output.
Expiry is exclusive and starts at the observation's first trusted receipt.
Worker completion, duplicate delivery, local refresh and restart do not extend it.
A new observation identity can provide a new report. A source's accepted
assessment-invalidated observation affects only earlier reports in the same
complete scope and named context; it cannot invalidate local facts or another
source. A subsequent new report can qualify independently. Withdrawal removes that
source's report without inventing a spend.
OutputKnowledge schedules expiry even without incoming data. The worker journals
an invalidate mutation before publishing the next coherent snapshot, including
after restart. KnowledgeStore.read independently checks wall time and returns
expired if a delayed timer has not yet committed the invalidation. Resuming the
runtime or calling flush performs that durable work. Replay reconstructs the
recorded outcome without contacting the verifier and never grants a new lifetime.
New journals use local verification frame version 3, sealing normalized currentness rules (including an empty list) alongside the non-final setting. Assessments use the BRC-192 canonical ID order, independent of whether source currentness is enabled. Historical version-1 and version-2 journals retain their original encoding, assessment presentation and accepted decisions when reopened or extended. In particular, version 1 used outpoint order for its local assessments. Saved fixture journals qualify that compatibility without contacting a verifier during replay.
Activating the canonical version-3 presentation for an older journal, or enabling, disabling or changing currentness rules, requires an explicit new namespace. Keep the previous journal for audit/recovery and populate the new one through authorized sources; never copy old accepted mutations as new acceptance authority. A newer frame cannot be mixed into an older namespace, and a version-3 journal cannot be downgraded in place. Unknown versions fail explicitly. No saved history is silently rewritten or interpreted under different presentation rules.
Source adapters
Import finite and direct adapters from @bsv/output-knowledge/sources, and the
durable live adapter from @bsv/output-knowledge/sources/live-lookup. The core entry
does not import wallet result validation or the legacy lookup transport on behalf
of applications using different sources. These browser entries are independently
checked from the same packed artifacts against their declared size budgets.
Finite and direct adapters bind an application-configured scope before opening transport. The scope includes chain, provider, service, query and rules digests, access and epoch. The caller supplies the account partition and monotonically increasing refresh generation. Reusing a completed finite generation for changed data is an error; retry identical observations or start a new generation. Finite adapters reject durable replay cursors instead of pretending to resume a BRC-193 session.
Durable progressive and live lookup
LiveLookupSource composes the SDK's retained-contract BRC-193 HTTP client with a
durable workflow cell and the same durable KnowledgeStore used by the runtime.
It yields snapshot pages progressively, then reads live groups with awaited
backpressure. It preserves complete groups and original receipt times. A local
workflow capture happens before delivery; the core's atomic receive stores the
groups, provenance and successful cursor together. Pulling the next item only
advances workflow state after finding that exact core receipt. Verification and
application projection remain independent, and ingestion cannot authorize a wallet
payment or spend. The selected live lookup profile is unpaid.
The application configures the chain, endpoint/identity, service, query digest,
rules digest, account partition, journal identity and source refresh generation.
The provider assigns access and epoch in the first validated response. connect()
captures or reloads that response and returns the complete SourceRequest for
runtime.attach. Pass that returned request unchanged; an arbitrary saved cursor
cannot be supplied as continuation authority. Source refresh generation and local
verification-context generation are separate counters.
First establish a verification context in the core journal. For a new local workflow identity, validate a freshly discovered signed capability and persist the prepared opening before any HTTP request:
import {
LiveLookupSource,
prepareLiveLookupSource,
liveLookupSourceBinding
} from '@bsv/output-knowledge/sources/live-lookup'
import { SQLiteOperationStateStore } from '@bsv/output-knowledge/operations/sqlite'
// configuration, selection, manifest and query come from the host's installed
// endpoint, chain and service-rules policy. core and runtime share one journal.
const prepared = prepareLiveLookupSource({
configuration,
namespace: workflowId,
manifest,
selection,
query,
limits: { maxBytes: 1024 * 1024, maxObservations: 256, waitMs: 20000 },
minimumReceived: (await core.revision()).received
})
const control = SQLiteOperationStateStore.create(
controlDatabasePath,
prepared.namespace,
prepared.binding,
prepared.initial,
prepared.limits
)
const source = new LiveLookupSource({
configuration,
control,
core,
trust: selection,
wallet // Required only when the selected profile uses BRC-103 authentication.
})
const request = await source.connect()
const subscription = runtime.attach(source, request)
void subscription.done.catch(onSourceFailure)On restart, recover the original control cell using the application-retained
workflow identity and trusted configuration. Use SQLiteOperationStateStore.open
with liveLookupSourceBinding(configuration) and the same control limits. In a
browser, use the corresponding explicit IndexedDBOperationStateStore.create/open
operations with a dedicated database. Both the control cell and core journal must
be durable. The memory adapters deliberately fail this requirement. Missing
storage, a lower core revision, or loss of the exact receipt behind a saved cursor
is an explicit reset condition, even if some unrelated history has the same head
revision. Browser eviction and clearing site data do not create a new opening
implicitly.
Do not call prepareLiveLookupSource again to recover an uncertain operation. The
saved cell retains the original signed capability, exact normalized Open and its
256-bit request ID. Retry and recovery validate that original selection under
installed local trust rules; manifest expiry does not silently replace an already
started operation. Session deadlines and current server authorization still apply.
Treat private control data, opening IDs and cursors according to the account's
storage/access policy; they are not telemetry fields.
Keep the same LiveLookupSource instance across cancelled or uncertain connection
attempts. Its transport continues occupying capacity until an earlier physical
request settles, even if an injected wallet, fetch or storage port ignores abort.
connect() and an active subscription are mutually exclusive; a subscription
allows one pending pull. Closing it cancels local work and does not close a remote
session shared with another worker. Await its done settlement before closing its
storage. If an injected storage port ignores cancellation, also wait for its
physical calls to settle; done reports subscription closure, not completion of
noncancellable external work. An uncertain CAS result is recovered by reading the saved cell, never by
assuming that cancellation rolled it back. Independent workers may share a cell:
CAS chooses one capture, and late results cannot overwrite an advanced job. The
host must bound the number of worker/source instances independently of the runtime's
attached-source limit.
The adapter preflights complete canonical source and control envelopes, including
worst-case escaping of provider-assigned identifiers. It reserves response space
before persisting the Open; it never lowers that saved allowance during recovery.
Limits, owned bindings, total step deadlines and eight-attempt contention bounds
apply to control reads, receipt checks, HTTP and capture. Defaults are a 30-second
operation deadline and 250 milliseconds between polls at the live head. Configure
waitMs + minimumPollMs below operationTimeoutMs, leaving time for authentication,
network and storage. Snapshot pages are not delayed by live-head pacing; every
continuation still yields to the event loop so immediate custom transports cannot
starve cancellation, expiry or another source. Contention,
quota, timeouts and cancellation are explicit failures; none is an empty successful
batch or evidence of a spend.
A previously captured historical batch remains ingestible after session expiry.
After its receipt is durable, local expiry or a selected service's terminal
continuity/authorization error produces a separately captured, empty
reset-required coverage batch. This is the adapter's local continuity report:
it carries no new successful cursor, observation or Bitcoin spend claim. The core
receives it durably, invalidates source continuity and publishes stale currentness
through its normal worker. The source then fails with reset-required. Restart
can replay exactly that reset but cannot resume the retired continuity. Begin an
explicit new source generation and new workflow only after choosing to reconcile;
other providers' evidence and historical facts remain intact. Transient transport
failures do not fabricate authenticated service errors or erase the saved cursor.
Configured source-currentness expiry continues to bound freshness while offline.
The control format is output-live-lookup-source/1. It retains the current job,
original contract/Open, minimum core revision, previous compact checkpoint and
its exact receipt key/position, and at most one captured batch. It never compacts
core receipt history. Preserve all receipts required by resumable source lifetimes;
generation reset and core compaction follow the separate runtime retention contract.
This adapter implements the base lookup profile; critical extensions require an
explicit compatible adapter. Existing finite lookup defaults are unchanged.
WalletOutputSource requests BRC-100 listOutputs with include: 'entire
transactions'. walletOutputQueryDigest(service, query) computes the scope's
query binding. The adapter validates the response through the existing SDK wallet
validator, retains each row's explicit txid and output index, and carries the
aggregate BEEF as received. It never selects an arbitrary last transaction from
that bundle. WALLET_OUTPUT_CONTEXT_SCHEMA identifies UTF-8 JSON containing the
original wallet output row, including requested tags and custom instructions.
That metadata stays inside the account/access partition and is not executable
authority or evidence of Bitcoin validity.
Wallet pages are pulled after the preceding page's receipt commits. Page count, page size, total bytes and the whole invocation's deadline are bounded. Offset pagination is not an atomic snapshot: concurrent wallet changes may duplicate or omit rows. Reconcile again in a new generation as needed. A complete finite scan means only that invocation reached its end. An empty later scan removes that source's membership after its accepted boundary; it does not establish a spend. Wallet calls without cancellation support retain their occupied adapter capacity until they actually settle, even after the subscriber cancels or times out. An installed clock failure before wallet I/O releases the refresh slot; retry the same source after the clock recovers.
LookupOutputSource wraps the existing LookupResolver.query$ and its pre-union
onEvidence receipts, with exactly one configured host per source. Use
lookupOutputQueryDigest(question) and set scope.provider to the canonical host
base, including any path prefix. Attach several instances concurrently within the
runtime's source capacity to obtain progressive federated results:
import { LookupOutputSource } from '@bsv/output-knowledge/sources'
const subscriptions = configuredHosts.map(({ host, scope, generation }) => {
const source = new LookupOutputSource({
id: `catalogue:${host}`,
host,
scope,
question
})
return runtime.attach(source, {
partition,
generation,
scope,
limits: runtime.limits
})
})
await Promise.all(subscriptions.map(subscription => subscription.done))
await runtime.flush()Host selection/discovery is trusted application configuration for this adapter;
it does not silently follow new endpoints or claim BRC-193 continuity. Each host
keeps its own membership and provenance even when another supplies the same
outpoint. A successful empty result, failed request, freeform response, deadline
and truncated intake have distinct outcomes. Legacy context is retained as opaque
JSON under LEGACY_LOOKUP_CONTEXT_SCHEMA, without becoming a new protocol field.
An explicit txid hint remains the asserted target; absent hints use the existing
BRC-24 final-entry target convention. Actual evidence verification remains the
worker's responsibility. Ordinary lookup, submission and resolver semantics are
unchanged.
DirectDeliverySource is a bounded bridge for an application-owned authenticated
transport such as MessageBox, NFC or peer exchange. Configure one source per peer
and access scope, attach it, then call deliver({ id, observations }) with stable
sender-scoped identities. A transport may acknowledge its sender only after that
promise resolves. The runtime advances the source iterator only after receipt
commits; evidence verification can still be pending or later fail. Returning or
cancelling the iterator before the next pull rejects the unconfirmed
acknowledgement. A caller consuming the source manually must honor that same
commit-before-next contract.
Direct delivery requires a durable store by default. Tests or explicitly volatile
applications can select allowVolatileReceipts: true; this does not promise restart
recovery. Queue overflow fails the bridge with limited, rejects unacknowledged
deliveries and requires reconciliation/retry with the original identities. It
never silently drops a receipt while acknowledging it. Direct delivery supplies
partial finite coverage, never an exhaustive collection or a replay cursor. The
adapter does not discover peers, decrypt participant data, or grant transport
authentication to a sender's own payload.
Installed proposal policies
@bsv/output-knowledge/proposals is an optional entry for BRC-194 policy validation.
ProposalPolicyRegistry accepts only explicitly installed local validators and
their exact parameters. Its descriptions carry the registered policy digest for
capability negotiation. An unrecognized identifier or different parameter digest
fails closed; the registry never downloads executable policy code.
import { AuthorDocumentPolicy, ProposalPolicyRegistry } from '@bsv/output-knowledge/proposals'
const policies = new ProposalPolicyRegistry([
{ policy: new AuthorDocumentPolicy(), parameters: { maxTextBytes: 4096 } }
])
const proposal = policies.validate(receivedEnvelope, { chain: configuredChain, service: topic })validate checks closed envelope fields, the selected service and chain, critical
extensions supported by that specific policy, canonical policy payload and the
author's actual BRC-77 signature. It returns an owned copy. permits checks policy
authority for put, read or finalize; it is only one part of authorization. The host
must authenticate the caller and intersect this permission with current access at
each mutation, retry, read and response serialization. The registry has no wallet,
network, admission or storage effects.
The concrete author-document-v1 policy permits canonical UTF-8 JSON {text:string},
including empty text, bounded by 1–4096 text bytes. It requires 1–32 sorted recipients
including the author, zero or one chain-bound anchor, and no embedded transaction.
Revisions retain the author, recipient set and anchor. Only the author may update,
withdraw or finalize. Recipients may read only while the host still authorizes them.
Signing does not encrypt the document; private transport and storage remain required.
successor verifies the exact signed predecessor digest and next revision within
the complete channel namespace. This pure check does not reserve a revision: the
host must still serialize changes against its durable active head. validateProposalWindow
uses exact U64 seconds, finite maximum lifetime, bounded future-clock skew and
exclusive signed expiry. Hosts apply it to new mutations, and separately enforce
current-head expiry and terminal fences. It must not cancel or reject recovery of
an already committed finalization merely because the proposal has since expired.
finalization validates bounded, completely consumed raw transaction bytes and the
claimed txid. For author-document, output zero must contain exactly one satoshi and
OP_FALSE OP_RETURN, a minimal four-byte push of ASCII PRP1, then a minimal push
of the 32-byte proposal digest. An anchor additionally requires input zero to spend
that exact outpoint. The check adds no unrelated sequence or lock-time restriction.
It is a relation check, not evidence verification: the service must independently
verify complete BEEF and configured topic admission before reporting success.
Recording or validating a document never consumes an input or releases a secret.
ProposalTransitions implements the pure channel lifecycle. Each change returns a
whole-record compare-and-swap token, the next local record and the exact proposal
and/or proposal-state events to commit together. It does not write storage itself.
Storage must compare that token, claim a new (caller, service, operationId) binding
when applicable, retain the channel and job, and append its events atomically.
Terminal channel fences must survive compaction for the service identity's lifetime.
An identical signed-body retry retains the original signature, clock and state.
Reservation stores the exact raw transaction, original verified BEEF and admission job before any external topic effect. The caller supplies raw bytes obtained from its trusted complete-BEEF verifier; a relation check does not replace that verifier. Expiry, updates and withdrawal compete with reservation on the same token. Once a reservation wins, expiry cannot cancel the job. A retry with a different verified BEEF encoding of the same raw transaction recovers the original job. Reusing the same operation for other bytes conflicts. Another operation on that already bound proposal resolves the original state and cannot start another transaction.
An uncertain topic result remains finalizing. A positive recovered result backed by the original durable admission receipt links finalization, even if its STEAK instructions are empty. Empty or duplicate STEAK alone establishes neither admission nor rejection. Definitive local rejection terminates the channel as finalization-failed with global outcome unknown. Later callbacks and timer expiry do not rewrite finalized or failed history. Reorganizations belong in separate currentness assessments, not a reversal of the historical admission record. The local replay parser rechecks signatures and record/job bindings offline; it is not an API for accepting remote provider claims as locally completed admissions.
MemoryProposalJournal implements the atomic journal port with explicitly volatile
storage. SQLiteProposalJournal is available from
@bsv/output-knowledge/proposals/sqlite and requires Node 22.13 or newer. It uses
SQLite WAL and synchronous=FULL, creates new files owner-only, and commits each
transition as one immutable row with its revision and retained-byte accounting.
Channel heads, terminal fences, operation claims and pending jobs are derived from
that committed prefix. Independent connections take the same SQLite write lock
before replaying and comparing a head. Reads pin an immutable prefix by revision.
Both journals revalidate plans against the stored lifecycle. They preserve original
commit keys across retries, reject an operation reused for another proposal, retain
superseded signed heads for lookup, and expose bounded ordered journal reads.
getProposal explicitly labels whether a retained signed head is still current.
appendProposalWithRecovery looks up the exact original commit after an uncertain
write; absence surfaces the error and never creates a replacement transaction.
All storage reads, including event history, contain private data and require host
authorization before any external serialization.
An optional local JSON context is committed atomically beside the transition. The
contextRetention capability identifies adapters that support it. The storage
frame retains a domain-separated digest and charges the complete frame against
byte limits; it does not validate a capability contract or confer authority on its
contents. Hosts must validate that context before writing and again during
recovery. Existing body-only entries keep their bytes and transition commit keys.
An identical retry recovers the original context; a different supplied context
fails rather than replacing it. A body-only commit cannot acquire context later.
The SDK's retainOutputCapability and restoreOutputCapability helpers capture
and revalidate a signed selection at its original time. A host can include that
bounded local record in the journal context; it still must bind the selected
proposal policy to its installed lifecycle, retain the operation's actual deadline
and recheck current authorization. A remote caller cannot supply trusted local
recovery context.
ProposalCapabilityContracts binds SDK selection and retention to an installed
ProposalTransitions configuration. It requires a confidential topic proposal
profile for the configured endpoint, identity, chain and service. Every advertised
policy must match an installed identifier, digest and parameter object exactly;
the advertised maximum lifetime must match the installed lifecycle. A host may
advertise a subset of its installed policies, but requirePolicy rejects a signed
head's policy when that particular retained selection omitted it. This check must
precede committing the lifecycle plan. It does not replace the plan's signature
and policy validation, current caller access, deadlines or complete-BEEF checks.
Both reference journals implement the optional getProposalEntry indexed read.
It returns one owned copy of that proposal's latest committed transition, events
and local context together, including for a superseded signed head. A host need
not scan private history or combine a record with context from a different
revision. Hosts must carry the required original contract forward in each new
transition's context; an absent context is an operational recovery failure, never
permission to substitute today's discovery result.
The completionReservation capability holds one maximum-sized entry and its byte
budget for every newly accepted finalizing job. Other writes cannot consume that
space. A terminal receipt releases the reservation. Hosts must bound the complete
terminal entry, including the retained job, STEAK and local context, to entryBytes
before starting admission. This reserves storage capacity, not admission success
or availability of the disk. Earlier journals replay without retroactively
requiring reservations; previously accepted jobs may already exceed the available
completion capacity. Recover those obligations before promising the new guarantee.
The referen
