@atomicmemory/core 1.0.0

package/dist/services/typed-belief-calculus.js

@@ -0,0 +1,204 @@
+/**
+ * Typed Belief Calculus (TBC) — Phase 2 LLM resolver.
+ *
+ * The TBC is a strict superset of AUDN's `Add | Update | Delete | No-op`
+ * decision space. It introduces eight typed operators that each carry
+ * explicit storage semantics: Affirm, Update, Retract, Supersede, Promote,
+ * Demote, EvidenceFor, Counter.
+ *
+ * Phase 2 (this revision) wires `decideBeliefOperator` to a real LLM call
+ * and lets `memory-audn.ts` route through it when `RuntimeConfig.tbcEnabled`
+ * is true. Schema is unchanged — TBC mutations write to existing JSONB
+ * metadata only. See `tbc-execution.ts` for the executor and
+ * `docs/typed-belief-calculus.md` for design rationale.
+ */
+import { llm as defaultLlm } from './llm.js';
+import { extractFirstJsonObject } from './extraction.js';
+const TBC_MAX_TOKENS = 4096;
+const TBC_MAX_CANDIDATES = 3;
+/**
+ * The eight typed belief operators that extend AUDN.
+ *
+ * Each operator describes a distinct effect on the belief graph; they are
+ * not mutually exclusive intents over the same evidence — `decideBeliefOperator`
+ * always picks exactly one per ingest, mirroring how AUDN picks exactly one
+ * AUDNAction today.
+ */
+export var BeliefOperator;
+(function (BeliefOperator) {
+    /** New evidence supports an existing claim — strengthen confidence, no new claim. */
+    BeliefOperator["Affirm"] = "AFFIRM";
+    /** Same attribute, different value — versioned supersession with both states retained. */
+    BeliefOperator["Update"] = "UPDATE";
+    /** Claim now believed false (no replacement) — mark RETRACTED, preserve as evidence. */
+    BeliefOperator["Retract"] = "RETRACT";
+    /** Replaced by a more specific or general claim — link old to new; both queryable. */
+    BeliefOperator["Supersede"] = "SUPERSEDE";
+    /** Strong, repeated belief becomes a directive (constraint tier) influencing answer prompt. */
+    BeliefOperator["Promote"] = "PROMOTE";
+    /** Challenged but not retracted — lower confidence; flag for re-evaluation. */
+    BeliefOperator["Demote"] = "DEMOTE";
+    /** Adds an evidence-for edge to a supported claim — does not introduce a new claim. */
+    BeliefOperator["EvidenceFor"] = "EVIDENCE_FOR";
+    /** Adds a counter edge to a challenged claim — does not introduce a new claim. */
+    BeliefOperator["Counter"] = "COUNTER";
+})(BeliefOperator || (BeliefOperator = {}));
+const VALID_OPERATORS = new Set(Object.values(BeliefOperator));
+/** Raised when the LLM resolver cannot produce a usable TBC decision. */
+export class BeliefResolverError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'BeliefResolverError';
+    }
+}
+const TBC_SYSTEM_PROMPT = `You are a belief-state reconciliation system. Given a NEW atomic claim and up to ${TBC_MAX_CANDIDATES} CANDIDATE existing claims (each with current belief state), pick exactly ONE typed belief operator that best describes the relationship.
+
+OPERATORS:
+- AFFIRM: NEW supports an existing CANDIDATE; no new claim is created. Strengthens the target.
+- UPDATE: NEW corrects a CANDIDATE about the same attribute (minor edit / typo / qualifier).
+- RETRACT: NEW asserts an existing CANDIDATE is false, with no replacement.
+- SUPERSEDE: NEW replaces a CANDIDATE with a more specific or more general claim. Both remain queryable.
+- PROMOTE: NEW reinforces a repeatedly-affirmed CANDIDATE strongly enough that it should become a directive.
+- DEMOTE: NEW challenges a CANDIDATE but is not strong enough to retract — lower its confidence.
+- EVIDENCE_FOR: NEW is itself novel content but adds a supporting edge to a CANDIDATE.
+- COUNTER: NEW is itself novel content but adds a contradicting edge to a CANDIDATE.
+
+RULES:
+- Pick AFFIRM when the candidate set is empty AND the new claim has no clear target.
+- target_claim_id MUST match one of the CANDIDATE ids when the operator references a target.
+- confidence_delta is in [-1, 1]: positive for AFFIRM/EVIDENCE_FOR/PROMOTE, negative for DEMOTE/COUNTER/RETRACT, 0 for UPDATE/SUPERSEDE.
+- Prefer EVIDENCE_FOR over AFFIRM when the new claim contains genuinely novel surface content but semantically supports the target.
+
+OUTPUT FORMAT (JSON):
+{
+  "operator": "AFFIRM" | "UPDATE" | "RETRACT" | "SUPERSEDE" | "PROMOTE" | "DEMOTE" | "EVIDENCE_FOR" | "COUNTER",
+  "target_claim_id": null | "id of candidate",
+  "confidence_delta": -1.0 to 1.0,
+  "rationale": "one sentence justification"
+}
+
+Return only the JSON object. Do not wrap it in markdown fences. Do not explain your reasoning outside the JSON.`;
+function viewCandidate(candidate) {
+    // Phase 2 does not yet hydrate confidence from storage; future phases pass
+    // the loaded BeliefMetadata in. For now we report the AUDN-era defaults.
+    return {
+        id: candidate.id,
+        content: candidate.content,
+        similarity: candidate.similarity,
+        confidence: 1.0,
+        mutation_type: null,
+        history_depth: 0,
+    };
+}
+function buildTbcUserMessage(newClaim, candidates) {
+    const trimmed = candidates.slice(0, TBC_MAX_CANDIDATES).map(viewCandidate);
+    const candidatesBlock = trimmed.length === 0
+        ? '(no candidates)'
+        : trimmed.map((c) => (`[ID: ${c.id}] (similarity: ${c.similarity.toFixed(2)}, confidence: ${c.confidence.toFixed(2)}, mutation: ${c.mutation_type ?? 'NONE'}, history_depth: ${c.history_depth}) ${c.content}`)).join('\n');
+    return `NEW CLAIM: ${newClaim.fact}\n\nCANDIDATE CLAIMS:\n${candidatesBlock}`;
+}
+function parseTbcDecision(raw, candidateIds) {
+    const cleaned = extractFirstJsonObject(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new BeliefResolverError(`TBC resolver returned non-JSON output: ${cleaned.slice(0, 400)}`, err);
+    }
+    return validateTbcDecision(parsed, candidateIds);
+}
+/** Operators that require a target_claim_id from the candidate set. AFFIRM is the only exception. */
+const TARGET_REQUIRED_OPERATORS = new Set([
+    BeliefOperator.Update,
+    BeliefOperator.Retract,
+    BeliefOperator.Supersede,
+    BeliefOperator.Promote,
+    BeliefOperator.Demote,
+    BeliefOperator.EvidenceFor,
+    BeliefOperator.Counter,
+]);
+// fallow-ignore-next-line complexity
+function validateTbcDecision(parsed, candidateIds) {
+    const operator = typeof parsed.operator === 'string' && VALID_OPERATORS.has(parsed.operator)
+        ? parsed.operator
+        : null;
+    if (!operator) {
+        throw new BeliefResolverError(`TBC resolver returned invalid operator: ${String(parsed.operator)}`);
+    }
+    const target = typeof parsed.target_claim_id === 'string' ? parsed.target_claim_id : null;
+    if (target !== null && !candidateIds.has(target)) {
+        throw new BeliefResolverError(`TBC resolver returned target_claim_id "${target}" not in candidate set [${[...candidateIds].join(', ')}]`);
+    }
+    if (TARGET_REQUIRED_OPERATORS.has(operator) && target === null) {
+        throw new BeliefResolverError(`TBC resolver picked ${operator} but provided no target_claim_id. ${operator} requires one of [${[...candidateIds].join(', ')}].`);
+    }
+    const deltaRaw = typeof parsed.confidence_delta === 'number' ? parsed.confidence_delta : 0;
+    const confidence_delta = Number.isFinite(deltaRaw) ? Math.max(-1, Math.min(1, deltaRaw)) : 0;
+    const rationale = typeof parsed.rationale === 'string' ? parsed.rationale : '';
+    return {
+        operator,
+        ...(target ? { target_claim_id: target } : {}),
+        confidence_delta,
+        rationale,
+    };
+}
+/**
+ * Resolve a typed belief operator for a candidate set via an LLM call.
+ *
+ * Fail-closed: any LLM transport failure or parser failure raises
+ * `BeliefResolverError` rather than silently returning an `Affirm`/`ADD`
+ * stub. AUDN's existing executor will surface the error to the caller.
+ *
+ * The signature mirrors `resolveAUDN(factText, candidates)` so the
+ * `memory-audn.ts` call site can swap it in cleanly.
+ *
+ * @param newClaim - The inbound atomic claim about to be ingested.
+ * @param candidates - Conflict candidates already discovered via the standard
+ *   AUDN candidate search; same input AUDN sees today.
+ * @param llmClient - Optional LLM provider override for tests; defaults to
+ *   the shared singleton in `services/llm.ts`.
+ * @returns A `BeliefOperationDecision` selecting one of the eight operators.
+ */
+export async function decideBeliefOperator(newClaim, candidates, llmClient = defaultLlm) {
+    const candidateIds = new Set(candidates.slice(0, TBC_MAX_CANDIDATES).map((c) => c.id));
+    const messages = [
+        { role: 'system', content: TBC_SYSTEM_PROMPT },
+        { role: 'user', content: buildTbcUserMessage(newClaim, candidates) },
+    ];
+    return runTbcLlmWithRetry(messages, candidateIds, llmClient);
+}
+/**
+ * Issue the TBC LLM call and parse. On parser/validation failure, retry ONCE
+ * with the validation error appended to the prompt as corrective context.
+ * Fail-closed (re-throws) if the retry also fails — preserves AUDN semantics.
+ */
+async function runTbcLlmWithRetry(messages, candidateIds, llmClient) {
+    try {
+        return await callAndParseTbc(messages, candidateIds, llmClient);
+    }
+    catch (firstErr) {
+        if (!(firstErr instanceof BeliefResolverError))
+            throw firstErr;
+        const correctiveTurn = {
+            role: 'user',
+            content: `Your previous response was invalid: ${firstErr.message}\nReturn a valid JSON object that conforms to the schema. If you pick UPDATE, RETRACT, SUPERSEDE, PROMOTE, DEMOTE, EVIDENCE_FOR, or COUNTER, you MUST set target_claim_id to one of the candidate IDs above.`,
+        };
+        return callAndParseTbc([...messages, correctiveTurn], candidateIds, llmClient);
+    }
+}
+async function callAndParseTbc(messages, candidateIds, llmClient) {
+    let raw;
+    try {
+        raw = await llmClient.chat(messages, { temperature: 0, jsonMode: true, maxTokens: TBC_MAX_TOKENS });
+    }
+    catch (err) {
+        throw new BeliefResolverError(`TBC resolver LLM call failed: ${err.message}`, err);
+    }
+    if (!raw) {
+        throw new BeliefResolverError('TBC resolver returned empty content');
+    }
+    return parseTbcDecision(raw, candidateIds);
+}

package/dist/services/upload-config.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file Typed configuration for the managed-blob upload pipeline.
+ *
+ * Discriminated by `rawStorageMode` so pointer-only deployments
+ * carry no HMAC secret at all (vs. holding a placeholder that is
+ * "never consumed in practice" — that earlier shape violated the
+ * workspace no-fallback rule and made it possible to leak a fake
+ * value into service code).
+ *
+ *   - `pointer_only` deployments: `{rawStorageMode, rawStoragePrefix}`
+ *     only. No key derivation runs in this branch, so the HMAC
+ *     secret is structurally absent.
+ *   - `managed_blob` deployments: REQUIRED `storageKeyHmacSecret`.
+ *     `runtime-container` narrows `RuntimeConfig` to this variant
+ *     when it constructs the document upload pipeline; tests build
+ *     the variant directly with `TEST_STORAGE_KEY_HMAC_SECRET`.
+ *
+ * Callers narrow with `rawStorageMode === 'managed_blob'` (the
+ * upload pipeline's early-return gate is exactly that check), at
+ * which point the secret is statically available without any
+ * runtime defensive read.
+ */
+/** Pointer-only — no managed-key derivation runs in this branch. */
+export interface UploadConfigPointerOnly {
+    rawStorageMode: 'pointer_only';
+    rawStoragePrefix: string;
+}
+/** Managed-blob — HMAC secret required to derive PII-safe key prefixes. */
+export interface UploadConfigManagedBlob {
+    rawStorageMode: 'managed_blob';
+    rawStoragePrefix: string;
+    storageKeyHmacSecret: string;
+}
+export type UploadConfig = UploadConfigPointerOnly | UploadConfigManagedBlob;

package/dist/services/upload-config.js

@@ -0,0 +1,23 @@
+/**
+ * @file Typed configuration for the managed-blob upload pipeline.
+ *
+ * Discriminated by `rawStorageMode` so pointer-only deployments
+ * carry no HMAC secret at all (vs. holding a placeholder that is
+ * "never consumed in practice" — that earlier shape violated the
+ * workspace no-fallback rule and made it possible to leak a fake
+ * value into service code).
+ *
+ *   - `pointer_only` deployments: `{rawStorageMode, rawStoragePrefix}`
+ *     only. No key derivation runs in this branch, so the HMAC
+ *     secret is structurally absent.
+ *   - `managed_blob` deployments: REQUIRED `storageKeyHmacSecret`.
+ *     `runtime-container` narrows `RuntimeConfig` to this variant
+ *     when it constructs the document upload pipeline; tests build
+ *     the variant directly with `TEST_STORAGE_KEY_HMAC_SECRET`.
+ *
+ * Callers narrow with `rawStorageMode === 'managed_blob'` (the
+ * upload pipeline's early-return gate is exactly that check), at
+ * which point the secret is statically available without any
+ * runtime defensive read.
+ */
+export {};

package/dist/services/upload-decision.d.ts

@@ -0,0 +1,65 @@
+/**
+ * the managed-upload upload-pipeline decision helpers — pure functions extracted
+ * out of `document-upload.ts` so the α/β/β2/γ orchestration stays
+ * under the 40-LOC-per-function cap and the decision tables are
+ * independently testable.
+ *
+ *   - `classifyIdempotent` decides what an in-flight `uploadRaw`
+ *     should do given the document's current row state + the
+ *     incoming content hash. Drives the claim step's idempotency short-
+ *     circuit and the same-bytes crash recovery branches.
+ *   - `deriveFinalRawStorageStatus` maps the adapter's lifecycle hint
+ *     (`'stored'` / `'pending'`) + provider name to the terminal
+ *     `raw_storage_status` value the finalization step writes. Provider-aware:
+ *     Filecoin `'stored'` is `blob_available` (gateway-confirmed
+ *     retrievable), immediate providers stay `blob_stored`.
+ *
+ * No imports of pg / store / codec — these helpers are 100% pure so
+ * tests can drive them with plain row literals.
+ */
+import type { RawDocumentRow } from '../db/raw-document-types.js';
+export type UploadIdempotencyDecision = {
+    kind: 'returnExisting';
+} | {
+    kind: 'reclaimAndUpload';
+} | {
+    kind: 'finalize';
+};
+/**
+ * Decision-table classifier: given the row's current state + the
+ * incoming content hash, decide whether the claim step can short-circuit
+ * (returnExisting), needs to re-run β/β2/γ in full (reclaimAndUpload),
+ * or can jump straight to the finalization step (finalize — recovery from a crash
+ * that happened between the durable URI-write step's URI write and the finalization step's status
+ * flip).
+ *
+ * Returns `null` when the row's content hash does NOT match — caller
+ * runs the existing `hasConflictingManagedBlob` check, which raises a
+ * 409 if the slot is occupied with different bytes.
+ */
+export declare function classifyIdempotent(document: RawDocumentRow, contentHash: string): UploadIdempotencyDecision | null;
+/**
+ * Provider-aware terminal status mapping. the finalization step writes the return
+ * value as the new `raw_storage_status`.
+ *
+ *   - Adapter `'pending'` → `blob_pending` regardless of provider
+ *     (the reconciler completes the flow).
+ *   - Adapter `'stored'` + eventual content-addressed provider →
+ *     `blob_available` (the provider has confirmed retrievability;
+ *     we skip past `blob_stored` directly to terminal-OK).
+ *   - Adapter `'stored'` + any other provider → `blob_stored`
+ *     (immediate providers — local_fs / s3).
+ */
+export declare function deriveFinalRawStorageStatus(args: {
+    storedStatus: 'stored' | 'pending';
+    storageProvider: string;
+}): 'blob_pending' | 'blob_available' | 'blob_stored';
+/**
+ * Read the persisted `upload_result.stored_status` sidecar the durable URI-write step
+ * wrote into `raw_storage_metadata`. the finalization step needs this on the
+ * finalize-recovery path because the in-memory `stored` from the provider-write step
+ * is null when β + β2 are skipped. Returns null when the sidecar is
+ * missing or malformed — caller must defend (the finalization step throws an
+ * InvariantError in that case).
+ */
+export declare function readPersistedStoredStatus(metadata: Record<string, unknown>): 'stored' | 'pending' | null;

package/dist/services/upload-decision.js

@@ -0,0 +1,98 @@
+/**
+ * the managed-upload upload-pipeline decision helpers — pure functions extracted
+ * out of `document-upload.ts` so the α/β/β2/γ orchestration stays
+ * under the 40-LOC-per-function cap and the decision tables are
+ * independently testable.
+ *
+ *   - `classifyIdempotent` decides what an in-flight `uploadRaw`
+ *     should do given the document's current row state + the
+ *     incoming content hash. Drives the claim step's idempotency short-
+ *     circuit and the same-bytes crash recovery branches.
+ *   - `deriveFinalRawStorageStatus` maps the adapter's lifecycle hint
+ *     (`'stored'` / `'pending'`) + provider name to the terminal
+ *     `raw_storage_status` value the finalization step writes. Provider-aware:
+ *     Filecoin `'stored'` is `blob_available` (gateway-confirmed
+ *     retrievable), immediate providers stay `blob_stored`.
+ *
+ * No imports of pg / store / codec — these helpers are 100% pure so
+ * tests can drive them with plain row literals.
+ */
+/**
+ * Decision-table classifier: given the row's current state + the
+ * incoming content hash, decide whether the claim step can short-circuit
+ * (returnExisting), needs to re-run β/β2/γ in full (reclaimAndUpload),
+ * or can jump straight to the finalization step (finalize — recovery from a crash
+ * that happened between the durable URI-write step's URI write and the finalization step's status
+ * flip).
+ *
+ * Returns `null` when the row's content hash does NOT match — caller
+ * runs the existing `hasConflictingManagedBlob` check, which raises a
+ * 409 if the slot is occupied with different bytes.
+ */
+export function classifyIdempotent(document, contentHash) {
+    if (document.contentHash !== contentHash)
+        return null;
+    switch (document.rawStorageStatus) {
+        case 'blob_stored':
+        case 'blob_pending':
+        case 'blob_available':
+            return { kind: 'returnExisting' };
+        case 'blob_uploading':
+            // the claim step-only OR Phase-β-only row (crash before the durable URI-write step wrote
+            // the URI). Bytes may already be on the provider but we don't
+            // have the CID — re-run β + β2 + γ. If the provider is
+            // content-addressed-idempotent, the second `store.put()` returns
+            // the same CID; if not, this creates a rare orphan-billing risk
+            // for provider cleanup.
+            if (document.storageUri === null)
+                return { kind: 'reclaimAndUpload' };
+            // the durable URI-write step succeeded; crash before the finalization step flipped the status.
+            // The URI is durable in the row, the bytes are on the provider.
+            // Skip β + β2 entirely; run the finalization step alone. No re-encode, no
+            // re-upload, no re-billing.
+            return { kind: 'finalize' };
+        case 'raw_storage_failed':
+            return { kind: 'reclaimAndUpload' };
+        default:
+            return null;
+    }
+}
+/**
+ * Provider-aware terminal status mapping. the finalization step writes the return
+ * value as the new `raw_storage_status`.
+ *
+ *   - Adapter `'pending'` → `blob_pending` regardless of provider
+ *     (the reconciler completes the flow).
+ *   - Adapter `'stored'` + eventual content-addressed provider →
+ *     `blob_available` (the provider has confirmed retrievability;
+ *     we skip past `blob_stored` directly to terminal-OK).
+ *   - Adapter `'stored'` + any other provider → `blob_stored`
+ *     (immediate providers — local_fs / s3).
+ */
+export function deriveFinalRawStorageStatus(args) {
+    if (args.storedStatus === 'pending')
+        return 'blob_pending';
+    if (isEventualContentProvider(args.storageProvider))
+        return 'blob_available';
+    return 'blob_stored';
+}
+function isEventualContentProvider(provider) {
+    return provider === 'filecoin';
+}
+/**
+ * Read the persisted `upload_result.stored_status` sidecar the durable URI-write step
+ * wrote into `raw_storage_metadata`. the finalization step needs this on the
+ * finalize-recovery path because the in-memory `stored` from the provider-write step
+ * is null when β + β2 are skipped. Returns null when the sidecar is
+ * missing or malformed — caller must defend (the finalization step throws an
+ * InvariantError in that case).
+ */
+export function readPersistedStoredStatus(metadata) {
+    const uploadResult = metadata['upload_result'];
+    if (!uploadResult || typeof uploadResult !== 'object')
+        return null;
+    const stored = uploadResult['stored_status'];
+    if (stored === 'stored' || stored === 'pending')
+        return stored;
+    return null;
+}

package/dist/services/upload-helpers.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Stateless helpers extracted out of `document-upload.ts` to keep the
+ * orchestration file under the workspace 400-line cap. These are pure
+ * functions + small async wrappers — no orchestration state, no
+ * codec/store/registry coupling beyond the typed argument bag.
+ */
+import pg from 'pg';
+import type { RawDocumentRow } from '../db/raw-document-types.js';
+import type { StoredRawContent } from '../storage/raw-content-store.js';
+export declare class UploadDocumentNotFoundError extends Error {
+    readonly documentId: string;
+    constructor(documentId: string);
+}
+export declare class ManagedStorageDisabledError extends Error {
+    constructor();
+}
+export declare class UploadDocumentConflictError extends Error {
+    readonly documentId: string;
+    readonly existingContentHash: string;
+    readonly incomingContentHash: string;
+    constructor(documentId: string, existingContentHash: string, incomingContentHash: string);
+}
+/**
+ * Surfaced when Phase β2 or Phase γ's compare-and-set found 0 rows.
+ * Means our claim was lost — another worker reclaimed the row or it
+ * was concurrently deleted. Not exported because route handlers
+ * currently map any such error to a generic 500; promote to `export`
+ * when Phase 8.5 observability needs to discriminate it.
+ */
+export declare class UploadClaimLostError extends Error {
+    readonly documentId: string;
+    readonly claimId: string;
+    readonly phase: 'beta2' | 'gamma';
+    constructor(documentId: string, claimId: string, phase: 'beta2' | 'gamma');
+}
+export interface UploadRawInput {
+    userId: string;
+    documentId: string;
+    body: Buffer;
+    contentType?: string;
+}
+export interface UploadRawResult {
+    documentId: string;
+    storageProvider: string;
+    storageUri: string;
+    contentHash: string;
+    sizeBytes: number;
+    rawStorageStatus: 'blob_stored' | 'blob_pending' | 'blob_available';
+    storageMode: 'managed_blob';
+    /**
+     * INTERNAL metadata shape `{ codec, filecoin?, upload_result }`.
+     * Route formatters project this through
+     * `formatPublicRawStorageMetadata` before emitting to the wire
+     * (rev-fix HIGH 3). Internal callers (Phase γ recovery, tests) can
+     * read the full shape directly off this field.
+     */
+    rawStorageMetadata: Record<string, unknown>;
+    idempotentSkip: boolean;
+}
+export declare function loadActive(client: pg.PoolClient, input: UploadRawInput): Promise<RawDocumentRow>;
+export declare function sha256Hex(buf: Buffer): string;
+export declare function describeError(err: unknown): string;
+/**
+ * Build the adapter-relative key the blob is stored under. Includes
+ * the content hash so byte-identical re-uploads collide on the same
+ * key (no orphan from re-uploading the same content).
+ *
+ * `userPrefix` MUST be the HMAC-SHA256-derived per-user prefix from
+ * `deriveStorageKeyPrefix(secret, userId)`. The plaintext `userId`
+ * MUST NEVER appear in any provider key/URI — the HMAC prefix is
+ * the PII-safe replacement. Stable across retries (same user → same
+ * prefix) so the same-bytes re-upload idempotency contract holds.
+ */
+export declare function blobKey(prefix: string, userPrefix: string, documentId: string, contentHash: string): string;
+/**
+ * Echo the row's existing state as the idempotent-skip response.
+ * Phase α returns this when `classifyIdempotent === 'returnExisting'`.
+ */
+export declare function idempotentResult(document: RawDocumentRow, contentHash: string, sizeBytes: number): UploadRawResult;
+export interface BuildUploadResultArgs {
+    documentId: string;
+    storageProvider: string;
+    storageUri: string;
+    contentHash: string;
+    sizeBytes: number;
+    finalStatus: 'blob_stored' | 'blob_pending' | 'blob_available';
+    rawStorageMetadata: Record<string, unknown>;
+    idempotentSkip: boolean;
+}
+export declare function buildUploadResult(args: BuildUploadResultArgs): UploadRawResult;
+/**
+ * Build the `raw_storage_metadata` JSONB Phase β2 writes:
+ *   - `codec`: the encoder's sidecar (name + version + AES-GCM internals).
+ *   - spread of `stored.providerMetadata`: `{ filecoin: { ... } }` for
+ *     Filecoin; `{}` for immediate providers.
+ *   - `upload_result.stored_status`: INTERNAL sidecar Phase γ reads
+ *     on the finalize-recovery path. Public formatters strip it.
+ */
+export declare function buildPhaseBeta2Metadata(stored: StoredRawContent & {
+    codecMetadata: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Best-effort `raw_storage_failed` marker. Logs (does not swallow)
+ * the marker failure so the original upload error is the one the
+ * caller sees.
+ */
+export declare function markRawStorageFailureBestEffort(q: pg.Pool, userId: string, documentId: string, code: string, message: string): Promise<void>;