Skip to content
ContractSpec
Start here

Package manual · domains

·Content, growth and creator operations

lib.content-analysis-runtime

Provider-neutral content analysis orchestration runtime.

domainslibraryv2.0.4experimentalservernode
@lssm-tech/lib.content-analysis-runtime
bun add @lssm-tech/lib.content-analysis-runtime
Package source ↗Manifest ↗

Manifest 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.authorize runs first on every call (first run, replay, resume). A denial throws CONTENT_ANALYSIS_POLICY_DENIED before any repository read and reveals nothing about prior receipts; IDEMPOTENCY_CONFLICT is reported only after authorization. Results carry the current decisionRef.
  • The host injects a budget port: reserve is idempotent per receipt id and settle per reservation ref. maxDurationMs bounds the asset (before any reservation) and time_range segments (before the model call); maxCostMicros bounds the reservation and the provider-reported costMicros (BigInt comparison). An unknown provider cost settles with unknownCharge.
  • Evidence must cite a decomposed segment with the same id and digest.
  • Durable repository (CONTENT-01f): claim inserts the running receipt 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 gets CONTENT_ANALYSIS_FENCE_LOST and writes nothing. The asset-duration refusal is an insertTerminalIfAbsent of the failed receipt plus its outbox row, so concurrent refusals write one row.
  • Step order: authorize -> lookup -> duration check -> claim -> budget.reserve(receiptId) -> attach reservationRef (store metadata, not a receipt field) -> media -> model -> fence re-check -> settle -> terminal save. A refused reservation is a fenced terminal CONTENT_BUDGET_EXCEEDED save.
  • Leases: leaseMs is 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 throws CONTENT_ANALYSIS_IN_PROGRESS with no reserve, media, model or emit. After expiry the call resumes under the same receipt id with fence + 1 and the same reservation, settling with unknownCharge (the interrupted attempt may have been charged). completed/failed receipts 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. relayContentAnalysisOutboxV1 reads one scope's pending rows, reloads each receipt by id, emits with dedupeKey <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: sweepContentAnalysisReservationsV1 expires running rows whose lease expired more than staleAfterMs (>= leaseMs) ago. It takes the row over under a new fence, settles (unknownCharge when a ref was attached; otherwise the model provably never ran, so the idempotent reserve(receiptId) recovers the ref and settles '0' with a known charge, or nothing when nothing was reserved) and saves failed CONTENT_ANALYSIS_EXPIRED with its outbox row.
  • Known limits: a resume can incur a second provider charge under one reservation (flagged by unknownCharge); time_range units are assumed to be milliseconds; a fence lost between the re-check and settle can 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

Declared capabilities

Lib Content Analysis Runtime

Provider-neutral content analysis orchestration runtime.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • cleanrimraf dist .turbo
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit