@mnstry/atelier 0.2.0-alpha.11 → 0.2.0-alpha.13

package/src/ingestion/optional/lightrag/atelier_lightrag_supplier/artifacts.py

@@ -0,0 +1,101 @@
+"""Private supplier artifacts. These receipts do not replace Atelier intake."""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+from enum import Enum
+from pathlib import Path
+
+
+def portable(value):
+    """Preserve native data fields without repr-based or lossy coercion."""
+    if dataclasses.is_dataclass(value):
+        value = dataclasses.asdict(value)
+    elif isinstance(value, Enum):
+        value = value.value
+    elif hasattr(value, "model_dump"):
+        value = value.model_dump(mode="json")
+    if value is None or isinstance(value, (str, bool, int, float)):
+        # Reject NaN/Infinity, which are not portable JSON.
+        json.dumps(value, allow_nan=False)
+        return value
+    if isinstance(value, (list, tuple)):
+        return [portable(item) for item in value]
+    if isinstance(value, dict) and all(isinstance(key, str) for key in value):
+        return {key: portable(item) for key, item in value.items()}
+    raise TypeError("Native artifact needs a host JSON serializer; object was not discarded")
+
+
+def encoded(value):
+    return json.dumps(portable(value), ensure_ascii=False, sort_keys=True,
+                      separators=(",", ":"), allow_nan=False).encode("utf-8")
+
+
+def digest(value):
+    return "sha256:" + hashlib.sha256(encoded(value)).hexdigest()
+
+
+class MemoryArtifacts:
+    """Test/host injection sink; the host must retain its returned bytes."""
+    def __init__(self):
+        self.objects = {}
+
+    def put_bytes(self, kind, data):
+        if not isinstance(data, bytes):
+            raise TypeError("Artifact bytes are required")
+        sha = hashlib.sha256(data).hexdigest()
+        self.objects.setdefault(sha, data)
+        return {"artifactId": "sha256:" + sha, "kind": kind,
+                "bytes": len(data), "storage": "host-memory"}
+
+    def put_json(self, kind, value):
+        return self.put_bytes(kind, encoded(value))
+
+    def read_json(self, ref):
+        return json.loads(self.read_bytes(ref))
+
+    def read_bytes(self, ref):
+        data = self.objects[ref["artifactId"].removeprefix("sha256:")]
+        if "sha256:" + hashlib.sha256(data).hexdigest() != ref["artifactId"]:
+            raise ValueError("Artifact readback digest differs")
+        return data
+
+
+class FileArtifacts:
+    """Immutable, content addressed files under an explicitly allocated root."""
+    def __init__(self, root, *, owner_root):
+        self.root, owner = Path(root).resolve(), Path(owner_root).resolve()
+        if not self.root.is_relative_to(owner):
+            raise ValueError("Artifact root is outside the supplier allocation")
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def put_bytes(self, kind, data):
+        if not isinstance(data, bytes):
+            raise TypeError("Artifact bytes are required")
+        sha = hashlib.sha256(data).hexdigest()
+        target = self.root / (sha + ".artifact")
+        try:
+            with target.open("xb") as output:
+                output.write(data)
+                output.flush()
+                import os
+                os.fsync(output.fileno())
+        except FileExistsError:
+            if target.read_bytes() != data:
+                raise ValueError("Existing artifact differs from its content address")
+        return {"artifactId": "sha256:" + sha, "kind": kind,
+                "bytes": len(data), "storage": "supplier-file", "path": str(target)}
+
+    def put_json(self, kind, value):
+        return self.put_bytes(kind, encoded(value))
+
+    def read_json(self, ref):
+        return json.loads(self.read_bytes(ref))
+
+    def read_bytes(self, ref):
+        target = self.root / (ref["artifactId"].removeprefix("sha256:") + ".artifact")
+        data = target.read_bytes()
+        if "sha256:" + hashlib.sha256(data).hexdigest() != ref["artifactId"]:
+            raise ValueError("Artifact readback digest differs")
+        return data

package/src/ingestion/optional/lightrag/atelier_lightrag_supplier/projection.py

@@ -0,0 +1,146 @@
+"""Derived native projection of the actual semantic runner project() result.
+
+Canonical acceptance/identity remains with the host's existing knowledge runner.
+Opaque IDs are native-normalization-safe. Native traversal stays undirected.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from .artifacts import digest, encoded, portable
+
+
+def record_ref(value):
+    if not (isinstance(value, dict) and isinstance(value.get("id"), str)
+            and re.fullmatch(r"sha256:[a-f0-9]{64}", value.get("digest", ""))):
+        raise ValueError("An exact existing harnessRef {id,digest} is required")
+    return portable(value)
+
+
+def opaque(kind, value):
+    return "ATELIER_" + kind + "_" + hashlib.sha256(encoded(value)).hexdigest().upper()
+
+
+def build_projection(project, *, profile="assertion-incidence"):
+    if (project.get("schema") != "atelier-knowledge-graph-proposal@v1"
+            or project.get("semanticProfile") != "atelier.semantic-operation-profile/v0"
+            or project.get("canonicalMutation") is not False or project.get("authority") != "none"):
+        raise ValueError("The existing runner semantic projection profile is required")
+    if profile not in {"assertion-incidence", "semantic-adjacency"}:
+        raise ValueError("Declare a supported projection profile")
+    result = {"chunks": [], "entities": [], "relationships": []}
+    mapping = {"entities": {}, "assertions": {}, "roles": {}, "chunks": {}}
+    losses = ["Native traversal is undirected; resolve direction from retained assertion records",
+              "Native summaries, weights and edits do not establish canonical truth",
+              "Native chunk IDs hash content: identical quote chunks can coalesce; exact evidence remains retained",
+              "Native entity/assertion source links use their first evidence alias; all evidence remains retained and indexed as chunks"]
+    entity_by_candidate, entity_by_record, seen_records = {}, {}, set()
+    for item in project.get("semanticEntities", []):
+        ref, candidate = record_ref(item["record"]), portable(item["candidate"])
+        if ref["id"] in seen_records or candidate["id"] in entity_by_candidate:
+            raise ValueError("Semantic entity identities are ambiguous")
+        seen_records.add(ref["id"])
+        name = opaque("ENTITY", ref)
+        entity_by_candidate[candidate["id"]] = name
+        entity_by_record[(ref["id"], ref["digest"])] = name
+        mapping["entities"][name] = {"record": ref, "candidate": candidate}
+        aliases = []
+        for index, evidence in enumerate(candidate.get("evidence", [])):
+            if not isinstance(evidence.get("quote"), str) or not evidence.get("quote"):
+                raise ValueError("Entity evidence needs its actual located quote")
+            alias = opaque("EVIDENCE", {"entity": ref, "index": index, "evidence": evidence})
+            aliases.append(alias)
+            mapping["chunks"][alias] = {"entity": ref, "evidence": evidence}
+            result["chunks"].append({"content": evidence["quote"], "source_id": alias,
+                "file_path": evidence.get("ref", "retained-evidence:" + alias), "chunk_order_index": index})
+        if not aliases:
+            losses.append("Entity " + ref["id"] + " has no native chunk source; exact canonical identity reference remains retained")
+        result["entities"].append({"entity_name": name, "entity_type": candidate["type"],
+            "description": encoded({"label": candidate["label"], "record": ref,
+                                    "identity": candidate.get("identity")}).decode(),
+            "source_id": aliases[0] if aliases else ""})
+
+    adjacency_pairs = {}
+    for item in project.get("semanticAssertions", []):
+        ref, candidate = record_ref(item["record"]), portable(item["candidate"])
+        if ref["id"] in seen_records:
+            raise ValueError("Duplicate canonical assertion record")
+        seen_records.add(ref["id"])
+        evidence = candidate.get("evidence", [])
+        if not evidence:
+            raise ValueError("An assertion requires retained located evidence")
+        aliases = []
+        for index, evidence_item in enumerate(evidence):
+            if not isinstance(evidence_item.get("quote"), str) or not evidence_item.get("quote"):
+                raise ValueError("The actual candidate's exact evidence quote is required")
+            alias = opaque("EVIDENCE", {"assertion": ref, "index": index, "evidence": evidence_item})
+            aliases.append(alias)
+            mapping["chunks"][alias] = {"assertion": ref, "evidence": evidence_item}
+            result["chunks"].append({"content": evidence_item["quote"], "source_id": alias,
+                                     "file_path": evidence_item.get("ref", "retained-evidence:" + alias),
+                                     "chunk_order_index": index})
+
+        # Endpoints returned by the real runner use resolved canonical records.
+        # A source-local candidate ID is not a canonical identity decision.
+        endpoints = item.get("endpoints", {})
+        participants = []
+        for role, field in [("subject", "subjectId"), ("object", "objectId")]:
+            if candidate.get(field) is None:
+                continue
+            endpoint = endpoints.get(role)
+            if endpoint is None:
+                raise ValueError("The runner's resolved endpoint record is required")
+            endpoint = record_ref(endpoint)
+            name = entity_by_record.get((endpoint["id"], endpoint["digest"]))
+            if name is None:
+                # Existing identities can resolve outside selected semanticEntities.
+                # Do not invent their type/label; host must hydrate them explicitly.
+                hydrated = project.get("resolvedEntities", [])
+                selected = [entity for entity in hydrated if entity.get("record") == endpoint]
+                if len(selected) != 1:
+                    raise ValueError("A resolved canonical endpoint needs exact owner-hydrated identity data")
+                entity = selected[0]
+                name = opaque("ENTITY", endpoint)
+                entity_by_record[(endpoint["id"], endpoint["digest"])] = name
+                mapping["entities"][name] = portable(entity)
+                result["entities"].append({"entity_name": name, "entity_type": entity["type"],
+                    "description": encoded({"label": entity["label"], "record": endpoint}).decode()})
+                losses.append("Hydrated endpoint " + endpoint["id"] + " has no native source chunk; authority stays in exact canonical record")
+            participants.append((role, name, endpoint))
+        assertion_name = opaque("ASSERTION", ref)
+        mapping["assertions"][assertion_name] = portable(item)
+        description = encoded({"record": ref, "candidate": candidate,
+                               "endpoints": endpoints}).decode()
+        if profile == "assertion-incidence":
+            result["entities"].append({"entity_name": assertion_name, "entity_type": "DERIVED_ASSERTION",
+                                       "description": description, "source_id": aliases[0]})
+            for role, entity_name, endpoint in participants:
+                role_name = opaque("ROLE", {"assertion": ref, "role": role})
+                mapping["roles"][role_name] = {"assertion": ref, "role": role, "entity": endpoint}
+                result["entities"].append({"entity_name": role_name, "entity_type": "DERIVED_ROLE_BINDING",
+                    "description": encoded(mapping["roles"][role_name]).decode(), "source_id": aliases[0]})
+                for source, target in [(assertion_name, role_name), (role_name, entity_name)]:
+                    result["relationships"].append({"src_id": source, "tgt_id": target,
+                        "description": description, "keywords": candidate["predicate"] + "," + role,
+                        "source_id": aliases[0], "weight": 1.0})
+        else:
+            if len(participants) != 2 or participants[0][1] == participants[1][1]:
+                losses.append("Adjacency omitted native edge for unary/self assertion " + ref["id"])
+                continue
+            pair = tuple(sorted([participants[0][1], participants[1][1]]))
+            adjacency_pairs.setdefault(pair, []).append(ref)
+            result["relationships"].append({"src_id": participants[0][1], "tgt_id": participants[1][1],
+                "description": description, "keywords": candidate["predicate"],
+                "source_id": aliases[0], "weight": 1.0})
+    if profile == "semantic-adjacency":
+        losses.append("Adjacency coalesces direction, predicates, negation, modality and time on a native pair")
+        for pair, refs in adjacency_pairs.items():
+            if len(refs) > 1:
+                losses.append("Native pair collapses assertions: " + ",".join(ref["id"] for ref in refs))
+    # Ensure entities have native source aliases when exact assertion evidence is available.
+    for entity in result["entities"]:
+        entity.setdefault("source_id", "")
+    return {"custom_kg": result, "mapping": mapping, "profile": profile,
+            "canonicalProjection": portable(project), "inputDigest": digest(project),
+            "losses": losses, "authority": "none", "canonicalMutation": False,
+            "nativeWeightMeaning": "native evidence floor/boost, never semantic confidence"}

package/src/ingestion/optional/lightrag/composition-binding.mjs

@@ -0,0 +1,67 @@
+import { isDeepStrictEqual } from 'node:util'
+
+const own = (value, key) => value && typeof value === 'object' ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value)
+const nonempty = value => typeof value === 'string' && value.length > 0
+const artifact = value => object(value) && nonempty(own(value, 'artifactId'))
+const sources = value => Array.isArray(value) && value.length > 0 && value.every(source => object(source) &&
+  ['sourceId', 'sourceDigest', 'attemptId'].every(key => nonempty(own(source, key))))
+
+export class LightRAGCompositionBindingError extends TypeError {
+  constructor(message, returned, { snapshotState = 'received', snapshotError = null } = {}) {
+    super(message, snapshotError ? { cause: snapshotError } : undefined)
+    this.name = 'LightRAGCompositionBindingError'
+    this.retainedReturn = returned
+    this.snapshotState = snapshotState
+    this.snapshotError = snapshotError
+    this.effectUncertain = true
+    this.retryAuthorized = false
+    // Failure data/costs are custody, never a successful host receipt identity.
+    for (const [key, value] of [['usage', own(own(returned, 'envelope'), 'usage') ?? null], ['supplierCosts', own(returned, 'costs') ?? null]]) {
+      try { this[key] = structuredClone(value) }
+      catch (error) { this[key] = value; this[`${key}SnapshotError`] = error }
+    }
+  }
+}
+
+/** Private host-dispatched binding; no Python/SDK process or receipt principal is
+ * constructed here. The actual host owns execution and the verified receipt bridge.
+ */
+export function createLightRAGCompositionBinding({ dispatch }) {
+  if (typeof dispatch !== 'function') throw new TypeError('Existing host supplier dispatch required')
+  const run = async (operation, payload) => {
+    // The host dispatches exactly one selected supplier query, canonical citation
+    // receiving, then receive_composition with its actual verified receipt owner.
+    const returned = await dispatch({ operation, payload })
+    let received
+    try { received = structuredClone(returned) }
+    catch (snapshotError) {
+      throw new LightRAGCompositionBindingError('Original supplier return could not be snapshotted', returned,
+        { snapshotState: 'failed', snapshotError })
+    }
+    const envelope = received?.envelope
+    if (received?.operation !== 'receive-composition' || received.outcome !== 'composition-envelope-received' ||
+        !object(envelope) || envelope.provider !== 'lightrag' || !nonempty(received.generationId) || envelope.generation !== received.generationId ||
+        envelope.nativeOperation !== operation || !envelope.receiptRef || !envelope.bridgeReceipt ||
+        envelope.receiptAssurance !== 'explicit-verified-existing-host-bridge' ||
+        !artifact(received.supplierQueryReceipt) || !artifact(received.supplierReceivingReceipt) ||
+        !artifact(received.envelopeArtifact) || !artifact(received.artifact) ||
+        !artifact(envelope.supplierQueryReceipt) || !artifact(envelope.supplierReceivingReceipt) || !artifact(envelope.artifactRef) ||
+        !sources(received.sourceBindings) || !sources(envelope.sourceBindings) ||
+        !Array.isArray(envelope.hits) || !Array.isArray(envelope.unresolvedReferences) ||
+        !isDeepStrictEqual(envelope.artifactRef, received.supplierReceivingReceipt) ||
+        !isDeepStrictEqual(envelope.supplierReceivingReceipt, received.supplierReceivingReceipt) ||
+        !isDeepStrictEqual(envelope.supplierQueryReceipt, received.supplierQueryReceipt) ||
+        !isDeepStrictEqual(envelope.sourceBindings, received.sourceBindings)) {
+      throw new LightRAGCompositionBindingError('Original supplier descriptors, source binding/capture and actual verified host receipt bridge required', received)
+    }
+    if (operation === 'answer' && !envelope.nativeResult?.llm_response) throw new LightRAGCompositionBindingError('Original coupled native answer required', received)
+    return structuredClone(envelope)
+  }
+  return Object.freeze({
+    bindings: Object.freeze({ retrieve: payload => run('retrieve', payload), nativeAnswer: payload => run('answer', payload) }),
+    operationRoles: Object.freeze({ retrieve: 'retrieve', nativeAnswer: 'native-answer' }),
+    hostRequired: Object.freeze(['single-selected-supplier-query', 'existing-canonical-citation-hydration',
+      'existing-current-source-and-quote-support', 'actual-verified-host-receipt-bridge']),
+  })
+}

package/src/ingestion/optional/vanilla/composition-binding.mjs

@@ -0,0 +1,102 @@
+import { createVanillaIngestionBridge, normalizeCandidateJson, readVanillaCapture, VanillaIngestionError } from './index.mjs'
+
+const check = (value, message) => { if (!value) throw new VanillaIngestionError('VANILLA_COMPOSITION_BINDING', message) }
+
+/** Private host adapter for the parent's createComposition callable interface.
+ * Receipt references come from the host, not from a new supplier receipt owner.
+ */
+export function createVanillaCompositionBinding({ runner, captureAttempt, extract,
+  normalize = normalizeCandidateJson, receiptFor, now, monotonic }) {
+  check(typeof extract === 'function' && typeof receiptFor === 'function', 'Existing host extractor and receipt-reference callback are required')
+  check(typeof runner?.context === 'function', 'The existing fresh knowledge context owner is required')
+  const bridge = createVanillaIngestionBridge({ runner, captureAttempt, now, monotonic })
+
+  async function bound(operationId) {
+    const status = await runner.status({ operationId })
+    check(status.phase === 'completed' && status.freshness === 'current', 'Current completed semantic operation is required')
+    const saved = readVanillaCapture(status)
+    return { status, operationBinding: {
+      operationId: status.operationId,
+      attemptId: status.attempt.attempt.attemptId,
+      inputDigest: status.input.digest,
+      domainRef: structuredClone(status.input.domainRef),
+      configurationDigest: status.extractor.configurationDigest,
+      completion: structuredClone(status.attempt.completion),
+      rawOutputDigest: saved.capture.raw.sha256,
+      historyDigest: status.head,
+      sourceReferences: status.input.evidence.map(span => structuredClone(span.reference)),
+    } }
+  }
+  async function receipt(operation, current, extra = {}) {
+    const receiptRef = await receiptFor({ operation, operationBinding: structuredClone(current.operationBinding),
+      usageAssurance: 'host-reported', authority: 'none', ...extra })
+    check(receiptRef !== undefined && receiptRef !== null && receiptRef !== '', 'Host must return its actual receipt/state reference')
+    return receiptRef
+  }
+  function operationId(input, extraction) {
+    const id = extraction?.operationBinding?.operationId ?? input?.resume?.operationId
+    check(typeof id === 'string' && id.length > 0, 'Use the actual extraction operation or an explicit saved operation')
+    return id
+  }
+  function query(input) {
+    check(typeof input?.proposalQuery === 'string' && input.proposalQuery.trim().length > 0, 'Explicit proposal query is required for the current knowledge view')
+    return input.proposalQuery
+  }
+
+  const extractOperation = async ({ input }, { signal } = {}) => {
+    check(Boolean(input?.begin) !== Boolean(input?.resume), 'Select one new reservation or one explicit saved-operation recovery')
+    const result = input.begin
+      ? await bridge.execute({ begin: input.begin, extract, normalize, signal })
+      : await bridge.resume({ operationId: input.resume.operationId, normalize, signal })
+    // A cache hit can return an older operation ID than the requested new one.
+    // Bind the actual runner result, never the caller's requested reservation.
+    const current = await bound(result.status.operationId)
+    return { result, operationBinding: current.operationBinding,
+      receiptRef: await receipt('extract', current, { cacheReuse: result.cacheReuse }),
+      usage: result.cacheReuse ? null : current.status.usage,
+      captureUsage: current.status.usage, cacheReuse: result.cacheReuse,
+      receiptAssurance: 'host-reference-to-existing-state', authority: 'none', semanticAcceptance: 'pending' }
+  }
+
+  const readKnowledgeView = async ({ requestedView, input, extraction }) => {
+    check(['native-exploration', 'accepted-knowledge'].includes(requestedView), 'Select an existing knowledge view')
+    const current = await bound(operationId(input, extraction)), selectedQuery = query(input)
+    // A domain reference identifies existing ledger/domain custody. It does not
+    // authenticate a human receiver or assert that any candidate was admitted.
+    const knowledgeView = requestedView === 'native-exploration'
+      ? await runner.proposals({ operationId: current.status.operationId, query: selectedQuery })
+      : await runner.context({ query: selectedQuery })
+    return { kind: requestedView, ownerRef: current.status.input.domainRef,
+      ownerRefSemantics: 'existing-knowledge-domain-reference', operationBinding: current.operationBinding,
+      knowledgeView, authority: 'none', canonicalMutation: false }
+  }
+
+  const retrieveOperation = async ({ input, question, view }) => {
+    check(view?.kind === 'native-exploration', 'This located proposal retriever serves native exploration only; accepted context stays with its receiver')
+    const current = await bound(view.operationBinding?.operationId)
+    // Revalidate evidence at retrieval, rather than serving a captured view object.
+    const proposalView = await runner.proposals({ operationId: current.status.operationId,
+      query: typeof question === 'string' && question.trim() ? question : query(input) })
+    const hits = proposalView.assertions.flatMap(assertion => assertion.evidence.map(citation => ({
+      evidenceRef: { sourceId: citation.sourceId, revision: citation.sourceDigest,
+        representationId: citation.attemptId, locator: structuredClone(citation.locator) },
+      quote: citation.quote, assertion: structuredClone(assertion),
+      score: null, scoreSemantics: 'literal-pending-proposal-match', semanticAcceptance: 'pending',
+    })))
+    return { hits, proposalView, operationBinding: current.operationBinding,
+      generation: proposalView.inputDigest,
+      artifactRef: { attemptId: current.operationBinding.attemptId,
+        outputDigest: current.operationBinding.completion.outputDigest },
+      receiptRef: await receipt('retrieve', current, { viewBinding: {
+        inputDigest: proposalView.inputDigest, domainRef: proposalView.domainRef,
+        answerClass: proposalView.answerClass, query: question ?? input.proposalQuery,
+      } }),
+      usage: null, receiptAssurance: 'host-reference-to-existing-state',
+      coverage: proposalView.coverage, readScope: proposalView.readScope,
+      authority: 'none', canonicalMutation: false, semanticAcceptance: 'pending' }
+  }
+  return Object.freeze({ bindings: Object.freeze({ extract: extractOperation, retrieve: retrieveOperation }),
+    // Private execution declaration for the receiver's own-property role checks.
+    // This does not register a capability or establish admission authority.
+    operationRoles: Object.freeze({ extract: 'extract', retrieve: 'retrieve' }), readKnowledgeView })
+}

package/src/ingestion/optional/vanilla/index.mjs

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto'
+import { performance } from 'node:perf_hooks'
+
+// Private supplier serialization, not an ontology, ledger, or public contract.
+export const VANILLA_CAPTURE_FORMAT = 'atelier.vanilla-extraction-capture/v0'
+export const MAX_CAPTURE_BYTES = 16 * 1024 * 1024 // Existing intake UTF-8 ceiling.
+const digest = bytes => createHash('sha256').update(bytes).digest('hex')
+const fields = ['inputTokens', 'outputTokens', 'cost', 'currency', 'elapsedMs', 'retries']
+
+export class VanillaIngestionError extends Error {
+  constructor(code, message, { cause, recovery, recorded, captured, attemptedCapture, uncaptured } = {}) {
+    super(message, { cause }); this.name = 'VanillaIngestionError'; this.code = code
+    if (recovery) this.recovery = recovery
+    if (recorded) this.recorded = recorded
+    if (captured) this.captured = captured
+    if (attemptedCapture) this.attemptedCapture = attemptedCapture
+    if (uncaptured) this.uncaptured = uncaptured
+  }
+}
+function check(value, code, message) { if (!value) throw new VanillaIngestionError(code, message) }
+function ownData(value, key) {
+  if (value === null || !['object', 'function'].includes(typeof value)) return undefined
+  try { return Object.getOwnPropertyDescriptor(value, key)?.value } catch { return undefined }
+}
+function same(left, right) {
+  // Object key order is not an intake or runner receipt contract.
+  const stable = value => value === null || typeof value !== 'object' ? JSON.stringify(value)
+    : Array.isArray(value) ? `[${value.map(stable).join(',')}]`
+      : `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`
+  return stable(left) === stable(right)
+}
+function rawBytes(output) {
+  check(typeof output === 'string' || output instanceof Uint8Array, 'VANILLA_OUTPUT', 'Extractor output must be text or bytes')
+  return Buffer.from(output) // Copy: the host cannot mutate the captured buffer later.
+}
+function captureFor(status, output, suppliedUsage, elapsedMs) {
+  const bytes = rawBytes(output)
+  const usage = Object.fromEntries(fields.map(key => [key, suppliedUsage?.[key] ?? (key === 'elapsedMs' ? elapsedMs : null)]))
+  for (const value of Object.values(usage)) check(typeof value !== 'number' || Number.isFinite(value),
+    'VANILLA_USAGE_ENCODING', 'Nonfinite reported usage cannot be losslessly encoded; retain returned bytes and settle host accounting')
+  const capture = {
+    format: VANILLA_CAPTURE_FORMAT,
+    inputDigest: status.input.digest,
+    extractor: status.extractor,
+    raw: { encoding: 'base64', bytes: bytes.length, sha256: digest(bytes), data: bytes.toString('base64') },
+    usage, usageAssurance: 'host-reported',
+    timing: { extractionElapsedMs: elapsedMs, assurance: 'host-measured-monotonic' },
+    coverage: status.input.coverage,
+  }
+  const outputEnvelope = JSON.stringify(capture)
+  check(Buffer.byteLength(outputEnvelope) <= MAX_CAPTURE_BYTES, 'VANILLA_CAPTURE_LIMIT', 'Capture exceeds the existing intake byte ceiling')
+  return { capture, outputEnvelope, outputDigest: digest(outputEnvelope) }
+}
+
+/** Verify the immutable wrapper and exact producer/input pins before reuse. */
+export function readVanillaCapture(status) {
+  check(['partial', 'complete'].includes(status?.attempt?.status) && typeof status.attempt.output === 'string', 'VANILLA_CAPTURE_MISSING', 'No saved extraction bytes are available')
+  const outputEnvelope = status.attempt.output
+  check(Buffer.byteLength(outputEnvelope) <= MAX_CAPTURE_BYTES, 'VANILLA_CAPTURE_LIMIT', 'Saved capture exceeds the intake ceiling')
+  let capture
+  try { capture = JSON.parse(outputEnvelope) } catch (cause) { throw new VanillaIngestionError('VANILLA_CAPTURE_INTEGRITY', 'Saved output is not a vanilla capture', { cause }) }
+  check(capture?.format === VANILLA_CAPTURE_FORMAT && capture.inputDigest === status.input.digest &&
+    same(capture.extractor, status.extractor) && capture.coverage === status.input.coverage &&
+    capture.usageAssurance === 'host-reported' && same(Object.keys(capture.usage ?? {}).sort(), [...fields].sort()),
+  'VANILLA_CAPTURE_INTEGRITY', 'Capture producer, input, coverage or usage pins differ')
+  const raw = capture.raw
+  check(raw?.encoding === 'base64' && typeof raw.data === 'string' && Number.isSafeInteger(raw.bytes) && raw.bytes >= 0,
+    'VANILLA_CAPTURE_INTEGRITY', 'Capture must retain exact encoded raw bytes')
+  const bytes = Buffer.from(raw.data, 'base64')
+  check(bytes.toString('base64') === raw.data && bytes.length === raw.bytes && digest(bytes) === raw.sha256,
+    'VANILLA_CAPTURE_INTEGRITY', 'Extractor raw-byte digest differs')
+  const outputDigest = digest(outputEnvelope)
+  check(status.attempt.status !== 'complete' || status.attempt.completion?.outputDigest === outputDigest,
+    'VANILLA_CAPTURE_INTEGRITY', 'Intake envelope digest differs')
+  if (status.phase === 'completed') check(same(status.usage, capture.usage), 'VANILLA_CAPTURE_INTEGRITY', 'Recorded usage differs from immutable capture')
+  return { capture, bytes, outputEnvelope, outputDigest }
+}
+
+export function normalizeCandidateJson({ bytes }) {
+  return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes))
+}
+
+/** A provider-free authored/deterministic callback; vocabulary remains host-owned. */
+export function createCandidateExtractor(buildCandidates) {
+  check(typeof buildCandidates === 'function', 'VANILLA_EXTRACTOR', 'A candidate authoring function is required')
+  return async ({ input, extractor, signal }) => {
+    check(['authored', 'deterministic'].includes(extractor.route), 'VANILLA_EXTRACTOR', 'This helper only implements provider-free routes')
+    const candidates = await buildCandidates({ input, signal })
+    return { output: JSON.stringify(candidates), usage: { inputTokens: 0, outputTokens: 0, cost: 0, currency: null, retries: 0 } }
+  }
+}
+
+/** Host composition supplies the existing createSemanticOperation result. */
+export function createVanillaIngestionBridge({ runner, captureAttempt = null, now = () => new Date().toISOString(), monotonic = () => performance.now() }) {
+  for (const method of ['begin', 'status', 'complete', 'proposals']) check(typeof runner?.[method] === 'function', 'VANILLA_RUNNER', `Existing semantic runner.${method} is required`)
+  check(captureAttempt === null || typeof captureAttempt === 'function', 'VANILLA_CAPTURE', 'The existing intake completion callback is required when supplied')
+  function notAborted(signal) { check(!signal?.aborted, 'VANILLA_ABORTED', 'Host cancelled extraction or interpretation; reopen saved state') }
+  async function failure(error, operationId, stage, extra = {}) {
+    let status = null
+    try { status = await runner.status({ operationId }) } catch { /* Never erase original saved receipts. */ }
+    let captured = extra.captured
+    const attemptedCapture = extra.attemptedCapture ?? ownData(error, 'captured')
+    const expectedOutputDigest = extra.expectedOutputDigest ?? ownData(ownData(attemptedCapture, 'completion'), 'outputDigest')
+    const expectedAttemptId = extra.expectedAttemptId ?? ownData(attemptedCapture, 'attemptId')
+    if (!captured && !extra.captureReadbackFailed && (expectedOutputDigest || stage === 'recovery') &&
+      ['partial', 'complete'].includes(status?.attempt?.status)) {
+      try {
+        const saved = readVanillaCapture(status)
+        if (status.operationId === operationId && (!expectedOutputDigest || saved.outputDigest === expectedOutputDigest) &&
+          (!expectedAttemptId || status.attempt.attempt.attemptId === expectedAttemptId)) captured = { attemptId: status.attempt.attempt.attemptId,
+          completion: status.attempt.completion, head: status.head, nextAction: 'reopen-captured-output' }
+      } catch { /* Unverified readback is never presented as a saved receipt. */ }
+    }
+    const code = ownData(error, 'code'), message = ownData(error, 'message')
+    return new VanillaIngestionError(typeof code === 'string' ? code : 'VANILLA_INTERRUPTED', typeof message === 'string' ? message : 'Host operation was interrupted', {
+      cause: error, recorded: ownData(error, 'recorded'), captured, attemptedCapture, uncaptured: captured ? undefined : extra.uncaptured,
+      recovery: { operationId, stage, phase: status?.phase ?? null, execution: status?.execution ?? 'unknown',
+        nextAction: captured ? 'resume-interpretation-from-capture' : 'inspect-and-explicitly-reconcile-execution',
+        extractorMayRunAgain: false },
+    })
+  }
+  async function verifyCapture({ operationId, attemptId, expectedOutputDigest, completion }) {
+    const reread = await runner.status({ operationId })
+    const verified = readVanillaCapture(reread)
+    check(reread.operationId === operationId && reread.attempt.attempt.attemptId === attemptId &&
+      reread.attempt.status === 'complete' && verified.outputDigest === expectedOutputDigest && same(completion, reread.attempt.completion),
+    'VANILLA_CAPTURE_INTEGRITY', 'Existing intake completion readback differs')
+    return { attemptId, completion: reread.attempt.completion, head: reread.head, nextAction: 'reopen-captured-output' }
+  }
+  async function result(status, { query, proposals = null, cacheReuse = false } = {}) {
+    check(status.freshness === 'current', 'VANILLA_STALE', 'Saved extraction is stale; use a new structural plan and extraction operation')
+    const saved = readVanillaCapture(status)
+    return { status, capture: saved.capture, proposals,
+      proposalView: query === undefined ? null : await runner.proposals({ operationId: status.operationId, query }),
+      cacheReuse, coverage: status.input.coverage, readScope: status.input.readScope,
+      sourceReferences: status.input.evidence.map(span => span.reference),
+      semanticAcceptance: 'pending', canonicalMutation: false, authority: 'none' }
+  }
+  async function interpret(status, { normalize, query, signal }) {
+    check(status.freshness === 'current', 'VANILLA_STALE', 'Captured output is retained but its source or domain is stale')
+    const saved = readVanillaCapture(status)
+    if (status.phase === 'completed') return result(status, { query, cacheReuse: true })
+    check(status.phase === 'reserved', 'VANILLA_RECOVERY_REQUIRED', 'Only a reserved capture may finish interpretation')
+    notAborted(signal)
+    const candidates = await normalize({ bytes: Buffer.from(saved.bytes), input: structuredClone(status.input), extractor: structuredClone(status.extractor) })
+    notAborted(signal)
+    // Reopen after asynchronous normalization. The actual runner rechecks source,
+    // input, immutable raw bytes and history before recording candidates.
+    const current = await runner.status({ operationId: status.operationId })
+    if (current.phase === 'completed') return result(current, { query, cacheReuse: true })
+    check(current.freshness === 'current', 'VANILLA_STALE', 'Source or adopted domain changed during interpretation')
+    const completed = await runner.complete({ operationId: status.operationId, output: saved.outputEnvelope,
+      expectedOutputDigest: saved.outputDigest, candidates, usage: saved.capture.usage, at: now(), confirm: current.head })
+    return result(completed, { query, proposals: completed.proposals })
+  }
+  async function execute({ begin, extract, normalize = normalizeCandidateJson, query, signal }) {
+    check(typeof extract === 'function' && typeof normalize === 'function', 'VANILLA_EXTRACTOR', 'Host extraction and pure normalization callbacks are required')
+    notAborted(signal)
+    let ready, extracted, retainedOutput, saved, captured, attemptedCapture, captureReadbackFailed = false, stage = 'reservation'
+    try {
+      ready = await runner.begin(begin)
+      if (ready.cacheReuse) return await result(ready, { query, cacheReuse: true })
+      check(ready.execution === 'ready-for-host', 'VANILLA_EXECUTION_UNKNOWN', 'Only a new ready reservation permits host extraction')
+      notAborted(signal); stage = 'extraction'
+      const started = monotonic()
+      extracted = await extract({ input: structuredClone(ready.input), extractor: structuredClone(ready.extractor), signal,
+        limits: { maxCaptureBytes: MAX_CAPTURE_BYTES, rawEncoding: 'base64' } })
+      const elapsedMs = Math.max(0, Math.round(monotonic() - started))
+      stage = 'capture'
+      retainedOutput = { output: rawBytes(extracted?.output), usage: structuredClone(extracted?.usage) }
+      saved = captureFor(ready, extracted?.output, extracted?.usage, elapsedMs)
+      const current = await runner.status({ operationId: ready.operationId })
+      if (captureAttempt) {
+        // The manifest is the runner's reservation. Capture uses that same
+        // existing intake owner; runner.complete subsequently verifies it again.
+        const attemptId = current.attempt.attempt?.attemptId
+        check(current.phase === 'reserved' && attemptId === ready.attempt.attempt.attemptId,
+          'VANILLA_CAPTURE_INTEGRITY', 'Capture requires the original reserved intake manifest')
+        attemptedCapture = { attemptId, expectedOutputDigest: saved.outputDigest, head: current.head, nextAction: 'inspect-capture-custody' }
+        attemptedCapture.completion = await captureAttempt({ attemptId, output: saved.outputEnvelope, expectedOutputDigest: saved.outputDigest })
+        stage = 'capture-readback'; captureReadbackFailed = true
+        captured = await verifyCapture({ operationId: ready.operationId, attemptId, expectedOutputDigest: saved.outputDigest, completion: attemptedCapture.completion })
+        captureReadbackFailed = false
+      } else {
+        // Runner-only compatibility fallback. There is currently no runner
+        // capture-only method; absent candidates produce an expected refusal.
+        try {
+          await runner.complete({ operationId: ready.operationId, output: saved.outputEnvelope, expectedOutputDigest: saved.outputDigest,
+            candidates: null, usage: saved.capture.usage, at: now(), confirm: current.head })
+          throw new VanillaIngestionError('VANILLA_RUNNER_PROFILE', 'Runner unexpectedly admitted absent candidates')
+        } catch (error) {
+          const receipt = ownData(error, 'captured')
+          if (!receipt) throw error
+          attemptedCapture = receipt
+          if (ownData(error, 'code') !== 'SEMANTIC_INVALID') throw error
+          stage = 'capture-readback'; captureReadbackFailed = true
+          captured = await verifyCapture({ operationId: ready.operationId, attemptId: ready.attempt.attempt.attemptId,
+            expectedOutputDigest: saved.outputDigest, completion: ownData(receipt, 'completion') })
+          captureReadbackFailed = false
+        }
+      }
+      stage = 'interpretation'
+      return await interpret(await runner.status({ operationId: ready.operationId }), { normalize, query, signal })
+    } catch (error) {
+      throw await failure(error, ready?.operationId ?? begin?.operationId, stage,
+        { captured, attemptedCapture, captureReadbackFailed, expectedOutputDigest: saved?.outputDigest,
+          expectedAttemptId: ready?.attempt?.attempt?.attemptId,
+          uncaptured: stage.startsWith('capture') && !captured && extracted ? retainedOutput ?? extracted : undefined })
+    }
+  }
+  // No extractor argument by design: recovery cannot charge extraction again.
+  async function resume({ operationId, normalize = normalizeCandidateJson, query, signal }) {
+    check(typeof normalize === 'function', 'VANILLA_EXTRACTOR', 'A pure normalization callback is required')
+    try { return await interpret(await runner.status({ operationId }), { normalize, query, signal }) }
+    catch (error) { throw await failure(error, operationId, 'recovery') }
+  }
+  return Object.freeze({ execute, resume })
+}