lib.content-analysis-runtime
Provider-neutral content analysis orchestration runtime.
domainslibraryv2.0.4experimentalservernode
@lssm-tech/lib.content-analysis-runtimebun add @lssm-tech/lib.content-analysis-runtimeManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Pure orchestration for bounded, provider-neutral content analysis. The host injects authorization, media decomposition, structured analysis, persistence, clock, digest, and event ports. The runtime validates evidence, enforces replay, and records sanitized terminal receipts without granting product authority.
Replay, budget and recovery semantics
policy.authorizeruns first on every call (first run, replay, resume). A denial throwsCONTENT_ANALYSIS_POLICY_DENIEDbefore any repository read and reveals nothing about prior receipts;IDEMPOTENCY_CONFLICTis reported only after authorization. Results carry the currentdecisionRef.- The host injects a
budgetport:reserveis idempotent per receipt id andsettleper reservation ref.maxDurationMsbounds the asset (before any reservation) andtime_rangesegments (before the model call);maxCostMicrosbounds the reservation and the provider-reportedcostMicros(BigInt comparison). An unknown provider cost settles withunknownCharge. - Evidence must cite a decomposed segment with the same id and digest.
- Durable repository (CONTENT-01f):
claiminserts therunningreceipt only when no row exists for (tenantId, workspaceId, idempotencyKey) and returns a fence. Every later write (attachReservation,saveTerminal) is conditional on that fence; a stale writer getsCONTENT_ANALYSIS_FENCE_LOSTand writes nothing. The asset-duration refusal is aninsertTerminalIfAbsentof the failed receipt plus its outbox row, so concurrent refusals write one row. - Step order: authorize -> lookup -> duration check -> claim ->
budget.reserve(receiptId)-> attachreservationRef(store metadata, not a receipt field) -> media -> model -> fence re-check -> settle -> terminal save. A refused reservation is a fenced terminalCONTENT_BUDGET_EXCEEDEDsave. - Leases:
leaseMsis a required positive integer and the host must set it at least as long as the model deadline. A same-key call while the lease is live throwsCONTENT_ANALYSIS_IN_PROGRESSwith no reserve, media, model or emit. After expiry the call resumes under the same receipt id with fence + 1 and the same reservation, settling withunknownCharge(the interrupted attempt may have been charged).completed/failedreceipts replay without effects, and a retry after failure needs a fresh idempotency key. - Outbox: every terminal save writes the receipt and one outbox row (
content.analysis.completed/failed) in one transaction.relayContentAnalysisOutboxV1reads one scope's pending rows, reloads each receipt by id, emits withdedupeKey<receiptId>:<eventKey>and acks. Emit failure defers the row (attempts + 1). Delivery is at-least-once with a stable dedupe key; the pipeline's inline relay is best-effort only. - Sweep:
sweepContentAnalysisReservationsV1expiresrunningrows whose lease expired more thanstaleAfterMs(>=leaseMs) ago. It takes the row over under a new fence, settles (unknownChargewhen a ref was attached; otherwise the model provably never ran, so the idempotentreserve(receiptId)recovers the ref and settles '0' with a known charge, or nothing when nothing was reserved) and saves failedCONTENT_ANALYSIS_EXPIREDwith its outbox row. - Known limits: a resume can incur a second provider charge under one reservation (flagged by
unknownCharge);time_rangeunits are assumed to be milliseconds; a fence lost between the re-check andsettlecan still refine the shared settlement.
Relationships
THIS PACKAGElib.content-analysis-runtime4 import paths
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
2 declarations
@lssm-tech/lib.content-analysis-specworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗
Declared capabilities
Lib Content Analysis Runtime
Provider-neutral content analysis orchestration runtime.
Scripts
buildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typescleanrimraf dist .turbolint:checknode ../../../../scripts/biome.cjs check .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit