@fortemi/core 2026.8.0 → 2026.9.1

package/dist/index.js

@@ -2,14 +2,1081 @@ import { v7, v5 } from 'uuid';
 import { sha256 } from '@noble/hashes/sha256';
 import { blake3 } from '@noble/hashes/blake3';
 import { bytesToHex } from '@noble/hashes/utils';
+import Ajv20202 from 'ajv/dist/2020.js';
 import { z } from 'zod';
 import { gzipSync, gunzipSync } from 'fflate';
-import Ajv2020 from 'ajv/dist/2020.js';
 
 // src/uuid.ts
 function generateId() {
   return v7();
 }
+function computeHash(data) {
+  const digest2 = sha256(data);
+  return `sha256:${bytesToHex(digest2)}`;
+}
+function computeBlobHash(data) {
+  return `blake3:${bytesToHex(blake3(data))}`;
+}
+
+// src/dataset-ingest.ts
+var DATASET_INGEST_CONTRACT = "fortemi.dataset-ingest/v1";
+var DATASET_INGEST_SCHEMA_VERSION = "1.0.0";
+var DatasetIngestError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DatasetIngestError";
+  }
+};
+function clone(value) {
+  return structuredClone(value);
+}
+var MemoryDatasetIngestStore = class {
+  scopes = /* @__PURE__ */ new Map();
+  queues = /* @__PURE__ */ new Map();
+  async transact(scopeKey, operation) {
+    const predecessor = this.queues.get(scopeKey) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+      release = resolve;
+    });
+    const queued = predecessor.then(() => current);
+    this.queues.set(scopeKey, queued);
+    await predecessor;
+    try {
+      const existing = this.scopes.get(scopeKey) ?? {
+        records: /* @__PURE__ */ new Map(),
+        receipts: /* @__PURE__ */ new Map()
+      };
+      const draft = {
+        records: new Map([...existing.records].map(([key, value]) => [key, clone(value)])),
+        receipts: new Map([...existing.receipts].map(([key, value]) => [key, clone(value)])),
+        ...existing.checkpoint ? { checkpoint: clone(existing.checkpoint) } : {}
+      };
+      const transaction = {
+        getRecord: (id) => draft.records.get(id),
+        setRecord: (record) => draft.records.set(record.logicalId, clone(record)),
+        getReceipt: (key) => draft.receipts.get(key),
+        setReceipt: (receipt) => draft.receipts.set(receipt.idempotencyKey, clone(receipt)),
+        getCheckpoint: () => draft.checkpoint,
+        setCheckpoint: (checkpoint) => {
+          draft.checkpoint = clone(checkpoint);
+        }
+      };
+      const result = await operation(transaction);
+      this.scopes.set(scopeKey, draft);
+      return result;
+    } finally {
+      release();
+      if (this.queues.get(scopeKey) === queued) this.queues.delete(scopeKey);
+    }
+  }
+  async getReceipt(scopeKey, idempotencyKey) {
+    return clone(this.scopes.get(scopeKey)?.receipts.get(idempotencyKey));
+  }
+  async getCheckpoint(scopeKey) {
+    return clone(this.scopes.get(scopeKey)?.checkpoint);
+  }
+  async getRecords(scopeKey) {
+    return [...this.scopes.get(scopeKey)?.records.values() ?? []].map(clone).sort((a, b) => a.logicalId.localeCompare(b.logicalId));
+  }
+};
+function canonicalJson(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+}
+function digest(value) {
+  return computeHash(new TextEncoder().encode(canonicalJson(value)));
+}
+function datasetDestinationScopeKey(scope) {
+  return [scope.tenant, scope.dataset, scope.sourceBinding, scope.stream, scope.partition ?? ""].map(encodeURIComponent).join("/");
+}
+function deriveDatasetIngestIdempotencyKey(plan, batch) {
+  if (batch.idempotencyKey) return batch.idempotencyKey;
+  return digest({
+    contract: DATASET_INGEST_CONTRACT,
+    planId: plan.planId,
+    planDigest: plan.planDigest,
+    sourceRevision: plan.sourceRevision,
+    configurationDigest: plan.configurationDigest,
+    transformationDigest: plan.transformationDigest,
+    destination: plan.destination,
+    mode: plan.mode,
+    sequence: batch.sequence,
+    checkpointBefore: batch.checkpointBefore,
+    checkpointAfter: batch.checkpointAfter,
+    mutations: batch.mutations
+  });
+}
+function assertContract(plan, batch) {
+  if (plan.contract !== DATASET_INGEST_CONTRACT || batch.contract !== DATASET_INGEST_CONTRACT) {
+    throw new DatasetIngestError("INGEST_CONTRACT_UNSUPPORTED", "Unsupported dataset ingest contract");
+  }
+  if (!plan.schemaVersion.startsWith("1.") || !batch.schemaVersion.startsWith("1.")) {
+    throw new DatasetIngestError("INGEST_SCHEMA_UNSUPPORTED", "Unsupported dataset ingest schema version");
+  }
+}
+function assertCheckpointScope(checkpoint, scope) {
+  if (checkpoint.contract !== DATASET_INGEST_CONTRACT) throw new DatasetIngestError("INGEST_CONTRACT_UNSUPPORTED", "Unsupported checkpoint contract");
+  if (!checkpoint.schemaVersion.startsWith("1.")) throw new DatasetIngestError("CHECKPOINT_VERSION_UNSUPPORTED", `Unsupported checkpoint schema ${checkpoint.schemaVersion}`);
+  if (datasetDestinationScopeKey(checkpoint.scope) !== datasetDestinationScopeKey(scope)) {
+    throw new DatasetIngestError("CHECKPOINT_SCOPE_MISMATCH", "Checkpoint belongs to another destination scope");
+  }
+}
+var DatasetIngestExecutor = class {
+  constructor(store) {
+    this.store = store;
+  }
+  attempts = /* @__PURE__ */ new Map();
+  successes = /* @__PURE__ */ new Map();
+  preview(plan, batch) {
+    assertContract(plan, batch);
+    return {
+      idempotencyKey: deriveDatasetIngestIdempotencyKey(plan, batch),
+      upserts: batch.mutations.filter((item) => item.operation === "upsert").length,
+      tombstones: batch.mutations.filter((item) => item.operation === "tombstone").length
+    };
+  }
+  connectionCheck(plan, batch) {
+    assertContract(plan, batch);
+    assertCheckpointScope(batch.checkpointAfter, plan.destination);
+    if (batch.checkpointBefore) assertCheckpointScope(batch.checkpointBefore, plan.destination);
+    return {
+      idempotencyKey: deriveDatasetIngestIdempotencyKey(plan, batch),
+      scopeKey: datasetDestinationScopeKey(plan.destination),
+      compatible: true
+    };
+  }
+  async executeBatch(plan, batch, options = {}) {
+    assertContract(plan, batch);
+    const scopeKey = datasetDestinationScopeKey(plan.destination);
+    const idempotencyKey = deriveDatasetIngestIdempotencyKey(plan, batch);
+    const requestDigest = digest({ plan, batch });
+    const runId = generateId();
+    this.attempts.set(scopeKey, { runId, state: "running", verification: "pending", idempotencyKey });
+    const cancel = () => {
+      if (options.signal?.aborted) throw new DatasetIngestError("INGEST_CANCELLED", "Dataset ingest was cancelled before commit");
+    };
+    try {
+      cancel();
+      const receipt = await this.store.transact(scopeKey, async (transaction) => {
+        const prior = transaction.getReceipt(idempotencyKey);
+        if (prior) {
+          if (prior.requestDigest !== requestDigest) throw new DatasetIngestError("IDEMPOTENCY_CONFLICT", "Idempotency key was previously used with different canonical content");
+          return prior;
+        }
+        const currentCheckpoint = transaction.getCheckpoint();
+        if (batch.checkpointBefore) {
+          assertCheckpointScope(batch.checkpointBefore, plan.destination);
+          if (!currentCheckpoint || canonicalJson(currentCheckpoint) !== canonicalJson(batch.checkpointBefore)) {
+            throw new DatasetIngestError("CHECKPOINT_MISMATCH", "checkpointBefore does not match committed state");
+          }
+        } else if (currentCheckpoint) {
+          throw new DatasetIngestError("CHECKPOINT_MISMATCH", "A committed checkpoint exists but checkpointBefore was omitted");
+        }
+        assertCheckpointScope(batch.checkpointAfter, plan.destination);
+        if (batch.checkpointAfter.sequence !== batch.sequence) throw new DatasetIngestError("BATCH_OUT_OF_ORDER", "Checkpoint sequence must equal batch sequence");
+        if (currentCheckpoint && batch.checkpointAfter.sequence <= currentCheckpoint.sequence) throw new DatasetIngestError("CHECKPOINT_REGRESSION", "Checkpoint sequence must advance");
+        const expectedSequence = (currentCheckpoint?.sequence ?? 0) + 1;
+        if (batch.sequence !== expectedSequence) throw new DatasetIngestError("BATCH_OUT_OF_ORDER", `Expected batch sequence ${expectedSequence}, received ${batch.sequence}`);
+        const tombstones = batch.mutations.filter((item) => item.operation === "tombstone").length;
+        if (tombstones > 0) {
+          if (!plan.reconciliation.enabled) throw new DatasetIngestError("RECONCILIATION_NOT_ENABLED", "Tombstones require reconciliation policy");
+          if (!batch.enumeration?.complete) throw new DatasetIngestError("RECONCILIATION_INCOMPLETE", "Tombstones require complete source enumeration");
+          if (tombstones > plan.reconciliation.maxTombstones && !batch.enumeration.approvalId) {
+            throw new DatasetIngestError("RECONCILIATION_APPROVAL_REQUIRED", `Tombstone count ${tombstones} exceeds approved threshold`);
+          }
+        }
+        const rejections = [];
+        const accepted = [];
+        for (const mutation of batch.mutations) {
+          cancel();
+          const failure2 = options.validateRecord?.(mutation);
+          if (!failure2) {
+            accepted.push(mutation);
+            continue;
+          }
+          const rejection = {
+            logicalIdDigest: digest(mutation.logicalId),
+            ...mutation.locator ? { locator: mutation.locator } : {},
+            code: failure2.code,
+            message: "Record rejected by validation policy"
+          };
+          if (plan.rejectionPolicy.mode === "fail-fast") throw new DatasetIngestError("RECORD_REJECTED", `${failure2.code}: record rejected`);
+          rejections.push(rejection);
+          if (rejections.length > plan.rejectionPolicy.maxRejectedRecords) throw new DatasetIngestError("REJECTION_LIMIT_EXCEEDED", "Rejected-record limit exceeded");
+        }
+        cancel();
+        for (const mutation of accepted) {
+          transaction.setRecord(mutation.operation === "upsert" ? { logicalId: mutation.logicalId, revision: mutation.revision, digest: mutation.digest, value: clone(mutation.value), tombstoned: false } : { logicalId: mutation.logicalId, revision: mutation.revision, digest: mutation.digest, tombstoned: true });
+        }
+        const effects = accepted.map(({ operation, logicalId, revision, digest: itemDigest }) => ({ operation, logicalId, revision, digest: itemDigest }));
+        const receipt2 = {
+          contract: DATASET_INGEST_CONTRACT,
+          schemaVersion: DATASET_INGEST_SCHEMA_VERSION,
+          runId,
+          idempotencyKey,
+          requestDigest,
+          planId: plan.planId,
+          planDigest: plan.planDigest,
+          sourceRevision: plan.sourceRevision,
+          destination: clone(plan.destination),
+          mode: plan.mode,
+          state: rejections.length ? "degraded" : "committed",
+          effects,
+          acceptedRecords: accepted.length,
+          rejectedRecords: rejections.length,
+          rejections,
+          outputDigest: digest(effects),
+          ...batch.checkpointBefore ? { checkpointBefore: clone(batch.checkpointBefore) } : {},
+          checkpointAfter: clone(batch.checkpointAfter),
+          verification: "verified"
+        };
+        await options.hooks?.beforeCommit?.();
+        cancel();
+        transaction.setReceipt(receipt2);
+        transaction.setCheckpoint(batch.checkpointAfter);
+        return receipt2;
+      });
+      this.successes.set(scopeKey, clone(receipt));
+      this.attempts.set(scopeKey, { runId: receipt.runId, state: receipt.state, verification: "verified", idempotencyKey });
+      await options.hooks?.afterCommit?.(clone(receipt));
+      return receipt;
+    } catch (error) {
+      const code = error instanceof DatasetIngestError ? error.code : void 0;
+      this.attempts.set(scopeKey, { runId, state: code === "INGEST_CANCELLED" ? "cancelled" : "failed", verification: "failed", idempotencyKey, ...code ? { errorCode: code } : {} });
+      throw error;
+    }
+  }
+  async resolveAmbiguousCommit(plan, batch) {
+    return this.store.getReceipt(datasetDestinationScopeKey(plan.destination), deriveDatasetIngestIdempotencyKey(plan, batch));
+  }
+  status(scope, expectedSourceRevision) {
+    const key = datasetDestinationScopeKey(scope);
+    const lastSuccessful = this.successes.get(key);
+    return {
+      scope: clone(scope),
+      ...this.attempts.get(key) ? { lastAttempt: clone(this.attempts.get(key)) } : {},
+      ...lastSuccessful ? { lastSuccessful: clone(lastSuccessful) } : {},
+      freshness: lastSuccessful ? expectedSourceRevision && expectedSourceRevision !== lastSuccessful.sourceRevision ? "stale" : "current" : "never"
+    };
+  }
+};
+
+// src/dataset-lineage.ts
+var DATASET_LINEAGE_CONTRACT = "fortemi.dataset-lineage/v1";
+var DATASET_LINEAGE_SCHEMA_VERSION = "1.0.0";
+var LINEAGE_ENTITY_KINDS = [
+  "dataset",
+  "dataset-revision",
+  "distribution",
+  "record",
+  "field",
+  "chunk",
+  "index",
+  "embedding-set",
+  "graph-artifact",
+  "community-artifact",
+  "processing-plan",
+  "run"
+];
+var LINEAGE_RELATIONSHIP_KINDS = [
+  "derived-from",
+  "field-derived-from",
+  "extracted-from",
+  "chunk-of",
+  "indexed-from",
+  "embedded-from",
+  "graph-derived-from",
+  "community-derived-from",
+  "revision-of",
+  "distributed-as",
+  "join-influence",
+  "filter-influence",
+  "aggregation-influence",
+  "ordering-influence",
+  "similarity-influence"
+];
+var LineageValidationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "LineageValidationError";
+  }
+};
+function canonicalJson2(value) {
+  if (value === void 0) return "null";
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson2).join(",")}]`;
+  const entries = Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right));
+  return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson2(item)}`).join(",")}}`;
+}
+function computeLineageDigest(value) {
+  return computeHash(new TextEncoder().encode(canonicalJson2(value)));
+}
+function clone2(value) {
+  return structuredClone(value);
+}
+function requireIdentity(id, label) {
+  if (!id || id.trim() !== id) throw new LineageValidationError("IDENTITY_REQUIRED", `${label} must be a non-empty canonical identity`);
+}
+function requireTimestamp(value, label) {
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value) || !Number.isFinite(Date.parse(value))) {
+    throw new LineageValidationError("VALUE_INVALID", `${label} must be an RFC 3339 UTC timestamp`);
+  }
+}
+var ENTITY_KIND_SET = new Set(LINEAGE_ENTITY_KINDS);
+var RELATIONSHIP_KIND_SET = new Set(LINEAGE_RELATIONSHIP_KINDS);
+var RELATIONSHIP_ENDPOINTS = {
+  "field-derived-from": [["field"], ["field"]],
+  "chunk-of": [["chunk"], ["record", "distribution"]],
+  "indexed-from": [["index"], ["dataset", "dataset-revision", "distribution", "record", "field", "chunk"]],
+  "embedded-from": [["embedding-set"], ["dataset", "dataset-revision", "record", "field", "chunk"]],
+  "graph-derived-from": [["graph-artifact"], ["dataset", "dataset-revision", "index", "embedding-set"]],
+  "community-derived-from": [["community-artifact"], ["graph-artifact"]],
+  "revision-of": [["dataset-revision"], ["dataset"]],
+  "distributed-as": [["dataset", "dataset-revision"], ["distribution"]]
+};
+var DatasetLineageLedger = class _DatasetLineageLedger {
+  sequence = 0;
+  entities = /* @__PURE__ */ new Map();
+  agents = /* @__PURE__ */ new Map();
+  activities = /* @__PURE__ */ new Map();
+  evidence = /* @__PURE__ */ new Map();
+  assertions = /* @__PURE__ */ new Map();
+  corrections = /* @__PURE__ */ new Map();
+  maximumTraversalDepth;
+  maximumTraversalResults;
+  maximumPageSize;
+  constructor(options = {}) {
+    this.maximumTraversalDepth = options.maximumTraversalDepth ?? 16;
+    this.maximumTraversalResults = options.maximumTraversalResults ?? 1e4;
+    this.maximumPageSize = options.maximumPageSize ?? 500;
+  }
+  get snapshot() {
+    return this.sequence;
+  }
+  appendEntity(entity) {
+    requireIdentity(entity.id, "entity.id");
+    if (!ENTITY_KIND_SET.has(entity.kind)) throw new LineageValidationError("VALUE_INVALID", `Unsupported entity kind ${String(entity.kind)}`);
+    requireIdentity(entity.schemaId, "entity.schemaId");
+    requireIdentity(entity.schemaVersion, "entity.schemaVersion");
+    requireTimestamp(entity.createdAt, "entity.createdAt");
+    this.ensureUnique(this.entities, entity.id, "entity");
+    return this.append(this.entities, entity.id, entity);
+  }
+  appendAgent(agent) {
+    requireIdentity(agent.id, "agent.id");
+    requireIdentity(agent.name, "agent.name");
+    this.ensureUnique(this.agents, agent.id, "agent");
+    return this.append(this.agents, agent.id, agent);
+  }
+  appendActivity(activity) {
+    requireIdentity(activity.id, "activity.id");
+    requireTimestamp(activity.startedAt, "activity.startedAt");
+    if (activity.endedAt) requireTimestamp(activity.endedAt, "activity.endedAt");
+    for (const agentId of activity.agentIds) {
+      if (!this.agents.has(agentId)) throw new LineageValidationError("AGENT_DANGLING", `Activity references unknown agent ${agentId}`);
+    }
+    this.ensureUnique(this.activities, activity.id, "activity");
+    return this.append(this.activities, activity.id, activity);
+  }
+  appendEvidence(item) {
+    requireIdentity(item.id, "evidence.id");
+    requireIdentity(item.revision, "evidence.revision");
+    requireIdentity(item.locator, "evidence.locator");
+    requireTimestamp(item.capturedAt, "evidence.capturedAt");
+    if (item.payload !== void 0 && computeLineageDigest(item.payload) !== item.digest) {
+      throw new LineageValidationError("EVIDENCE_DIGEST_MISMATCH", `Evidence ${item.id} payload does not match ${item.digest}`);
+    }
+    const key = `${item.id}@${item.revision}`;
+    this.ensureUnique(this.evidence, key, "evidence revision");
+    return this.append(this.evidence, key, item);
+  }
+  appendAssertion(assertion) {
+    requireIdentity(assertion.id, "assertion.id");
+    requireIdentity(assertion.revision, "assertion.revision");
+    requireIdentity(assertion.method, "assertion.method");
+    requireIdentity(assertion.schemaId, "assertion.schemaId");
+    requireIdentity(assertion.schemaVersion, "assertion.schemaVersion");
+    requireTimestamp(assertion.assertedAt, "assertion.assertedAt");
+    if (!RELATIONSHIP_KIND_SET.has(assertion.relationship)) throw new LineageValidationError("VALUE_INVALID", `Unsupported relationship ${String(assertion.relationship)}`);
+    if (!Number.isFinite(assertion.confidence) || assertion.confidence < 0 || assertion.confidence > 1) {
+      throw new LineageValidationError("VALUE_INVALID", "assertion.confidence must be between 0 and 1");
+    }
+    const source = this.entities.get(assertion.sourceEntityId)?.value;
+    const target = this.entities.get(assertion.targetEntityId)?.value;
+    if (!source || !target) throw new LineageValidationError("IDENTITY_DANGLING", "Assertion source and target must both exist");
+    const endpointRule = RELATIONSHIP_ENDPOINTS[assertion.relationship];
+    if (endpointRule && (!endpointRule[0].includes(source.kind) || !endpointRule[1].includes(target.kind))) {
+      throw new LineageValidationError("TYPE_DIRECTION_INVALID", `${assertion.relationship} does not allow ${source.kind} -> ${target.kind}`);
+    }
+    if (!this.agents.has(assertion.issuerAgentId)) throw new LineageValidationError("AGENT_DANGLING", `Unknown issuer agent ${assertion.issuerAgentId}`);
+    if (assertion.producingActivityId && !this.activities.has(assertion.producingActivityId)) {
+      throw new LineageValidationError("IDENTITY_DANGLING", `Unknown producing activity ${assertion.producingActivityId}`);
+    }
+    if (assertion.assertionKind === "observed" && !assertion.producingActivityId) {
+      throw new LineageValidationError("ACTIVITY_REQUIRED", "Observed assertions require a producing activity");
+    }
+    if (assertion.assertionKind === "observed" && assertion.evidence.length === 0) {
+      throw new LineageValidationError("EVIDENCE_DANGLING", "Observed assertions require evidence");
+    }
+    for (const reference of assertion.evidence) {
+      const item = this.evidence.get(`${reference.evidenceId}@${reference.revision}`)?.value;
+      if (!item) throw new LineageValidationError("EVIDENCE_DANGLING", `Unknown evidence ${reference.evidenceId}@${reference.revision}`);
+      if (item.digest !== reference.digest) throw new LineageValidationError("EVIDENCE_DIGEST_MISMATCH", `Evidence reference digest differs for ${reference.evidenceId}`);
+      if (reference.locator && reference.locator !== item.locator) throw new LineageValidationError("EVIDENCE_DIGEST_MISMATCH", `Evidence locator differs for ${reference.evidenceId}`);
+    }
+    const key = `${assertion.id}@${assertion.revision}`;
+    if (this.assertions.has(key)) throw new LineageValidationError("IDENTITY_DUPLICATE", `Duplicate assertion revision ${key}`);
+    const prior = [...this.assertions.values()].some((entry) => entry.value.id === assertion.id);
+    if (prior && !this.hasReplacementPermission(assertion.id, assertion.revision)) {
+      throw new LineageValidationError("CORRECTION_INVALID", `Assertion ${assertion.id} can only receive revision ${assertion.revision} after an explicit correction`);
+    }
+    return this.append(this.assertions, key, assertion);
+  }
+  appendCorrection(correction) {
+    requireIdentity(correction.id, "correction.id");
+    requireIdentity(correction.reason, "correction.reason");
+    requireTimestamp(correction.recordedAt, "correction.recordedAt");
+    if (!this.assertions.has(`${correction.assertionId}@${correction.assertionRevision}`)) throw new LineageValidationError("IDENTITY_DANGLING", `Unknown assertion ${correction.assertionId}@${correction.assertionRevision}`);
+    if (!this.agents.has(correction.issuerAgentId)) throw new LineageValidationError("AGENT_DANGLING", `Unknown correction issuer ${correction.issuerAgentId}`);
+    const activity = this.activities.get(correction.activityId)?.value;
+    if (!activity || activity.kind !== "correction") throw new LineageValidationError("CORRECTION_INVALID", "Correction requires a correction activity");
+    if (correction.action === "retract" && (correction.replacementAssertionId || correction.replacementRevision)) throw new LineageValidationError("CORRECTION_INVALID", "Retraction cannot name a replacement");
+    if (correction.action !== "retract" && (!correction.replacementAssertionId || !correction.replacementRevision)) throw new LineageValidationError("CORRECTION_INVALID", `${correction.action} requires a replacement assertion identity and revision`);
+    if (correction.replacementAssertionId === correction.assertionId && correction.action === "supersede") {
+      throw new LineageValidationError("CORRECTION_INVALID", "Supersession must identify a different assertion");
+    }
+    this.ensureUnique(this.corrections, correction.id, "correction");
+    return this.append(this.corrections, correction.id, correction);
+  }
+  traverse(request, policy) {
+    this.validateTraversalRequest(request);
+    const snapshot = request.snapshot ?? this.sequence;
+    if (snapshot < 0 || snapshot > this.sequence) throw new LineageValidationError("SNAPSHOT_UNAVAILABLE", `Snapshot ${snapshot} is unavailable`);
+    const entityMap = this.visibleAt(this.entities, snapshot);
+    const assertions = [...this.visibleAt(this.assertions, snapshot).values()].filter((assertion) => !request.relationshipKinds || request.relationshipKinds.includes(assertion.relationship)).filter((assertion) => !request.assertionKinds || request.assertionKinds.includes(assertion.assertionKind)).filter((assertion) => policy.canReadAssertion(clone2(assertion))).filter((assertion) => {
+      const source = entityMap.get(assertion.sourceEntityId);
+      const target = entityMap.get(assertion.targetEntityId);
+      return Boolean(source && target && policy.canReadEntity(clone2(source)) && policy.canReadEntity(clone2(target)));
+    }).sort(compareAssertions);
+    for (const id of request.startEntityIds) {
+      const entity = entityMap.get(id);
+      if (!entity || !policy.canReadEntity(clone2(entity))) throw new LineageValidationError("IDENTITY_DANGLING", `Start entity ${id} is unavailable`);
+    }
+    const queue = [...new Set(request.startEntityIds)].sort().map((id) => ({ id, depth: 0, path: [] }));
+    const visitedDepth = /* @__PURE__ */ new Map();
+    const nodeMap = /* @__PURE__ */ new Map();
+    const edgeMap = /* @__PURE__ */ new Map();
+    while (queue.length > 0) {
+      const current = queue.shift();
+      const priorDepth = visitedDepth.get(current.id);
+      if (priorDepth !== void 0 && priorDepth <= current.depth) continue;
+      visitedDepth.set(current.id, current.depth);
+      const entity = entityMap.get(current.id);
+      if (!request.entityKinds || request.entityKinds.includes(entity.kind) || current.depth === 0) {
+        nodeMap.set(current.id, { entity: clone2(entity), depth: current.depth, pathAssertionIds: [...current.path] });
+      }
+      if (current.depth >= request.maximumDepth) continue;
+      for (const assertion of assertions) {
+        const downstream = assertion.sourceEntityId === current.id;
+        const upstream = assertion.targetEntityId === current.id;
+        if (request.direction === "downstream" && !downstream || request.direction === "upstream" && !upstream || request.direction === "both" && !downstream && !upstream) continue;
+        const nextId = downstream ? assertion.targetEntityId : assertion.sourceEntityId;
+        edgeMap.set(`${assertion.id}@${assertion.revision}`, {
+          assertion: clone2(assertion),
+          status: this.statusAt(assertion.id, assertion.revision, snapshot),
+          ...request.includeEvidence ? { evidence: assertion.evidence.map((reference) => this.evidence.get(`${reference.evidenceId}@${reference.revision}`)).filter((entry) => Boolean(entry && entry.sequence <= snapshot)).map((entry) => entry.value).filter((item) => policy.canReadEvidence(clone2(item))).map(clone2) } : {}
+        });
+        queue.push({ id: nextId, depth: current.depth + 1, path: [...current.path, assertion.id] });
+      }
+      if (nodeMap.size + edgeMap.size > request.maximumResults) break;
+    }
+    const allNodes = [...nodeMap.values()].sort((left, right) => left.depth - right.depth || left.entity.id.localeCompare(right.entity.id));
+    const allEdges = [...edgeMap.values()].sort((left, right) => compareAssertions(left.assertion, right.assertion));
+    const rows = [
+      ...allNodes.map((value) => ({ kind: "node", key: `n:${String(value.depth).padStart(8, "0")}:${value.entity.id}`, value })),
+      ...allEdges.map((value) => ({ kind: "edge", key: `e:${value.assertion.sourceEntityId}:${value.assertion.targetEntityId}:${value.assertion.relationship}:${value.assertion.id}`, value }))
+    ].sort((left, right) => left.key.localeCompare(right.key));
+    const requestFingerprint = this.traversalFingerprint(request, snapshot);
+    const offset = request.cursor ? this.decodeCursor(request.cursor, requestFingerprint, snapshot) : 0;
+    const bounded = rows.slice(0, request.maximumResults);
+    const page = bounded.slice(offset, offset + request.pageSize);
+    const nextOffset = offset + page.length;
+    const truncated = rows.length > request.maximumResults;
+    return {
+      contract: DATASET_LINEAGE_CONTRACT,
+      schemaVersion: DATASET_LINEAGE_SCHEMA_VERSION,
+      snapshot,
+      nodes: page.filter((row) => row.kind === "node").map((row) => clone2(row.value)),
+      edges: page.filter((row) => row.kind === "edge").map((row) => clone2(row.value)),
+      ...nextOffset < bounded.length ? { nextCursor: `${snapshot}.${nextOffset}.${requestFingerprint}` } : {},
+      truncated
+    };
+  }
+  exportArchive(snapshot = this.sequence) {
+    if (snapshot < 0 || snapshot > this.sequence) throw new LineageValidationError("SNAPSHOT_UNAVAILABLE", `Snapshot ${snapshot} is unavailable`);
+    const content = {
+      contract: DATASET_LINEAGE_CONTRACT,
+      schemaVersion: DATASET_LINEAGE_SCHEMA_VERSION,
+      snapshot,
+      entities: this.sorted(this.visibleAt(this.entities, snapshot)),
+      agents: this.sorted(this.visibleAt(this.agents, snapshot)),
+      activities: this.sorted(this.visibleAt(this.activities, snapshot)),
+      evidence: this.sorted(this.visibleAt(this.evidence, snapshot), (item) => `${item.id}@${item.revision}`),
+      assertions: this.sorted(this.visibleAt(this.assertions, snapshot)),
+      corrections: this.sorted(this.visibleAt(this.corrections, snapshot))
+    };
+    return clone2({ ...content, digest: computeLineageDigest(content) });
+  }
+  static importArchive(archive, options = {}) {
+    if (archive.contract !== DATASET_LINEAGE_CONTRACT || !archive.schemaVersion.startsWith("1.")) throw new LineageValidationError("VALUE_INVALID", "Unsupported lineage archive contract");
+    const { digest: digest2, ...content } = archive;
+    if (computeLineageDigest(content) !== digest2) throw new LineageValidationError("EVIDENCE_DIGEST_MISMATCH", "Lineage archive digest does not match canonical content");
+    const ledger = new _DatasetLineageLedger(options);
+    for (const item of archive.agents) ledger.appendAgent(item);
+    for (const item of archive.entities) ledger.appendEntity(item);
+    for (const item of archive.activities) ledger.appendActivity(item);
+    for (const item of archive.evidence) ledger.appendEvidence(item);
+    const replacementKeys = new Set(archive.corrections.flatMap((item) => item.replacementAssertionId && item.replacementRevision ? [`${item.replacementAssertionId}@${item.replacementRevision}`] : []));
+    for (const item of archive.assertions.filter((item2) => !replacementKeys.has(`${item2.id}@${item2.revision}`))) ledger.appendAssertion(item);
+    const pending = [...archive.corrections];
+    while (pending.length > 0) {
+      const index = pending.findIndex((item) => ledger.assertions.has(`${item.assertionId}@${item.assertionRevision}`));
+      if (index < 0) throw new LineageValidationError("CORRECTION_INVALID", "Correction history contains an unreachable assertion revision");
+      const correction = pending.splice(index, 1)[0];
+      ledger.appendCorrection(correction);
+      if (correction.replacementAssertionId && correction.replacementRevision) {
+        const key = `${correction.replacementAssertionId}@${correction.replacementRevision}`;
+        if (!ledger.assertions.has(key)) {
+          const replacement = archive.assertions.find((item) => `${item.id}@${item.revision}` === key);
+          if (!replacement) throw new LineageValidationError("IDENTITY_DANGLING", `Missing replacement assertion ${key}`);
+          ledger.appendAssertion(replacement);
+        }
+      }
+    }
+    return ledger;
+  }
+  project(capabilities, snapshot = this.sequence) {
+    const source = this.exportArchive(snapshot);
+    const losses = [];
+    const entities = source.entities.filter((item, index) => {
+      const keep = capabilities.entityKinds.includes(item.kind);
+      if (!keep) losses.push({ path: `/entities/${index}`, reason: "unsupported-entity-kind", canonicalDigest: computeLineageDigest(item) });
+      return keep;
+    });
+    const entityIds = new Set(entities.map((item) => item.id));
+    const assertions = source.assertions.filter((item, index) => {
+      const reason = !capabilities.relationshipKinds.includes(item.relationship) ? "unsupported-relationship-kind" : !capabilities.assertionKinds.includes(item.assertionKind) ? "unsupported-assertion-kind" : !entityIds.has(item.sourceEntityId) || !entityIds.has(item.targetEntityId) ? "unsupported-entity-kind" : void 0;
+      if (reason) losses.push({ path: `/assertions/${index}`, reason, canonicalDigest: computeLineageDigest(item) });
+      return !reason;
+    });
+    const evidenceIds = new Set(assertions.flatMap((item) => item.evidence.map((reference) => `${reference.evidenceId}@${reference.revision}`)));
+    const evidence = capabilities.preservesEvidence ? source.evidence.filter((item) => evidenceIds.has(`${item.id}@${item.revision}`)) : [];
+    if (!capabilities.preservesEvidence && evidenceIds.size > 0) losses.push({ path: "/evidence", reason: "evidence-omitted", canonicalDigest: computeLineageDigest(source.evidence) });
+    const assertionIds = new Set(assertions.map((item) => item.id));
+    const corrections = capabilities.preservesCorrections ? source.corrections.filter((item) => assertionIds.has(item.assertionId)) : [];
+    if (!capabilities.preservesCorrections && source.corrections.length > 0) losses.push({ path: "/corrections", reason: "corrections-omitted", canonicalDigest: computeLineageDigest(source.corrections) });
+    losses.sort((left, right) => left.path.localeCompare(right.path) || left.reason.localeCompare(right.reason));
+    const projectionContent = { entities, assertions, evidence, corrections };
+    const projectionDigest = computeLineageDigest(projectionContent);
+    return clone2({
+      contract: DATASET_LINEAGE_CONTRACT,
+      schemaVersion: DATASET_LINEAGE_SCHEMA_VERSION,
+      canonical: false,
+      regenerable: true,
+      sourceDigest: source.digest,
+      ...projectionContent,
+      digest: projectionDigest,
+      lossReceipt: {
+        contract: DATASET_LINEAGE_CONTRACT,
+        schemaVersion: DATASET_LINEAGE_SCHEMA_VERSION,
+        sourceDigest: source.digest,
+        projectionDigest,
+        lossless: losses.length === 0,
+        losses
+      }
+    });
+  }
+  append(map, key, value) {
+    this.sequence += 1;
+    map.set(key, { sequence: this.sequence, value: clone2(value) });
+    return this.sequence;
+  }
+  ensureUnique(map, key, label) {
+    if (map.has(key)) throw new LineageValidationError("IDENTITY_DUPLICATE", `Duplicate ${label} identity ${key}`);
+  }
+  visibleAt(map, snapshot) {
+    return new Map([...map].filter(([, entry]) => entry.sequence <= snapshot).map(([key, entry]) => [key, clone2(entry.value)]));
+  }
+  sorted(map, key = (item) => item.id) {
+    return [...map.values()].sort((left, right) => key(left).localeCompare(key(right))).map(clone2);
+  }
+  hasReplacementPermission(assertionId, revision) {
+    return [...this.corrections.values()].some((entry) => entry.value.action === "correct" && entry.value.replacementAssertionId === assertionId && entry.value.replacementRevision === revision);
+  }
+  statusAt(assertionId, revision, snapshot) {
+    const latest = [...this.corrections.values()].filter((entry) => entry.sequence <= snapshot && entry.value.assertionId === assertionId && entry.value.assertionRevision === revision).sort((left, right) => right.sequence - left.sequence)[0]?.value;
+    if (!latest) return "active";
+    return latest.action === "correct" ? "corrected" : latest.action === "retract" ? "retracted" : "superseded";
+  }
+  validateTraversalRequest(request) {
+    if (request.startEntityIds.length === 0) throw new LineageValidationError("IDENTITY_REQUIRED", "At least one start entity is required");
+    if (!Number.isSafeInteger(request.maximumDepth) || request.maximumDepth < 0 || request.maximumDepth > this.maximumTraversalDepth) throw new LineageValidationError("TRAVERSAL_LIMIT_EXCEEDED", `maximumDepth exceeds ${this.maximumTraversalDepth}`);
+    if (!Number.isSafeInteger(request.maximumResults) || request.maximumResults < 1 || request.maximumResults > this.maximumTraversalResults) throw new LineageValidationError("TRAVERSAL_LIMIT_EXCEEDED", `maximumResults exceeds ${this.maximumTraversalResults}`);
+    if (!Number.isSafeInteger(request.pageSize) || request.pageSize < 1 || request.pageSize > this.maximumPageSize || request.pageSize > request.maximumResults) throw new LineageValidationError("TRAVERSAL_LIMIT_EXCEEDED", `pageSize exceeds ${this.maximumPageSize}`);
+  }
+  traversalFingerprint(request, snapshot) {
+    const parameters = { ...request };
+    delete parameters.cursor;
+    delete parameters.snapshot;
+    return computeLineageDigest({ ...parameters, startEntityIds: [...new Set(parameters.startEntityIds)].sort(), snapshot });
+  }
+  decodeCursor(cursor, fingerprint, snapshot) {
+    const match = /^(\d+)\.(\d+)\.(sha256:[0-9a-f]{64})$/.exec(cursor);
+    if (!match || Number(match[1]) !== snapshot || match[3] !== fingerprint) throw new LineageValidationError("CURSOR_INVALID", "Cursor does not match this query and snapshot");
+    const offset = Number(match[2]);
+    if (!Number.isSafeInteger(offset) || offset < 0) throw new LineageValidationError("CURSOR_INVALID", "Cursor offset is invalid");
+    return offset;
+  }
+};
+function compareAssertions(left, right) {
+  return left.sourceEntityId.localeCompare(right.sourceEntityId) || left.targetEntityId.localeCompare(right.targetEntityId) || left.relationship.localeCompare(right.relationship) || left.id.localeCompare(right.id);
+}
+
+// src/dataset-execution-capabilities.ts
+var DATASET_EXECUTION_CONTRACT = "fortemi.dataset-execution-capabilities/v1";
+var DATASET_EXECUTION_SCHEMA_VERSION = "1.0.0";
+var DATASET_EXECUTION_CAPABILITY_IDS = [
+  "ingest.full",
+  "ingest.snapshot",
+  "ingest.incremental",
+  "ingest.stream",
+  "schema.inspect",
+  "identity.stable-revision",
+  "identity.record",
+  "mutation.upsert",
+  "mutation.tombstone",
+  "mutation.reconcile",
+  "checkpoint.read",
+  "checkpoint.write",
+  "execution.cancel",
+  "rejection.record",
+  "index.lexical",
+  "index.chunk",
+  "index.vector",
+  "index.hybrid",
+  "index.rerank",
+  "index.graph",
+  "index.community",
+  "lineage.dataset",
+  "lineage.record",
+  "lineage.field",
+  "lineage.relationship-evidence",
+  "transaction.atomic-batch",
+  "privacy.pre-materialization-filter",
+  "pagination.cursor",
+  "ordering.deterministic"
+];
+var ID_SET = new Set(DATASET_EXECUTION_CAPABILITY_IDS);
+var LIMIT_KEYS = ["maxInputBytes", "maxRecordBytes", "maxBatchRecords", "maxConcurrency", "maxPageSize", "maxTraversalDepth"];
+function major(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
+  return match ? Number(match[1]) : null;
+}
+function compareVersions(left, right) {
+  const parse = (value) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(value);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+  };
+  const a = parse(left);
+  const b = parse(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < 3; index++) {
+    if (a[index] !== b[index]) return a[index] > b[index] ? 1 : -1;
+  }
+  return 0;
+}
+function isSupported(capability) {
+  return capability !== void 0 && capability.status !== "unsupported";
+}
+function validateDatasetExecutionDescriptor(descriptor) {
+  const diagnostics = [];
+  if (descriptor.contract !== DATASET_EXECUTION_CONTRACT) {
+    diagnostics.push({ code: "CONTRACT_MAJOR_UNSUPPORTED", path: "/contract", message: `Unsupported contract ${String(descriptor.contract)}` });
+  }
+  if (major(descriptor.schemaVersion) !== 1) {
+    diagnostics.push({ code: "SCHEMA_VERSION_UNSUPPORTED", path: "/schemaVersion", message: `Unsupported descriptor schema version ${descriptor.schemaVersion}` });
+  }
+  const capabilities = /* @__PURE__ */ new Map();
+  descriptor.capabilities.forEach((capability, index) => {
+    if (!ID_SET.has(capability.id) || compareVersions(capability.version, capability.version) === null) {
+      diagnostics.push({ code: "DESCRIPTOR_INVALID", path: `/capabilities/${index}`, message: `Invalid capability declaration ${capability.id}` });
+      return;
+    }
+    if (capabilities.has(capability.id)) {
+      diagnostics.push({ code: "CAPABILITY_DUPLICATE", capability: capability.id, path: `/capabilities/${index}/id`, message: `Capability ${capability.id} is declared more than once` });
+    }
+    capabilities.set(capability.id, capability);
+    for (const key of LIMIT_KEYS) {
+      const value = capability.limits?.[key];
+      if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) {
+        diagnostics.push({ code: "DESCRIPTOR_INVALID", capability: capability.id, path: `/capabilities/${index}/limits/${key}`, message: `${key} must be a non-negative safe integer` });
+      }
+    }
+    if (capability.status !== "unsupported" && capability.evidence.length === 0) {
+      diagnostics.push({ code: "DESCRIPTOR_INVALID", capability: capability.id, path: `/capabilities/${index}/evidence`, message: `Supported capability ${capability.id} requires evidence` });
+    }
+    for (const evidenceId of capability.evidence) {
+      if (!descriptor.evidence.some((evidence) => evidence.id === evidenceId)) {
+        diagnostics.push({ code: "DESCRIPTOR_INVALID", capability: capability.id, path: `/capabilities/${index}/evidence`, message: `Unknown evidence ${evidenceId}` });
+      }
+    }
+  });
+  const requireTogether = (source, requirements) => {
+    if (!isSupported(capabilities.get(source))) return;
+    for (const requirement of requirements) {
+      if (!isSupported(capabilities.get(requirement))) {
+        diagnostics.push({ code: "CAPABILITY_INCONSISTENT", capability: source, message: `${source} requires ${requirement}` });
+      }
+    }
+  };
+  requireTogether("ingest.incremental", ["identity.stable-revision", "checkpoint.read", "checkpoint.write"]);
+  requireTogether("lineage.field", ["lineage.relationship-evidence"]);
+  requireTogether("mutation.reconcile", ["mutation.upsert", "mutation.tombstone"]);
+  requireTogether("index.hybrid", ["index.lexical", "index.vector"]);
+  if (descriptor.guarantees.transaction === "atomic-batch" && !isSupported(capabilities.get("transaction.atomic-batch"))) {
+    diagnostics.push({ code: "CAPABILITY_INCONSISTENT", capability: "transaction.atomic-batch", message: "Atomic-batch guarantee requires transaction.atomic-batch capability" });
+  }
+  if (descriptor.runtime.plane === "static-cache" && descriptor.runtime.dataClass !== "static-cache") {
+    diagnostics.push({ code: "CAPABILITY_INCONSISTENT", message: "Static-cache execution plane must declare static-cache data class" });
+  }
+  if (descriptor.runtime.plane === "live-remote-persistence" && descriptor.runtime.maturity === "stable" && !descriptor.evidence.some((item) => item.kind === "live-qualification")) {
+    diagnostics.push({ code: "CAPABILITY_INCONSISTENT", message: "Stable live remote persistence requires live qualification evidence" });
+  }
+  return diagnostics;
+}
+function assessRequirement(requirement, capabilities) {
+  const capability = capabilities.get(requirement.id);
+  if (!isSupported(capability)) {
+    return { ok: false, reason: "unsupported", diagnostics: [{ code: "REQUIRED_CAPABILITY_MISSING", capability: requirement.id, message: `Capability ${requirement.id} is unsupported` }] };
+  }
+  if (requirement.minimumVersion) {
+    const comparison = compareVersions(capability.version, requirement.minimumVersion);
+    if (comparison === null || comparison < 0) {
+      return { ok: false, reason: "version-insufficient", diagnostics: [{ code: "CAPABILITY_VERSION_INSUFFICIENT", capability: requirement.id, message: `${capability.version} does not satisfy ${requirement.minimumVersion}` }] };
+    }
+  }
+  for (const key of LIMIT_KEYS) {
+    const required = requirement.minimumLimits?.[key];
+    if (required !== void 0 && (capability.limits?.[key] ?? -1) < required) {
+      return { ok: false, reason: "limit-insufficient", diagnostics: [{ code: "CAPABILITY_LIMIT_INSUFFICIENT", capability: requirement.id, path: `/minimumLimits/${key}`, message: `${key} does not satisfy ${required}` }] };
+    }
+  }
+  return { ok: true, diagnostics: [] };
+}
+function negotiateDatasetExecutionCapabilities(descriptor, request) {
+  const diagnostics = validateDatasetExecutionDescriptor(descriptor);
+  if (request.contract !== DATASET_EXECUTION_CONTRACT) {
+    diagnostics.push({ code: "CONTRACT_MAJOR_UNSUPPORTED", path: "/contract", message: `Unsupported request contract ${String(request.contract)}` });
+  }
+  const capabilities = new Map(descriptor.capabilities.map((capability) => [capability.id, capability]));
+  const selected = [];
+  const degradations = [];
+  if (diagnostics.length === 0) {
+    for (const requirement of request.required) {
+      const assessment = assessRequirement(requirement, capabilities);
+      if (assessment.ok) selected.push(requirement.id);
+      else diagnostics.push(...assessment.diagnostics);
+    }
+    for (const requirement of request.optional ?? []) {
+      const assessment = assessRequirement(requirement, capabilities);
+      if (assessment.ok) {
+        selected.push(requirement.id);
+        continue;
+      }
+      const fallback = requirement.fallback?.find((id) => isSupported(capabilities.get(id)));
+      if (fallback) selected.push(fallback);
+      degradations.push({
+        requested: requirement.id,
+        ...fallback ? { selected: fallback } : {},
+        reason: assessment.reason,
+        changedGuarantees: fallback ? [`${requirement.id} replaced by ${fallback}`] : [`${requirement.id} omitted`]
+      });
+    }
+  }
+  return {
+    contract: DATASET_EXECUTION_CONTRACT,
+    accepted: diagnostics.length === 0,
+    runtime: { ...descriptor.runtime },
+    selected: [...new Set(selected)],
+    degradations,
+    diagnostics
+  };
+}
+
+// src/dataset-execution-descriptors.ts
+var FORTEMI_BROWSER_LOCAL_DATASET_EXECUTION_DESCRIPTOR = {
+  contract: DATASET_EXECUTION_CONTRACT,
+  schemaVersion: DATASET_EXECUTION_SCHEMA_VERSION,
+  runtime: { id: "fortemi-browser", version: "2026.8.0", plane: "browser-local-archive", dataClass: "canonical", maturity: "stable" },
+  guarantees: { transaction: "atomic-batch", isolation: "serializable", durability: "wal", availability: "local-process", ordering: "backend-cursor" },
+  capabilities: [
+    { id: "ingest.full", version: "1.0.0", status: "supported", limits: { maxBatchRecords: 1e3, maxConcurrency: 1 }, evidence: ["browser-conformance"] },
+    { id: "identity.record", version: "1.0.0", status: "supported", evidence: ["browser-conformance"] },
+    { id: "mutation.upsert", version: "1.0.0", status: "supported", evidence: ["browser-conformance"] },
+    { id: "transaction.atomic-batch", version: "1.0.0", status: "supported", evidence: ["browser-conformance"] },
+    { id: "ordering.deterministic", version: "1.0.0", status: "supported", evidence: ["browser-conformance"] }
+  ],
+  evidence: [{ id: "browser-conformance", kind: "conformance-report", uri: "fortemi://conformance/browser-local/v1" }]
+};
+var FORTEMI_STATIC_CACHE_DATASET_EXECUTION_DESCRIPTOR = {
+  contract: DATASET_EXECUTION_CONTRACT,
+  schemaVersion: DATASET_EXECUTION_SCHEMA_VERSION,
+  runtime: { id: "fortemi-static", version: "2026.8.0", plane: "static-cache", dataClass: "static-cache", maturity: "stable" },
+  guarantees: { transaction: "none", isolation: "snapshot", durability: "filesystem", availability: "local-process", ordering: "stable-identity" },
+  capabilities: [
+    { id: "index.lexical", version: "1.0.0", status: "supported", limits: { maxPageSize: 1e3 }, evidence: ["static-conformance"] },
+    { id: "pagination.cursor", version: "1.0.0", status: "supported", evidence: ["static-conformance"] },
+    { id: "ordering.deterministic", version: "1.0.0", status: "supported", evidence: ["static-conformance"] }
+  ],
+  evidence: [{ id: "static-conformance", kind: "conformance-report", uri: "fortemi://conformance/static-cache/v1" }]
+};
+var FORTEMI_PORTABLE_SHARD_DATASET_EXECUTION_DESCRIPTOR = {
+  contract: DATASET_EXECUTION_CONTRACT,
+  schemaVersion: DATASET_EXECUTION_SCHEMA_VERSION,
+  runtime: { id: "fortemi-shard", version: "2026.8.0", plane: "portable-shard", dataClass: "portable-projection", maturity: "stable" },
+  guarantees: { transaction: "none", isolation: "snapshot", durability: "filesystem", availability: "local-process", ordering: "stable-identity" },
+  capabilities: [
+    { id: "schema.inspect", version: "1.0.0", status: "supported", evidence: ["shard-conformance"] },
+    { id: "lineage.dataset", version: "1.0.0", status: "experimental", evidence: ["shard-conformance"] },
+    { id: "ordering.deterministic", version: "1.0.0", status: "supported", evidence: ["shard-conformance"] }
+  ],
+  evidence: [{ id: "shard-conformance", kind: "conformance-report", uri: "fortemi://conformance/knowledge-shard/v1" }]
+};
+var DATASET_MATERIALIZATION_CONTRACT = "fortemi.dataset-materialization-profile/v1";
+var DATASET_MATERIALIZATION_SCHEMA_VERSION = "1.0.0";
+var DATASET_MATERIALIZATION_KINDS = [
+  "chunking",
+  "lexical",
+  "vector",
+  "hybrid",
+  "rerank",
+  "entity-relationship-extraction",
+  "graph-retrieval",
+  "community"
+];
+var DatasetMaterializationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "DatasetMaterializationError";
+  }
+};
+var encoder = new TextEncoder();
+function canonicalJson3(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson3).join(",")}]`;
+  return `{${Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson3(item)}`).join(",")}}`;
+}
+function digestDatasetMaterializationValue(value) {
+  return computeHash(encoder.encode(canonicalJson3(value)));
+}
+function profileDiagnostics(profile) {
+  const diagnostics = [];
+  const requiredBoundaries = ["chunking", "model-invocation", "index-persistence"];
+  if (profile.contract !== DATASET_MATERIALIZATION_CONTRACT || !/^1\./.test(profile.schemaVersion)) {
+    diagnostics.push({ code: "PROFILE_INVALID", path: "/contract", message: "Unsupported profile contract or schema major" });
+  }
+  if (profile.output.dataClass !== "regenerable-index" || profile.output.canonicalMutation !== false) {
+    diagnostics.push({ code: "PROFILE_INVALID", path: "/output", message: "Profiles may only produce derived, regenerable artifacts" });
+  }
+  for (const boundary of requiredBoundaries) {
+    if (!profile.privacy.filtersBefore.includes(boundary)) {
+      diagnostics.push({ code: "PROFILE_INVALID", path: "/privacy/filtersBefore", message: `Privacy filtering must precede ${boundary}` });
+    }
+  }
+  if (profile.determinism.class === "seeded" && profile.determinism.seedRequired !== true) {
+    diagnostics.push({ code: "PROFILE_INVALID", path: "/determinism/seedRequired", message: "Seeded profiles must require a seed" });
+  }
+  if (profile.resourceLimits.maxInputBytes < 0 || profile.resourceLimits.maxRecords < 0 || profile.resourceLimits.maxConcurrency < 1) {
+    diagnostics.push({ code: "PROFILE_INVALID", path: "/resourceLimits", message: "Resource limits must be non-negative and concurrency must be positive" });
+  }
+  return diagnostics;
+}
+function negotiateDatasetMaterializationProfile(request) {
+  const candidates = [request.profile, ...request.fallbackProfiles ?? []];
+  const primaryDiagnostics = profileDiagnostics(request.profile);
+  if (!request.profile.operations.includes(request.operation)) {
+    primaryDiagnostics.push({ code: "OPERATION_UNSUPPORTED", path: "/operations", message: `${request.operation} is not supported by ${request.profile.id}` });
+  }
+  if (request.profile.status === "unsupported") {
+    primaryDiagnostics.push({ code: "PROFILE_UNSUPPORTED", path: "/status", message: `${request.profile.id} is unsupported` });
+  }
+  for (let index = 0; index < candidates.length; index += 1) {
+    const candidate = candidates[index];
+    const diagnostics = index === 0 ? primaryDiagnostics : profileDiagnostics(candidate);
+    if (!candidate.operations.includes(request.operation) || candidate.status === "unsupported" || diagnostics.length > 0) continue;
+    const capability = negotiateDatasetExecutionCapabilities(request.runtime, {
+      contract: DATASET_EXECUTION_CONTRACT,
+      required: candidate.requiredRuntimeCapabilities,
+      optional: candidate.optionalRuntimeCapabilities
+    });
+    if (capability.accepted) {
+      const fallback = index > 0;
+      return {
+        accepted: true,
+        requestedProfile: request.profile.id,
+        selectedProfile: candidate.id,
+        runtime: { ...request.runtime.runtime },
+        degraded: fallback || capability.degradations.length > 0,
+        degradations: capability.degradations,
+        diagnostics: fallback ? primaryDiagnostics : []
+      };
+    }
+    if (index === 0) primaryDiagnostics.push(...capability.diagnostics);
+  }
+  return {
+    accepted: false,
+    requestedProfile: request.profile.id,
+    runtime: { ...request.runtime.runtime },
+    degraded: false,
+    degradations: [],
+    diagnostics: [...primaryDiagnostics, { code: "NO_FALLBACK_PROFILE", message: `No compatible ${request.operation} profile is available` }]
+  };
+}
+function clone3(value) {
+  return structuredClone(value);
+}
+function assertResources(snapshot, profile) {
+  const inputBytes = encoder.encode(canonicalJson3(snapshot.records)).byteLength;
+  if (snapshot.records.length > profile.resourceLimits.maxRecords || inputBytes > profile.resourceLimits.maxInputBytes) {
+    throw new DatasetMaterializationError("RESOURCE_LIMIT_EXCEEDED", `Input exceeds profile ${profile.id} resource limits`);
+  }
+  return inputBytes;
+}
+function stableArtifacts(artifacts) {
+  return [...artifacts].sort((left, right) => {
+    const score = (right.score ?? Number.NEGATIVE_INFINITY) - (left.score ?? Number.NEGATIVE_INFINITY);
+    return score || left.logicalId.localeCompare(right.logicalId) || left.digest.localeCompare(right.digest);
+  });
+}
+async function executeDatasetMaterialization(request, runtime, adapter, authorize, options = {}) {
+  const negotiation = negotiateDatasetMaterializationProfile({ operation: "build", profile: request.profile, runtime, fallbackProfiles: options.fallbackProfiles });
+  if (!negotiation.accepted || !negotiation.selectedProfile) {
+    throw new DatasetMaterializationError("NEGOTIATION_FAILED", negotiation.diagnostics.map((item) => item.message).join("; "));
+  }
+  const selected = [request.profile, ...options.fallbackProfiles ?? []].find((item) => item.id === negotiation.selectedProfile);
+  try {
+    const validateConfiguration = new Ajv20202({ strict: true, allErrors: true }).compile(selected.configurationSchema);
+    if (!validateConfiguration(request.configuration)) {
+      throw new DatasetMaterializationError("CONFIGURATION_INVALID", `Configuration does not satisfy ${selected.id}: ${JSON.stringify(validateConfiguration.errors)}`);
+    }
+  } catch (error) {
+    if (error instanceof DatasetMaterializationError) throw error;
+    throw new DatasetMaterializationError("PROFILE_INVALID", `Invalid configuration schema for ${selected.id}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const inputBytes = assertResources(request.snapshot, selected);
+  const allowed = [];
+  const denied = [];
+  for (const record of request.snapshot.records) {
+    if (await authorize(Object.freeze(clone3(record)))) allowed.push(clone3(record));
+    else denied.push(record.digest);
+  }
+  const privacy = {
+    policyId: "caller-authorization",
+    policyVersion: "1.0.0",
+    policyDigest: digestDatasetMaterializationValue({ policy: "caller-authorization", version: "1.0.0" }),
+    allowedRecordDigests: allowed.map((item) => item.digest).sort(),
+    deniedRecordDigests: denied.sort(),
+    evaluatedAt: (options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))()
+  };
+  const affected = request.affected ?? {
+    sourceRevisions: [request.snapshot.revision],
+    recordDigests: allowed.map((item) => item.digest).sort(),
+    chunkDigests: []
+  };
+  const detachedSnapshot = clone3({ ...request.snapshot, records: allowed });
+  const result = await adapter.materialize(Object.freeze({
+    snapshot: detachedSnapshot,
+    profile: clone3(selected),
+    configuration: clone3(request.configuration),
+    mode: request.mode,
+    affected: clone3(affected)
+  }));
+  const artifacts = selected.determinism.class === "deterministic" ? stableArtifacts(result.artifacts) : clone3(result.artifacts);
+  const digests = artifacts.map((item) => item.digest).sort();
+  const counts = artifacts.reduce((all, item) => {
+    all[item.kind] = (all[item.kind] ?? 0) + 1;
+    return all;
+  }, {});
+  const profileDigest = digestDatasetMaterializationValue(selected);
+  const receiptBase = {
+    contract: DATASET_MATERIALIZATION_CONTRACT,
+    schemaVersion: DATASET_MATERIALIZATION_SCHEMA_VERSION,
+    runId: request.runId,
+    processingRunId: request.processingRunId,
+    source: { datasetId: request.snapshot.datasetId, revision: request.snapshot.revision, digests: [...request.snapshot.sourceDigests].sort() },
+    schema: { id: request.snapshot.schemaId, version: request.snapshot.schemaVersion, digest: request.snapshot.schemaDigest },
+    profile: { id: selected.id, version: selected.version, digest: profileDigest, configurationDigest: digestDatasetMaterializationValue(request.configuration), implementation: clone3(selected.implementation) },
+    runtime: clone3(runtime.runtime),
+    negotiation: { requestedProfile: negotiation.requestedProfile, selectedProfile: negotiation.selectedProfile, degraded: negotiation.degraded, degradations: clone3(negotiation.degradations) },
+    mode: request.mode,
+    affected: clone3(affected),
+    output: { counts, digests, aggregateDigest: digestDatasetMaterializationValue(digests) },
+    privacy,
+    resources: { ...clone3(result.resources), inputBytes },
+    createdAt: (options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))()
+  };
+  const receipt = {
+    ...receiptBase,
+    receiptId: digestDatasetMaterializationValue(receiptBase)
+  };
+  return { artifacts, receipt };
+}
+async function executeDatasetRetrieval(request, runtime, adapter, receiptId, fallbackProfiles = []) {
+  const negotiation = negotiateDatasetMaterializationProfile({ operation: "query", profile: request.profile, runtime, fallbackProfiles });
+  if (!negotiation.accepted || !negotiation.selectedProfile) throw new DatasetMaterializationError("NEGOTIATION_FAILED", negotiation.diagnostics.map((item) => item.message).join("; "));
+  if (!adapter.retrieve) throw new DatasetMaterializationError("ADAPTER_MISMATCH", `Backend ${adapter.backend.id} cannot query`);
+  const selected = [request.profile, ...fallbackProfiles].find((item) => item.id === negotiation.selectedProfile);
+  const results = await adapter.retrieve(Object.freeze({ request: clone3(request), profile: clone3(selected) }));
+  return {
+    contract: DATASET_MATERIALIZATION_CONTRACT,
+    schemaVersion: DATASET_MATERIALIZATION_SCHEMA_VERSION,
+    queryId: request.queryId,
+    requestedProfile: request.profile.id,
+    actualProfile: selected.id,
+    actualBackend: { ...adapter.backend, plane: runtime.runtime.plane },
+    degraded: negotiation.degraded,
+    ...negotiation.degraded ? { fallbackReason: negotiation.diagnostics.map((item) => item.message).join("; ") || "optional capability degradation" } : {},
+    scoreSemantics: { implementationScoped: true, comparableAcrossImplementations: false },
+    results: selected.determinism.class === "deterministic" ? stableArtifacts(results).slice(0, request.limit) : clone3(results).slice(0, request.limit),
+    receiptId
+  };
+}
+function compareDatasetIncrementalParity(full, incremental) {
+  const select = (items, kind) => items.filter((item) => !kind || item.kind === kind).map((item) => `${item.logicalId}:${item.digest}`).sort();
+  const mismatches = [];
+  if (canonicalJson3(select(full)) !== canonicalJson3(select(incremental))) mismatches.push("identities");
+  if (canonicalJson3(select(full, "chunk")) !== canonicalJson3(select(incremental, "chunk"))) mismatches.push("chunks");
+  if (canonicalJson3(select(full, "relationship")) !== canonicalJson3(select(incremental, "relationship"))) mismatches.push("relationships");
+  if (canonicalJson3(select(full, "community")) !== canonicalJson3(select(incremental, "community"))) mismatches.push("communities");
+  if (canonicalJson3(full.map((item) => item.digest).sort()) !== canonicalJson3(incremental.map((item) => item.digest).sort())) mismatches.push("digests");
+  const order = (items) => items.map((item) => `${item.logicalId}:${item.digest}`);
+  if (canonicalJson3(order(full)) !== canonicalJson3(order(incremental))) mismatches.push("ordering");
+  return { equivalent: mismatches.length === 0, mismatches };
+}
+function validateDatasetBenchmarkEvidence(evidence) {
+  const errors = [];
+  if (evidence.contract !== DATASET_MATERIALIZATION_CONTRACT || !/^1\./.test(evidence.schemaVersion)) errors.push("unsupported benchmark contract");
+  if (!evidence.correctness.passed) errors.push("correctness suite did not pass");
+  if (evidence.freshness.sourceRevision !== evidence.corpus.revision) errors.push("benchmark evidence is stale");
+  if (!evidence.claims.corpusScoped || evidence.claims.universalScaleLimit) errors.push("benchmark claims must remain corpus-scoped");
+  if (evidence.measurements.length === 0) errors.push("benchmark has no measurements");
+  return errors;
+}
 
 // src/event-bus.ts
 var TypedEventBus = class {
@@ -1005,6 +2072,54 @@ var migration0023 = {
   `
 };
 
+// src/migrations/0024_source_upsert_contract.ts
+var migration0024 = {
+  version: 24,
+  name: "0024_source_upsert_contract",
+  sql: `
+    ALTER TABLE source_import_run ADD COLUMN IF NOT EXISTS external_run_id TEXT;
+    ALTER TABLE source_import_run ADD COLUMN IF NOT EXISTS source_id TEXT;
+    ALTER TABLE source_import_run ADD COLUMN IF NOT EXISTS source_schema_version TEXT;
+    ALTER TABLE source_import_run ADD COLUMN IF NOT EXISTS workspace_id TEXT;
+    UPDATE source_import_run SET external_run_id = id WHERE external_run_id IS NULL;
+    UPDATE source_import_run SET source_schema_version = 'legacy' WHERE source_schema_version IS NULL;
+    ALTER TABLE source_import_run ALTER COLUMN external_run_id SET NOT NULL;
+    ALTER TABLE source_import_run ALTER COLUMN source_schema_version SET NOT NULL;
+    ALTER TABLE source_import_run ADD CONSTRAINT source_import_run_contract_lengths
+      CHECK (
+        length(external_run_id) BETWEEN 1 AND 200
+        AND (source_id IS NULL OR length(source_id) BETWEEN 1 AND 500)
+        AND length(source_schema_version) BETWEEN 1 AND 100
+        AND (workspace_id IS NULL OR length(workspace_id) BETWEEN 1 AND 500)
+      );
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_source_import_run_scope
+      ON source_import_run(tenant_id, COALESCE(archive_id, ''), namespace, external_run_id);
+
+    ALTER TABLE source_identity ADD COLUMN IF NOT EXISTS source_id TEXT;
+    ALTER TABLE source_identity ADD CONSTRAINT source_identity_source_id_length
+      CHECK (source_id IS NULL OR length(source_id) BETWEEN 1 AND 500);
+
+    CREATE TABLE IF NOT EXISTS source_import_batch (
+      id TEXT PRIMARY KEY,
+      tenant_id TEXT NOT NULL DEFAULT 'default',
+      archive_id TEXT,
+      namespace TEXT NOT NULL,
+      batch_id TEXT NOT NULL,
+      request_digest TEXT NOT NULL,
+      import_run_id TEXT NOT NULL,
+      outcome TEXT NOT NULL,
+      checkpoint JSONB NOT NULL DEFAULT '{}',
+      receipt JSONB NOT NULL DEFAULT '{}',
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_source_import_batch_scope
+      ON source_import_batch(tenant_id, COALESCE(archive_id, ''), namespace, batch_id);
+    CREATE INDEX IF NOT EXISTS idx_source_import_batch_run
+      ON source_import_batch(import_run_id);
+  `
+};
+
 // src/migrations/index.ts
 var allMigrations = [
   migration0001,
@@ -1029,7 +2144,8 @@ var allMigrations = [
   migration0020,
   migration0021,
   migration0022,
-  migration0023
+  migration0023,
+  migration0024
 ];
 
 // src/data-archive.ts
@@ -1135,13 +2251,6 @@ async function restoreDbSnapshot(source, options = {}) {
   const createOptions = { loadDataDir: data };
   return createPGliteInstance(options.persistence ?? "memory", options.archiveName ?? "default", createOptions);
 }
-function computeHash(data) {
-  const digest = sha256(data);
-  return `sha256:${bytesToHex(digest)}`;
-}
-function computeBlobHash(data) {
-  return `blake3:${bytesToHex(blake3(data))}`;
-}
 
 // src/repositories/notes-repository.ts
 var NotesRepository = class {
@@ -4401,52 +5510,79 @@ function createLazyBlobStore(archiveName, options) {
 }
 
 // src/repositories/source-upsert-repository.ts
-var DEFAULT_MAX_ITEMS = 500;
+var SOURCE_UPSERT_CONTRACT_VERSION = "1.0.0";
+var SOURCE_UPSERT_MAX_ITEMS = 500;
 function assertSource(input) {
-  if (!input.namespace || input.namespace.length > 128) throw new Error("Source namespace is required and must be <= 128 characters");
-  if (!input.external_id || input.external_id.length > 1024) throw new Error("Source external_id is required and must be <= 1024 characters");
-  if (!input.source_schema_version || input.source_schema_version.length > 64) {
-    throw new Error("Source schema version is required and must be <= 64 characters");
-  }
-  if (!input.import_run_id || input.import_run_id.length > 128) throw new Error("Source import_run_id is required and must be <= 128 characters");
+  if (!input.tenant_id || input.tenant_id.length > 200) throw new Error("invalid_batch_metadata");
+  if (!input.namespace || input.namespace.length > 200) throw new Error("invalid_batch_metadata");
+  if (!input.external_id || input.external_id.length > 1e3) throw new Error("invalid_item");
+  if (!input.source_schema_version || input.source_schema_version.length > 100) throw new Error("invalid_batch_metadata");
+  if (!input.import_run_id || input.import_run_id.length > 200) throw new Error("invalid_batch_metadata");
 }
-function sourceHash(source) {
+function sourceIdentityHash(source) {
   return computeHash(new TextEncoder().encode([
     source.tenant_id ?? "default",
-    source.archive_id ?? "",
+    source.archive_id ?? "public",
     source.namespace,
-    source.external_id
+    source.external_id,
+    ""
   ].join("\0")));
 }
-function contentDigest(content) {
+function sourceContentDigest(content) {
   return computeHash(new TextEncoder().encode(content));
 }
-async function insertNote(tx, input, noteId, digest) {
+function sourceRequestDigest(items, options) {
+  return computeHash(new TextEncoder().encode(JSON.stringify({
+    items: items.map((item) => ({
+      source: item.source,
+      title: item.title ?? null,
+      content: item.content,
+      content_digest: item.content_digest ?? null,
+      format: item.format ?? "markdown",
+      visibility: item.visibility ?? "private",
+      metadata: item.metadata ?? null,
+      policy: item.policy ?? options.policy ?? "version"
+    })),
+    checkpoint: options.checkpoint ?? null,
+    dry_run: options.dryRun === true
+  })));
+}
+function deriveSourceBatchId(requestDigest) {
+  return `derived-${requestDigest.slice("sha256:".length, "sha256:".length + 32)}`;
+}
+function sourceRunRecordId(source) {
+  return computeHash(new TextEncoder().encode([
+    source.tenant_id ?? "default",
+    source.archive_id ?? "public",
+    source.namespace,
+    source.import_run_id,
+    ""
+  ].join("\0")));
+}
+function parseReceipt(value) {
+  const parsed = typeof value === "string" ? JSON.parse(value) : value;
+  if (!parsed || typeof parsed !== "object") return null;
+  return parsed;
+}
+function duplicateReceipt(receipt) {
+  const items = receipt.items.map((item) => ({ ...item, outcome: "unchanged", reason: void 0, reason_code: void 0 }));
+  return finish(receipt.import_run_id, receipt.batch_id, false, "duplicate", items, receipt.checkpoint);
+}
+async function insertNote(tx, input, noteId, digest2) {
   const originalId = generateId();
   if (input.source.archive_id) {
-    await tx.query(
-      `INSERT INTO archive (id, name)
-       VALUES ($1, $2)
-       ON CONFLICT (id) DO NOTHING`,
-      [input.source.archive_id, input.source.archive_id]
-    );
+    await tx.query("INSERT INTO archive (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [input.source.archive_id, input.source.archive_id]);
   }
   await tx.query(
     `INSERT INTO note (id, archive_id, title, format, source, visibility)
      VALUES ($1, $2, $3, $4, $5, $6)`,
-    [
-      noteId,
-      input.source.archive_id ?? null,
-      input.title ?? null,
-      input.format ?? "markdown",
-      `source:${input.source.namespace}`,
-      input.visibility ?? "private"
-    ]
+    [noteId, input.source.archive_id ?? null, input.title ?? null, input.format ?? "markdown", `source:${input.source.namespace}`, input.visibility ?? "private"]
   );
+  await tx.query("INSERT INTO note_original (id, note_id, content, content_hash) VALUES ($1, $2, $3, $4)", [originalId, noteId, input.content, digest2]);
   await tx.query(
-    `INSERT INTO note_original (id, note_id, content, content_hash)
-     VALUES ($1, $2, $3, $4)`,
-    [originalId, noteId, input.content, digest]
+    `INSERT INTO note_revision (id, note_id, revision_number, type, content, ai_metadata)
+     VALUES ($1, $2, 1, 'source-import', $3, $4::jsonb)`,
+    [generateId(), noteId, input.content, JSON.stringify(input.metadata ?? null)]
   );
   await tx.query(
     `INSERT INTO note_revised_current (note_id, content, ai_metadata)
@@ -4454,55 +5590,26 @@ async function insertNote(tx, input, noteId, digest) {
     [noteId, input.content, JSON.stringify(input.metadata ?? null)]
   );
 }
-async function updateNote(tx, input, noteId, outcome) {
+async function updateNote(tx, input, noteId, outcome, digest2) {
   if (input.source.archive_id) {
-    await tx.query(
-      `INSERT INTO archive (id, name)
-       VALUES ($1, $2)
-       ON CONFLICT (id) DO NOTHING`,
-      [input.source.archive_id, input.source.archive_id]
-    );
+    await tx.query("INSERT INTO archive (id, name) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING", [input.source.archive_id, input.source.archive_id]);
   }
   if (outcome === "versioned") {
-    const count2 = await tx.query(
-      `SELECT COUNT(*) AS count FROM note_revision WHERE note_id = $1`,
-      [noteId]
-    );
-    const current = await tx.query(
-      `SELECT content, ai_metadata FROM note_revised_current WHERE note_id = $1`,
-      [noteId]
+    const count2 = await tx.query("SELECT COUNT(*) AS count FROM note_revision WHERE note_id = $1", [noteId]);
+    await tx.query(
+      `INSERT INTO note_revision (id, note_id, revision_number, type, content, ai_metadata)
+       VALUES ($1, $2, $3, 'source-import', $4, $5::jsonb)`,
+      [generateId(), noteId, Number.parseInt(count2.rows[0]?.count ?? "0", 10) + 1, input.content, JSON.stringify(input.metadata ?? null)]
     );
-    const nextRevision = Number.parseInt(count2.rows[0]?.count ?? "0", 10) + 1;
-    if (current.rows[0]) {
-      await tx.query(
-        `INSERT INTO note_revision (id, note_id, revision_number, type, content, ai_metadata)
-         VALUES ($1, $2, $3, 'source-import', $4, $5::jsonb)`,
-        [
-          generateId(),
-          noteId,
-          nextRevision,
-          current.rows[0].content,
-          JSON.stringify(current.rows[0].ai_metadata ?? null)
-        ]
-      );
-    }
+  } else {
+    await tx.query("UPDATE note_original SET content = $1, content_hash = $2 WHERE note_id = $3", [input.content, digest2, noteId]);
   }
   await tx.query(
-    `UPDATE note
-     SET title = $1, format = $2, visibility = $3, archive_id = $4, updated_at = now(), deleted_at = NULL
-     WHERE id = $5`,
-    [
-      input.title ?? null,
-      input.format ?? "markdown",
-      input.visibility ?? "private",
-      input.source.archive_id ?? null,
-      noteId
-    ]
+    `UPDATE note SET title = $1, format = $2, visibility = $3, archive_id = $4, updated_at = now(), deleted_at = NULL WHERE id = $5`,
+    [input.title ?? null, input.format ?? "markdown", input.visibility ?? "private", input.source.archive_id ?? null, noteId]
   );
   await tx.query(
-    `UPDATE note_revised_current
-     SET content = $1, ai_metadata = $2::jsonb, is_user_edited = false, updated_at = now()
-     WHERE note_id = $3`,
+    `UPDATE note_revised_current SET content = $1, ai_metadata = $2::jsonb, is_user_edited = false, updated_at = now() WHERE note_id = $3`,
     [input.content, JSON.stringify(input.metadata ?? null), noteId]
   );
 }
@@ -4511,184 +5618,260 @@ var SourceUpsertRepository = class {
     this.db = db;
     this.events = events;
   }
-  async upsertBatch(items, options = {}) {
-    const maxItems = options.maxItems ?? DEFAULT_MAX_ITEMS;
-    if (items.length > maxItems) throw new Error(`Source upsert batch exceeds the ${maxItems} item bound`);
-    if (items.length === 0) {
-      return {
-        import_run_id: "",
-        dry_run: options.dryRun === true,
-        outcomes: [],
-        counts: { inserted: 0, unchanged: 0, versioned: 0, replaced: 0, conflict: 0, rejected: 0 }
-      };
-    }
-    const outcomes = [];
-    for (const [index, item] of items.entries()) {
-      try {
-        assertSource(item.source);
-        outcomes.push({
-          index,
-          outcome: "rejected",
-          external_id_hash: sourceHash(item.source),
-          content_digest: contentDigest(item.content)
-        });
-      } catch (error) {
-        outcomes.push({
-          index,
-          outcome: "rejected",
-          external_id_hash: item.source ? sourceHash({ ...item.source, external_id: item.source.external_id ?? "" }) : "",
-          content_digest: contentDigest(item.content ?? ""),
-          reason: error instanceof Error ? error.message : String(error)
-        });
-      }
+  async upsertRequest(request, scope = {}) {
+    const tenant = scope.tenant_id ?? "default";
+    const memory = scope.archive_id ?? null;
+    const items = request.items.map((item) => ({
+      source: {
+        tenant_id: tenant,
+        archive_id: memory,
+        namespace: request.source_namespace,
+        external_id: item.external_id,
+        source_schema_version: request.source_schema_version,
+        import_run_id: request.import_run_id,
+        source_id: request.source_id,
+        workspace_id: request.workspace_id,
+        caller_stable_id: item.caller_stable_id
+      },
+      title: item.title,
+      content: item.content,
+      content_digest: item.content_digest,
+      format: item.format,
+      metadata: item.metadata,
+      policy: item.policy ?? request.policy
+    }));
+    const invalidCommon = request.source_id !== void 0 && (request.source_id.length === 0 || request.source_id.length > 500) || request.workspace_id !== void 0 && (request.workspace_id.length === 0 || request.workspace_id.length > 500);
+    if (invalidCommon) {
+      const batchId = request.batch_id ?? deriveSourceBatchId(sourceRequestDigest(items, {}));
+      const rejected = items.map((item, index) => ({
+        index,
+        outcome: "rejected",
+        external_id_hash: sourceIdentityHash(item.source),
+        content_digest: sourceContentDigest(item.content),
+        reason_code: "invalid_batch_metadata"
+      }));
+      return contractResponse(finish(request.import_run_id, batchId, request.dry_run === true, "rejected", rejected, request.checkpoint));
     }
-    if (outcomes.some((outcome) => outcome.reason)) {
-      return this.finish(items[0].source?.import_run_id ?? "", options.dryRun === true, outcomes);
+    return contractResponse(await this.upsertBatch(items, {
+      dryRun: request.dry_run,
+      batchId: request.batch_id,
+      checkpoint: request.checkpoint,
+      policy: request.policy
+    }));
+  }
+  async upsertBatch(items, options = {}) {
+    const maxItems = options.maxItems ?? SOURCE_UPSERT_MAX_ITEMS;
+    const importRunId = items[0]?.source.import_run_id ?? "";
+    const requestDigest = sourceRequestDigest(items, options);
+    const batchId = options.batchId ?? deriveSourceBatchId(requestDigest);
+    const batchReason = batchId.length === 0 || batchId.length > 200 ? "invalid_batch_metadata" : JSON.stringify(options.checkpoint ?? {}).length > 65536 ? "checkpoint_too_large" : void 0;
+    const validation = validateItems(items, maxItems, batchReason);
+    if (validation) {
+      return finish(importRunId, batchId, options.dryRun === true, "rejected", validation, options.checkpoint);
     }
     if (options.dryRun) {
-      const preview = [];
-      for (const [index, item] of items.entries()) {
-        const externalIdHash = sourceHash(item.source);
-        const digest = contentDigest(item.content);
-        const existing = await this.db.query(
-          `SELECT note_id, content_digest
-           FROM source_identity
-           WHERE tenant_id = $1
-             AND archive_id IS NOT DISTINCT FROM $2
-             AND namespace = $3
-             AND external_id = $4
-           LIMIT 1`,
-          [item.source.tenant_id ?? "default", item.source.archive_id ?? null, item.source.namespace, item.source.external_id]
-        );
-        if (existing.rows.length === 0) {
-          preview.push({ index, outcome: "inserted", external_id_hash: externalIdHash, content_digest: digest });
-        } else if (existing.rows[0].content_digest === digest) {
-          preview.push({ index, outcome: "unchanged", note_id: existing.rows[0].note_id, external_id_hash: externalIdHash, content_digest: digest });
-        } else if ((item.policy ?? "version") === "conflict") {
-          preview.push({ index, outcome: "conflict", note_id: existing.rows[0].note_id, external_id_hash: externalIdHash, content_digest: digest });
-        } else {
-          preview.push({
+      const preview = await previewItems(this.db, items, options.policy);
+      return finish(importRunId, batchId, true, "preview", preview, options.checkpoint);
+    }
+    const response = await this.db.transaction(async (tx) => {
+      const prior = await tx.query(
+        `SELECT request_digest, receipt FROM source_import_batch
+         WHERE tenant_id = $1 AND archive_id IS NOT DISTINCT FROM $2 AND namespace = $3 AND batch_id = $4 LIMIT 1`,
+        [items[0].source.tenant_id ?? "default", items[0].source.archive_id ?? null, items[0].source.namespace, batchId]
+      );
+      if (prior.rows[0]) {
+        if (prior.rows[0].request_digest !== requestDigest) {
+          const rejected = items.map((item, index) => ({
             index,
-            outcome: item.policy === "replace" ? "replaced" : "versioned",
-            note_id: existing.rows[0].note_id,
-            external_id_hash: externalIdHash,
-            content_digest: digest
-          });
+            outcome: "rejected",
+            external_id_hash: sourceIdentityHash(item.source),
+            content_digest: sourceContentDigest(item.content),
+            reason_code: "batch_id_reused_with_different_request"
+          }));
+          return finish(importRunId, batchId, false, "rejected", rejected, options.checkpoint);
+        }
+        const receipt = parseReceipt(prior.rows[0].receipt);
+        if (!receipt) throw new Error("Stored source upsert receipt is invalid");
+        return duplicateReceipt(receipt);
+      }
+      for (const item of items) {
+        if (!item.source.caller_stable_id) continue;
+        const collision = await tx.query("SELECT id FROM note WHERE id = $1 LIMIT 1", [item.source.caller_stable_id]);
+        if (collision.rows[0]) {
+          const mapped = await findExisting(tx, item);
+          if (mapped?.note_id === item.source.caller_stable_id) continue;
+          const rejected = items.map((candidate, index) => ({
+            index,
+            outcome: "rejected",
+            external_id_hash: sourceIdentityHash(candidate.source),
+            content_digest: sourceContentDigest(candidate.content),
+            reason_code: "caller_stable_id_conflict"
+          }));
+          return finish(importRunId, batchId, false, "rejected", rejected, options.checkpoint);
         }
       }
-      return this.finish(items[0].source.import_run_id, true, preview);
-    }
-    await this.db.transaction(async (tx) => {
+      const outcomes = [];
       for (const [index, item] of items.entries()) {
-        const externalIdHash = sourceHash(item.source);
-        const digest = contentDigest(item.content);
-        const existing = await tx.query(
-          `SELECT note_id, content_digest
-           FROM source_identity
-           WHERE tenant_id = $1
-             AND archive_id IS NOT DISTINCT FROM $2
-             AND namespace = $3
-             AND external_id = $4
-           LIMIT 1`,
-          [item.source.tenant_id ?? "default", item.source.archive_id ?? null, item.source.namespace, item.source.external_id]
-        );
-        if (existing.rows.length === 0) {
+        const externalIdHash = sourceIdentityHash(item.source);
+        const digest2 = sourceContentDigest(item.content);
+        const existing = await findExisting(tx, item);
+        if (!existing) {
           const noteId = item.source.caller_stable_id ?? generateId();
-          await insertNote(tx, item, noteId, digest);
+          await insertNote(tx, item, noteId, digest2);
           await tx.query(
             `INSERT INTO source_identity
-              (id, tenant_id, archive_id, namespace, external_id, external_id_hash,
-               source_schema_version, content_digest, import_run_id, caller_stable_id, note_id)
-             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
-            [
-              generateId(),
-              item.source.tenant_id ?? "default",
-              item.source.archive_id ?? null,
-              item.source.namespace,
-              item.source.external_id,
-              externalIdHash,
-              item.source.source_schema_version,
-              digest,
-              item.source.import_run_id,
-              item.source.caller_stable_id ?? null,
-              noteId
-            ]
+              (id, tenant_id, archive_id, namespace, external_id, external_id_hash, source_id, source_schema_version, content_digest, import_run_id, caller_stable_id, note_id)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12)`,
+            [generateId(), item.source.tenant_id ?? "default", item.source.archive_id ?? null, item.source.namespace, item.source.external_id, externalIdHash, item.source.source_id ?? null, item.source.source_schema_version, digest2, item.source.import_run_id, item.source.caller_stable_id ?? null, noteId]
           );
-          outcomes[index] = { index, outcome: "inserted", note_id: noteId, external_id_hash: externalIdHash, content_digest: digest };
+          outcomes.push({ index, outcome: "inserted", note_id: noteId, external_id_hash: externalIdHash, content_digest: digest2 });
           continue;
         }
-        const row = existing.rows[0];
-        if (row.content_digest === digest) {
-          outcomes[index] = { index, outcome: "unchanged", note_id: row.note_id, external_id_hash: externalIdHash, content_digest: digest };
+        if (existing.content_digest === digest2) {
+          outcomes.push({ index, outcome: "unchanged", note_id: existing.note_id, external_id_hash: externalIdHash, content_digest: digest2 });
           continue;
         }
-        const policy = item.policy ?? "version";
+        const policy = item.policy ?? options.policy ?? "version";
         if (policy === "conflict") {
-          outcomes[index] = { index, outcome: "conflict", note_id: row.note_id, external_id_hash: externalIdHash, content_digest: digest };
+          outcomes.push({ index, outcome: "conflict", note_id: existing.note_id, external_id_hash: externalIdHash, content_digest: digest2 });
           continue;
         }
         const outcome = policy === "replace" ? "replaced" : "versioned";
-        await updateNote(tx, item, row.note_id, outcome);
+        await updateNote(tx, item, existing.note_id, outcome, digest2);
         await tx.query(
-          `UPDATE source_identity
-           SET source_schema_version = $1, content_digest = $2, import_run_id = $3, updated_at = now()
-           WHERE note_id = $4
-             AND tenant_id = $5
-             AND archive_id IS NOT DISTINCT FROM $6
-             AND namespace = $7
-             AND external_id = $8`,
-          [
-            item.source.source_schema_version,
-            digest,
-            item.source.import_run_id,
-            row.note_id,
-            item.source.tenant_id ?? "default",
-            item.source.archive_id ?? null,
-            item.source.namespace,
-            item.source.external_id
-          ]
-        );
-        outcomes[index] = { index, outcome, note_id: row.note_id, external_id_hash: externalIdHash, content_digest: digest };
-      }
-      if (hasMaterialChange(outcomes)) {
-        await tx.query(
-          `INSERT INTO source_import_run (id, tenant_id, archive_id, namespace, completed_at, checkpoint, receipt)
-           VALUES ($1, $2, $3, $4, now(), $5::jsonb, $6::jsonb)
-           ON CONFLICT (id) DO UPDATE
-             SET completed_at = EXCLUDED.completed_at,
-                 checkpoint = EXCLUDED.checkpoint,
-                 receipt = EXCLUDED.receipt`,
-          [
-            items[0].source.import_run_id,
-            items[0].source.tenant_id ?? "default",
-            items[0].source.archive_id ?? null,
-            items[0].source.namespace,
-            JSON.stringify({ item_count: items.length }),
-            JSON.stringify({ counts: countOutcomes(outcomes) })
-          ]
+          `UPDATE source_identity SET source_id = $1, source_schema_version = $2, content_digest = $3, import_run_id = $4, updated_at = now()
+           WHERE note_id = $5 AND tenant_id = $6 AND archive_id IS NOT DISTINCT FROM $7 AND namespace = $8 AND external_id = $9`,
+          [item.source.source_id ?? null, item.source.source_schema_version, digest2, item.source.import_run_id, existing.note_id, item.source.tenant_id ?? "default", item.source.archive_id ?? null, item.source.namespace, item.source.external_id]
         );
+        outcomes.push({ index, outcome, note_id: existing.note_id, external_id_hash: externalIdHash, content_digest: digest2 });
       }
+      const committed = finish(importRunId, batchId, false, "committed", outcomes, options.checkpoint);
+      await tx.query(
+        `INSERT INTO source_import_run (id, tenant_id, archive_id, namespace, external_run_id, source_id, source_schema_version, workspace_id, completed_at, checkpoint, receipt)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, now(), $9::jsonb, $10::jsonb)
+         ON CONFLICT (id) DO UPDATE SET source_id = EXCLUDED.source_id, source_schema_version = EXCLUDED.source_schema_version, workspace_id = EXCLUDED.workspace_id, completed_at = EXCLUDED.completed_at, checkpoint = EXCLUDED.checkpoint, receipt = EXCLUDED.receipt`,
+        [sourceRunRecordId(items[0].source), items[0].source.tenant_id ?? "default", items[0].source.archive_id ?? null, items[0].source.namespace, importRunId, items[0].source.source_id ?? null, items[0].source.source_schema_version, items[0].source.workspace_id ?? null, JSON.stringify(options.checkpoint ?? {}), JSON.stringify(redactedReceipt(committed))]
+      );
+      await tx.query(
+        `INSERT INTO source_import_batch (id, tenant_id, archive_id, namespace, batch_id, request_digest, import_run_id, outcome, checkpoint, receipt)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, 'committed', $8::jsonb, $9::jsonb)`,
+        [generateId(), items[0].source.tenant_id ?? "default", items[0].source.archive_id ?? null, items[0].source.namespace, batchId, requestDigest, importRunId, JSON.stringify(options.checkpoint ?? {}), JSON.stringify(redactedReceipt(committed))]
+      );
+      return committed;
     });
-    if (hasMaterialChange(outcomes)) {
-      this.events?.emit("source.upserted", { importRunId: items[0].source.import_run_id, counts: countOutcomes(outcomes) });
+    if (response.outcome === "committed" && hasMaterialChange(response.items)) {
+      this.events?.emit("source.upserted", { importRunId, counts: response.counts });
     }
-    return this.finish(items[0].source.import_run_id, false, outcomes);
-  }
-  finish(importRunId, dryRun, outcomes) {
-    return { import_run_id: importRunId, dry_run: dryRun, outcomes, counts: countOutcomes(outcomes) };
+    return response;
   }
 };
+async function findExisting(tx, item) {
+  const result = await tx.query(
+    `SELECT note_id, content_digest FROM source_identity
+     WHERE tenant_id = $1 AND archive_id IS NOT DISTINCT FROM $2 AND namespace = $3 AND external_id = $4 LIMIT 1`,
+    [item.source.tenant_id ?? "default", item.source.archive_id ?? null, item.source.namespace, item.source.external_id]
+  );
+  return result.rows[0] ?? null;
+}
+async function previewItems(db, items, batchPolicy) {
+  const preview = [];
+  for (const [index, item] of items.entries()) {
+    const external_id_hash = sourceIdentityHash(item.source);
+    const content_digest = sourceContentDigest(item.content);
+    const existing = await findExisting(db, item);
+    if (!existing) preview.push({ index, outcome: "inserted", external_id_hash, content_digest });
+    else if (existing.content_digest === content_digest) preview.push({ index, outcome: "unchanged", note_id: existing.note_id, external_id_hash, content_digest });
+    else if ((item.policy ?? batchPolicy ?? "version") === "conflict") preview.push({ index, outcome: "conflict", note_id: existing.note_id, external_id_hash, content_digest });
+    else preview.push({ index, outcome: (item.policy ?? batchPolicy) === "replace" ? "replaced" : "versioned", note_id: existing.note_id, external_id_hash, content_digest });
+  }
+  return preview;
+}
+function validateItems(items, maxItems, initialReason) {
+  const seen = /* @__PURE__ */ new Set();
+  const stableIds = /* @__PURE__ */ new Set();
+  const rejected = [];
+  let batchReason = initialReason ?? (items.length === 0 || items.length > maxItems ? "batch_size_out_of_bounds" : null);
+  for (const [index, item] of items.entries()) {
+    const digest2 = sourceContentDigest(item.content ?? "");
+    let reason = batchReason;
+    try {
+      assertSource(item.source);
+      if (!item.content || item.content.length > 4194304) reason ??= "invalid_item";
+      if ((item.format ?? "markdown").length > 100 || (item.title?.length ?? 0) > 2e3 || JSON.stringify(item.metadata ?? {}).length > 262144) reason ??= "invalid_item";
+      if (item.content_digest && item.content_digest !== digest2) reason ??= "content_digest_mismatch";
+      const identity = `${item.source.tenant_id ?? "default"}\0${item.source.archive_id ?? ""}\0${item.source.namespace}\0${item.source.external_id}`;
+      if (seen.has(identity)) reason ??= "duplicate_external_id_in_batch";
+      seen.add(identity);
+      if (item.source.caller_stable_id && stableIds.has(item.source.caller_stable_id)) reason ??= "caller_stable_id_conflict";
+      if (item.source.caller_stable_id) stableIds.add(item.source.caller_stable_id);
+    } catch (error) {
+      const code = error instanceof Error ? error.message : "invalid_item";
+      reason ??= code === "invalid_batch_metadata" ? code : "invalid_item";
+    }
+    if (reason) {
+      batchReason = reason;
+      rejected.push({ index, outcome: "rejected", external_id_hash: sourceIdentityHash(item.source), content_digest: digest2, reason_code: reason });
+    }
+  }
+  if (!batchReason) return null;
+  if (rejected.length === items.length) return rejected;
+  return items.map((item, index) => rejected.find((result) => result.index === index) ?? {
+    index,
+    outcome: "rejected",
+    external_id_hash: sourceIdentityHash(item.source),
+    content_digest: sourceContentDigest(item.content),
+    reason_code: batchReason
+  });
+}
+function finish(importRunId, batchId, dryRun, outcome, items, checkpoint) {
+  return {
+    contract_version: SOURCE_UPSERT_CONTRACT_VERSION,
+    import_run_id: importRunId,
+    batch_id: batchId,
+    dry_run: dryRun,
+    outcome,
+    ...checkpoint ? { checkpoint } : {},
+    items,
+    outcomes: items,
+    counts: countOutcomes(items)
+  };
+}
+function redactedReceipt(receipt) {
+  return { ...contractResponse(receipt), items: receipt.items.map(sanitizeItem) };
+}
+function contractResponse(receipt) {
+  return {
+    contract_version: receipt.contract_version,
+    import_run_id: receipt.import_run_id,
+    batch_id: receipt.batch_id,
+    dry_run: receipt.dry_run,
+    outcome: receipt.outcome,
+    ...receipt.checkpoint ? { checkpoint: receipt.checkpoint } : {},
+    counts: receipt.counts,
+    items: receipt.items
+  };
+}
+function sanitizeItem(item) {
+  return {
+    index: item.index,
+    outcome: item.outcome,
+    ...item.note_id ? { note_id: item.note_id } : {},
+    external_id_hash: item.external_id_hash,
+    content_digest: item.content_digest,
+    ...item.reason_code ? { reason_code: item.reason_code } : {}
+  };
+}
 function hasMaterialChange(outcomes) {
-  return outcomes.some((outcome) => outcome.outcome === "inserted" || outcome.outcome === "versioned" || outcome.outcome === "replaced");
+  return outcomes.some((item) => item.outcome === "inserted" || item.outcome === "versioned" || item.outcome === "replaced");
 }
 function countOutcomes(outcomes) {
   return {
-    inserted: outcomes.filter((outcome) => outcome.outcome === "inserted").length,
-    unchanged: outcomes.filter((outcome) => outcome.outcome === "unchanged").length,
-    versioned: outcomes.filter((outcome) => outcome.outcome === "versioned").length,
-    replaced: outcomes.filter((outcome) => outcome.outcome === "replaced").length,
-    conflict: outcomes.filter((outcome) => outcome.outcome === "conflict").length,
-    rejected: outcomes.filter((outcome) => outcome.outcome === "rejected").length
+    inserted: outcomes.filter((item) => item.outcome === "inserted").length,
+    unchanged: outcomes.filter((item) => item.outcome === "unchanged").length,
+    versioned: outcomes.filter((item) => item.outcome === "versioned").length,
+    replaced: outcomes.filter((item) => item.outcome === "replaced").length,
+    conflict: outcomes.filter((item) => item.outcome === "conflict").length,
+    rejected: outcomes.filter((item) => item.outcome === "rejected").length
   };
 }
 
@@ -5591,7 +6774,7 @@ function titleGenerationHandler(job, db) {
 
 Note content:
 ${content.slice(0, 1e3)}`;
-      const llmTitle = (await llmFn2(prompt, { maxTokens: 60, temperature: 0.3 })).trim();
+      const llmTitle = (await llmFn2(prompt, { maxTokens: 60, temperature: 0.3, task: "chat.general" })).trim();
       if (llmTitle) {
         const title2 = llmTitle.length > 200 ? llmTitle.slice(0, 197) + "..." : llmTitle;
         await db.query(
@@ -5632,7 +6815,7 @@ Respond with ONLY the enhanced note content, no explanation.
 
 Original note:
 ${content}`;
-    const revised = (await llmFn2(prompt, { maxTokens: 2e3, temperature: 0.4 })).trim();
+    const revised = (await llmFn2(prompt, { maxTokens: 2e3, temperature: 0.4, task: "chat.revision" })).trim();
     if (!revised || revised === content) return { skipped: true, reason: "no changes from LLM" };
     const revResult = await db.query(
       `SELECT COALESCE(MAX(revision_number), 0) as max_rev FROM note_revision WHERE note_id = $1`,
@@ -5673,7 +6856,7 @@ Text:
 ${content.slice(0, 1500)}
 
 Tags:`;
-    const response = (await llmFn2(prompt, { maxTokens: 60, temperature: 0.1 })).trim();
+    const response = (await llmFn2(prompt, { maxTokens: 60, temperature: 0.1, task: "chat.tagging" })).trim();
     const tags = response.split(/[,\n]/).map((t) => t.trim().toLowerCase().replace(/^[-*\d.]+\s*/, "").replace(/['"]/g, "")).filter((t) => {
       if (t.length < 2 || t.length > 40) return false;
       if (/^\d+$/.test(t)) return false;
@@ -6956,10 +8139,24 @@ function chunkText(text, maxChars = 800, overlap = 100) {
 }
 
 // src/capabilities/embedding-handler.ts
+var DEFAULT_LARGE_DOCUMENT_CHARS = 12e3;
+var DEFAULT_LARGE_DOCUMENT_CHUNKS = 12;
 var embedFn = null;
+var embeddingTaskSelectionOptions = {};
 function setEmbedFunction(fn) {
   embedFn = fn;
 }
+function setEmbeddingTaskSelectionOptions(options = {}) {
+  embeddingTaskSelectionOptions = { ...options };
+}
+function getEmbeddingTaskSelectionOptions() {
+  return { ...embeddingTaskSelectionOptions };
+}
+function selectEmbeddingTask(content, chunks, options = {}) {
+  const largeDocumentChars = options.largeDocumentChars ?? DEFAULT_LARGE_DOCUMENT_CHARS;
+  const largeDocumentChunks = options.largeDocumentChunks ?? DEFAULT_LARGE_DOCUMENT_CHUNKS;
+  return content.length >= largeDocumentChars || chunks.length >= largeDocumentChunks ? "embedding.large-document" : "embedding.document";
+}
 function getEmbedFunction() {
   return embedFn;
 }
@@ -6985,7 +8182,8 @@ async function embeddingGenerationHandler(job, db) {
   if (!noteText) return { skipped: true, reason: "note missing, deleted, or has no content" };
   const content = noteText.combined;
   const chunks = chunkText(content);
-  const embeddings = await fn(chunks);
+  const task = selectEmbeddingTask(content, chunks, embeddingTaskSelectionOptions);
+  const embeddings = await fn(chunks, { task });
   const vector = averageEmbeddings(embeddings);
   const embeddingSets = new EmbeddingSetsRepository(db);
   const set = await embeddingSets.ensureDefault();
@@ -6994,7 +8192,7 @@ async function embeddingGenerationHandler(job, db) {
     embedding_set_id: set.id,
     vector
   });
-  return { chunks: chunks.length, embeddings: embeddings.length, setId: set.id };
+  return { chunks: chunks.length, embeddings: embeddings.length, setId: set.id, task };
 }
 
 // src/capabilities/auto-tag.ts
@@ -7153,6 +8351,226 @@ function unregisterLlmCapability() {
   setLlmFunction(null);
 }
 
+// src/capabilities/fallback-router.ts
+var DEFAULT_COOLDOWNS = {
+  rateLimit: 3e4,
+  serverError: 6e4,
+  connectionFailure: 3e5,
+  contentPolicy: 0
+};
+function classifyError(error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  const lower = msg.toLowerCase();
+  if (lower.includes("429") || lower.includes("rate limit")) return "rate_limit";
+  if (lower.includes("500") || lower.includes("502") || lower.includes("503") || lower.includes("504")) return "server_error";
+  if (lower.includes("content") && (lower.includes("policy") || lower.includes("filter"))) return "content_policy";
+  if (lower.includes("context") && (lower.includes("window") || lower.includes("length") || lower.includes("too long"))) return "context_window";
+  if (lower.includes("fetch") || lower.includes("network") || lower.includes("connection") || lower.includes("econnrefused") || lower.includes("timeout")) return "connection_failure";
+  return "unknown";
+}
+var FallbackRouter = class {
+  id = "fallback-router";
+  name = "Fallback Router";
+  tier = "remote";
+  providers;
+  cooldowns;
+  cooldownMap = /* @__PURE__ */ new Map();
+  events;
+  get capabilities() {
+    const available = this.getAvailableProviders();
+    return {
+      embeddings: available.some((p) => p.capabilities.embeddings),
+      chat: available.some((p) => p.capabilities.chat),
+      streaming: available.some((p) => p.capabilities.streaming),
+      vision: available.some((p) => p.capabilities.vision),
+      toolCalling: available.some((p) => p.capabilities.toolCalling),
+      structuredOutput: available.some((p) => p.capabilities.structuredOutput),
+      maxContextTokens: Math.max(
+        ...available.map((p) => p.capabilities.maxContextTokens ?? 0),
+        0
+      )
+    };
+  }
+  constructor(config) {
+    this.providers = [...config.providers];
+    this.cooldowns = { ...DEFAULT_COOLDOWNS, ...config.cooldowns };
+    this.events = config.events;
+  }
+  // -------------------------------------------------------------------------
+  // Provider management
+  // -------------------------------------------------------------------------
+  /** Get providers not currently in cooldown */
+  getAvailableProviders() {
+    const now2 = Date.now();
+    return this.providers.filter((p) => {
+      const cd = this.cooldownMap.get(p.id);
+      if (!cd) return true;
+      if (now2 >= cd.expiresAt) {
+        this.cooldownMap.delete(p.id);
+        return true;
+      }
+      return false;
+    });
+  }
+  /** Get providers in cooldown with their expiry info */
+  getCoolingDown() {
+    const now2 = Date.now();
+    const result = [];
+    for (const [id, entry] of this.cooldownMap) {
+      if (now2 < entry.expiresAt) {
+        result.push({ providerId: id, category: entry.category, expiresAt: entry.expiresAt });
+      }
+    }
+    return result;
+  }
+  /** Manually clear cooldown for a provider */
+  clearCooldown(providerId) {
+    this.cooldownMap.delete(providerId);
+  }
+  /** Clear all cooldowns */
+  clearAllCooldowns() {
+    this.cooldownMap.clear();
+  }
+  /** Add a provider to the chain (appended at lowest priority) */
+  addProvider(provider) {
+    this.providers.push(provider);
+  }
+  /** Remove a provider from the chain */
+  removeProvider(id) {
+    this.providers = this.providers.filter((p) => p.id !== id);
+    this.cooldownMap.delete(id);
+  }
+  /** Reorder providers (new priority order) */
+  setOrder(ids) {
+    const byId = new Map(this.providers.map((p) => [p.id, p]));
+    const reordered = [];
+    for (const id of ids) {
+      const p = byId.get(id);
+      if (p) reordered.push(p);
+    }
+    for (const p of this.providers) {
+      if (!ids.includes(p.id)) reordered.push(p);
+    }
+    this.providers = reordered;
+  }
+  // -------------------------------------------------------------------------
+  // InferenceProvider interface — with fallback
+  // -------------------------------------------------------------------------
+  async embed(request) {
+    return this.withFallback(
+      (p) => p.capabilities.embeddings && !!p.embed,
+      (p) => p.embed(request)
+    );
+  }
+  async complete(request) {
+    return this.withFallback(
+      (p) => p.capabilities.chat && !!p.complete,
+      (p) => p.complete(request)
+    );
+  }
+  async *stream(request) {
+    const candidates = this.getAvailableProviders().filter((p) => p.capabilities.streaming && p.stream);
+    if (candidates.length === 0) {
+      throw new Error("No available providers with streaming capability");
+    }
+    yield* candidates[0].stream(request);
+  }
+  async listModels() {
+    const available = this.getAvailableProviders();
+    const results = await Promise.allSettled(
+      available.map((p) => p.listModels())
+    );
+    const models = [];
+    for (const r of results) {
+      if (r.status === "fulfilled") models.push(...r.value);
+    }
+    return models;
+  }
+  async probe() {
+    const available = this.getAvailableProviders();
+    if (available.length === 0) {
+      return { status: "down", latencyMs: 0, message: "All providers in cooldown" };
+    }
+    const start = Date.now();
+    const results = await Promise.allSettled(
+      available.map((p) => p.probe())
+    );
+    const okCount = results.filter(
+      (r) => r.status === "fulfilled" && r.value.status === "ok"
+    ).length;
+    return {
+      status: okCount === available.length ? "ok" : okCount > 0 ? "degraded" : "down",
+      latencyMs: Date.now() - start,
+      message: `${okCount}/${available.length} providers healthy`
+    };
+  }
+  dispose() {
+    for (const p of this.providers) {
+      p.dispose();
+    }
+    this.providers = [];
+    this.cooldownMap.clear();
+  }
+  // -------------------------------------------------------------------------
+  // Core fallback logic
+  // -------------------------------------------------------------------------
+  async withFallback(filter, execute) {
+    const candidates = this.getAvailableProviders().filter(filter);
+    if (candidates.length === 0) {
+      throw new Error("No available providers for this request");
+    }
+    let lastError;
+    for (const provider of candidates) {
+      try {
+        return await execute(provider);
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        const category = classifyError(err);
+        this.applyCooldown(provider.id, category);
+        const nextCandidate = candidates[candidates.indexOf(provider) + 1];
+        if (nextCandidate) {
+          this.events?.emit("provider.fallback", {
+            fromProvider: provider.id,
+            toProvider: nextCandidate.id,
+            errorCategory: category,
+            error: lastError.message
+          });
+        }
+      }
+    }
+    throw lastError ?? new Error("All providers failed");
+  }
+  applyCooldown(providerId, category) {
+    let cooldownMs;
+    switch (category) {
+      case "rate_limit":
+        cooldownMs = this.cooldowns.rateLimit;
+        break;
+      case "server_error":
+        cooldownMs = this.cooldowns.serverError;
+        break;
+      case "connection_failure":
+        cooldownMs = this.cooldowns.connectionFailure;
+        break;
+      case "content_policy":
+        cooldownMs = this.cooldowns.contentPolicy;
+        break;
+      default:
+        cooldownMs = this.cooldowns.serverError;
+    }
+    if (cooldownMs > 0) {
+      const expiresAt = Date.now() + cooldownMs;
+      this.cooldownMap.set(providerId, { expiresAt, category });
+      this.events?.emit("provider.cooldown", {
+        providerId,
+        errorCategory: category,
+        cooldownMs,
+        expiresAt
+      });
+    }
+  }
+};
+
 // src/capabilities/provider-registry.ts
 var ProviderRegistry = class {
   constructor(events) {
@@ -7160,6 +8578,7 @@ var ProviderRegistry = class {
   }
   providers = /* @__PURE__ */ new Map();
   activeId = null;
+  routes = /* @__PURE__ */ new Map();
   /** Register a provider. First provider with embedding capability becomes active. */
   add(provider) {
     if (this.providers.has(provider.id)) {
@@ -7197,6 +8616,36 @@ var ProviderRegistry = class {
     this.syncLegacyFunctions();
     this.events?.emit("provider.active", { id, name: provider.name });
   }
+  setRoute(task, policy) {
+    const cloned = cloneProviderRoutePolicy(policy);
+    this.routes.set(task, cloned);
+    this.events?.emit("provider.route.configured", {
+      task,
+      providerIds: cloned.providerIds ?? [],
+      model: cloned.model,
+      fallback: cloned.fallback,
+      hasRequirements: Boolean(cloned.requirements)
+    });
+  }
+  getRoute(task) {
+    const route = this.routes.get(task);
+    return route ? cloneProviderRoutePolicy(route) : void 0;
+  }
+  clearRoute(task) {
+    this.routes.delete(task);
+    this.events?.emit("provider.route.cleared", { task });
+  }
+  clearRoutes() {
+    const tasks = Array.from(this.routes.keys());
+    this.routes.clear();
+    if (tasks.length === 0) {
+      this.events?.emit("provider.route.cleared", {});
+      return;
+    }
+    for (const task of tasks) {
+      this.events?.emit("provider.route.cleared", { task });
+    }
+  }
   /** Get the currently active provider */
   getActive() {
     if (!this.activeId) return null;
@@ -7228,27 +8677,51 @@ var ProviderRegistry = class {
   }
   /** Convenience: embed using active provider */
   async embed(request) {
-    const provider = this.getActive();
-    if (!provider?.embed) {
-      throw new Error("No active provider with embedding capability");
-    }
-    return provider.embed(request);
+    const route = request.task ? this.routes.get(request.task) : void 0;
+    return this.withRouteFallback(request.task, "embeddings", request.model, async (selection) => {
+      if (!selection.provider.embed) throw new Error("No routed provider with embedding capability");
+      return selection.provider.embed(withResolvedModel(request, selection.model));
+    }, route?.fallback !== false);
   }
   /** Convenience: complete using active provider */
   async complete(request) {
-    const provider = this.getActive();
-    if (!provider?.complete) {
-      throw new Error("No active provider with chat capability");
-    }
-    return provider.complete(request);
+    const route = request.task ? this.routes.get(request.task) : void 0;
+    return this.withRouteFallback(request.task, "chat", request.model, async (selection) => {
+      if (!selection.provider.complete) throw new Error("No routed provider with chat capability");
+      return selection.provider.complete(withResolvedModel(request, selection.model));
+    }, route?.fallback !== false);
   }
   /** Convenience: stream using active provider */
   stream(request) {
-    const provider = this.getActive();
-    if (!provider?.stream) {
-      throw new Error("No active provider with streaming capability");
-    }
-    return provider.stream(request);
+    const { provider, model } = this.resolveProvider(request.task, "streaming", request.model, true);
+    if (!provider.stream) throw new Error("No routed provider with streaming capability");
+    return provider.stream(withResolvedModel(request, model));
+  }
+  previewRoute(task, capability, requestModel) {
+    const { provider, model, routeMatched } = this.resolveProvider(task, capability, requestModel, false);
+    return {
+      provider,
+      providerId: provider.id,
+      providerName: provider.name,
+      tier: provider.tier,
+      capability,
+      task,
+      model,
+      routeMatched
+    };
+  }
+  async probeRoute(task, capability, requestModel) {
+    const selection = this.previewRoute(task, capability, requestModel);
+    const probe = await selection.provider.probe();
+    return { ...selection, probe };
+  }
+  validateRoute(task, capability = inferInferenceTaskCapability(task), policy = this.routes.get(task)) {
+    return validateProviderRoute(task, capability, policy, this.list());
+  }
+  validateRoutes() {
+    return Array.from(this.routes.entries()).map(
+      ([task, policy]) => this.validateRoute(task, inferInferenceTaskCapability(task), policy)
+    );
   }
   /** Dispose all providers */
   dispose() {
@@ -7270,29 +8743,357 @@ var ProviderRegistry = class {
   syncLegacyFunctions() {
     const active = this.getActive();
     if (active?.embed && active.capabilities.embeddings) {
-      const embedBridge = (texts) => active.embed({ texts }).then((r) => r.vectors);
+      const embedBridge = (texts, options) => {
+        const request = {
+          texts,
+          task: options?.task ?? "embedding.document"
+        };
+        if (options?.model) request.model = options.model;
+        return this.embed(request).then((r) => r.vectors);
+      };
       setEmbedFunction(embedBridge);
     } else {
       setEmbedFunction(null);
     }
     if (active?.complete && active.capabilities.chat) {
-      const llmBridge = (prompt, options) => active.complete({
-        prompt,
-        maxTokens: options?.maxTokens,
-        temperature: options?.temperature
-      }).then((r) => r.text);
+      const llmBridge = (prompt, options) => {
+        const request = {
+          prompt,
+          task: options?.task ?? "chat.general"
+        };
+        if (options?.model) request.model = options.model;
+        if (options?.maxTokens !== void 0) request.maxTokens = options.maxTokens;
+        if (options?.temperature !== void 0) request.temperature = options.temperature;
+        return this.complete(request).then((r) => r.text);
+      };
       setLlmFunction(llmBridge);
     } else {
       setLlmFunction(null);
     }
   }
+  resolveProvider(task, capability, requestModel, emitSelection = false) {
+    const candidates = this.resolveRouteSelections(task, capability, requestModel);
+    const selection = candidates[0];
+    if (!selection) {
+      const label = task ? ` for task '${task}'` : "";
+      throw new Error(`No provider satisfies ${String(capability)} route${label}`);
+    }
+    if (emitSelection) {
+      this.emitRouteSelected(selection);
+    }
+    return selection;
+  }
+  resolveRouteSelections(task, capability, requestModel) {
+    const route = task ? this.routes.get(task) : void 0;
+    const model = requestModel ?? route?.model;
+    const routeMatched = Boolean(route);
+    return this.resolveCandidates(route, capability).filter((provider) => Boolean(provider.capabilities[capability])).filter((provider) => capability !== "embeddings" || Boolean(provider.embed)).filter((provider) => capability !== "chat" || Boolean(provider.complete)).filter((provider) => capability !== "streaming" || Boolean(provider.stream)).map((provider) => ({
+      provider,
+      providerId: provider.id,
+      providerName: provider.name,
+      tier: provider.tier,
+      capability,
+      task,
+      model,
+      routeMatched
+    }));
+  }
+  emitRouteSelected(selection) {
+    this.events?.emit("provider.route.selected", {
+      providerId: selection.providerId,
+      providerName: selection.providerName,
+      tier: selection.tier,
+      capability: String(selection.capability),
+      task: selection.task,
+      model: selection.model,
+      routeMatched: selection.routeMatched
+    });
+  }
+  async withRouteFallback(task, capability, requestModel, execute, allowFallback) {
+    const selections = this.resolveRouteSelections(task, capability, requestModel);
+    const candidates = allowFallback ? selections : selections.slice(0, 1);
+    if (!candidates.length) {
+      const label = task ? ` for task '${task}'` : "";
+      const route = task ? this.routes.get(task) : void 0;
+      this.emitRouteFailed(
+        void 0,
+        capability,
+        task,
+        requestModel ?? route?.model,
+        Boolean(route),
+        0,
+        0,
+        0,
+        "no_provider",
+        `No provider satisfies ${String(capability)} route${label}`
+      );
+      throw new Error(`No provider satisfies ${String(capability)} route${label}`);
+    }
+    let lastError;
+    let lastSelection;
+    let lastErrorCategory = "unknown";
+    const start = Date.now();
+    for (let index = 0; index < candidates.length; index++) {
+      const selection = candidates[index];
+      try {
+        this.emitRouteSelected(selection);
+        const result = await execute(selection);
+        this.emitRouteCompleted(selection, index + 1, index, Date.now() - start);
+        return result;
+      } catch (err) {
+        lastSelection = selection;
+        lastError = err instanceof Error ? err : new Error(String(err));
+        lastErrorCategory = classifyError(err);
+        const next = candidates[index + 1];
+        if (next) {
+          this.events?.emit("provider.fallback", {
+            fromProvider: selection.providerId,
+            toProvider: next.providerId,
+            errorCategory: lastErrorCategory,
+            error: lastError.message
+          });
+        }
+      }
+    }
+    this.emitRouteFailed(
+      lastSelection,
+      capability,
+      task,
+      requestModel,
+      candidates[0]?.routeMatched ?? Boolean(task && this.routes.get(task)),
+      candidates.length,
+      Math.max(candidates.length - 1, 0),
+      Date.now() - start,
+      lastErrorCategory,
+      lastError?.message ?? "All routed providers failed"
+    );
+    throw lastError ?? new Error("All routed providers failed");
+  }
+  emitRouteCompleted(selection, attempt, fallbackCount, latencyMs) {
+    this.events?.emit("provider.route.completed", {
+      providerId: selection.providerId,
+      providerName: selection.providerName,
+      tier: selection.tier,
+      capability: String(selection.capability),
+      task: selection.task,
+      model: selection.model,
+      routeMatched: selection.routeMatched,
+      attempt,
+      fallbackCount,
+      latencyMs
+    });
+  }
+  emitRouteFailed(selection, capability, task, model, routeMatched, attempt, fallbackCount, latencyMs, errorCategory, error) {
+    this.events?.emit("provider.route.failed", {
+      providerId: selection?.providerId,
+      providerName: selection?.providerName,
+      tier: selection?.tier,
+      capability: String(capability),
+      task,
+      model: selection?.model ?? model,
+      routeMatched,
+      attempt,
+      fallbackCount,
+      latencyMs,
+      errorCategory,
+      error
+    });
+  }
+  resolveCandidates(route, capability) {
+    const all = this.list();
+    if (!route) {
+      const active = this.getActive();
+      return active ? [active, ...all.filter((provider) => provider.id !== active.id)] : all;
+    }
+    const byId = new Map(all.map((provider) => [provider.id, provider]));
+    const selected = [];
+    for (const id of route.providerIds ?? []) {
+      const provider = byId.get(id);
+      if (provider) selected.push(provider);
+    }
+    const hasExplicitProviderIds = Boolean(route.providerIds?.length);
+    const remaining = hasExplicitProviderIds || route.fallback === false ? selected : all;
+    return remaining.filter((provider) => {
+      if (route.tiers?.length && !route.tiers.includes(provider.tier)) return false;
+      if (!providerSatisfiesRouteRequirements(provider, route.requirements, capability)) return false;
+      return true;
+    });
+  }
 };
+function withResolvedModel(request, model) {
+  return model === void 0 ? request : { ...request, model };
+}
+function inferInferenceTaskCapability(task) {
+  if (task.startsWith("embedding.")) return "embeddings";
+  if (task.startsWith("vision.")) return "vision";
+  return "chat";
+}
+function validateProviderRoute(task, capability, policy, providers) {
+  const byId = new Map(providers.map((provider) => [provider.id, provider]));
+  const providerIds = policy?.providerIds ?? [];
+  const issues = [];
+  const eligibleProviderIds = [];
+  if (policy && providerIds.length === 0 && policy.fallback === false) {
+    issues.push({
+      severity: "error",
+      code: "empty-explicit-chain",
+      message: `Route '${task}' disables fallback but does not name a provider.`
+    });
+  }
+  const candidates = providerIds.length ? providerIds.map((id) => byId.get(id)).filter((provider) => Boolean(provider)) : providers;
+  for (const providerId of providerIds) {
+    if (!byId.has(providerId)) {
+      issues.push({
+        severity: "error",
+        code: "missing-provider",
+        providerId,
+        message: `Route '${task}' references missing provider '${providerId}'.`
+      });
+    }
+  }
+  for (const provider of candidates) {
+    if (policy?.tiers?.length && !policy.tiers.includes(provider.tier)) continue;
+    if (!provider.capabilities[capability]) {
+      issues.push({
+        severity: "error",
+        code: "unsupported-capability",
+        providerId: provider.id,
+        message: `Provider '${provider.id}' does not support ${String(capability)} for route '${task}'.`
+      });
+      continue;
+    }
+    if (capability === "embeddings" && !provider.embed) {
+      issues.push({
+        severity: "error",
+        code: "missing-handler",
+        providerId: provider.id,
+        message: `Provider '${provider.id}' has no embedding handler for route '${task}'.`
+      });
+      continue;
+    }
+    if (capability === "chat" && !provider.complete) {
+      issues.push({
+        severity: "error",
+        code: "missing-handler",
+        providerId: provider.id,
+        message: `Provider '${provider.id}' has no chat handler for route '${task}'.`
+      });
+      continue;
+    }
+    if (capability === "streaming" && !provider.stream) {
+      issues.push({
+        severity: "error",
+        code: "missing-handler",
+        providerId: provider.id,
+        message: `Provider '${provider.id}' has no streaming handler for route '${task}'.`
+      });
+      continue;
+    }
+    const requirementIssue = getProviderRouteRequirementIssue(provider, policy?.requirements, capability);
+    if (requirementIssue) {
+      issues.push({
+        severity: "error",
+        code: "profile-requirement",
+        providerId: provider.id,
+        message: requirementIssue
+      });
+      continue;
+    }
+    eligibleProviderIds.push(provider.id);
+  }
+  if (!eligibleProviderIds.length) {
+    issues.push({
+      severity: "error",
+      code: "no-eligible-provider",
+      message: `Route '${task}' has no eligible ${String(capability)} provider.`
+    });
+  }
+  return {
+    task,
+    capability,
+    policy: policy ? cloneProviderRoutePolicy(policy) : void 0,
+    providerIds,
+    eligibleProviderIds,
+    issues,
+    ok: !issues.some((issue) => issue.severity === "error")
+  };
+}
+function cloneProviderRoutePolicy(policy) {
+  return {
+    ...policy,
+    providerIds: policy.providerIds ? [...policy.providerIds] : void 0,
+    tiers: policy.tiers ? [...policy.tiers] : void 0,
+    requirements: policy.requirements ? {
+      ...policy.requirements,
+      privacyTiers: policy.requirements.privacyTiers ? [...policy.requirements.privacyTiers] : void 0
+    } : void 0
+  };
+}
+var COST_ORDER = ["free", "low", "medium", "high"];
+function providerSatisfiesRouteRequirements(provider, requirements, capability) {
+  return getProviderRouteRequirementIssue(provider, requirements, capability) === void 0;
+}
+function getProviderRouteRequirementIssue(provider, requirements, capability) {
+  if (!requirements) return void 0;
+  const profile = provider.profile;
+  if (requirements.privacyTiers?.length) {
+    const privacy = profile?.privacyTier ?? privacyTierFromProviderTier(provider.tier);
+    if (!requirements.privacyTiers.includes(privacy)) {
+      return `Provider '${provider.id}' does not match required privacy tier`;
+    }
+  }
+  if (requirements.maxCostTier) {
+    const cost = profile?.costTier;
+    if (!cost || COST_ORDER.indexOf(cost) > COST_ORDER.indexOf(requirements.maxCostTier)) {
+      return `Provider '${provider.id}' does not match required cost tier`;
+    }
+  }
+  if (requirements.minContextTokens) {
+    const context = provider.capabilities.maxContextTokens;
+    if (!context || context < requirements.minContextTokens) {
+      return `Provider '${provider.id}' does not advertise enough context`;
+    }
+  }
+  if (capability === "embeddings" && requirements.minEmbeddingDimensions) {
+    const dimensions = profile?.embeddingDimensions ?? [];
+    if (!dimensions.some((dimension) => dimension >= requirements.minEmbeddingDimensions)) {
+      return `Provider '${provider.id}' does not advertise enough embedding dimensions`;
+    }
+  }
+  if (requirements.dataClass) {
+    const allowed = profile?.dataClasses ?? defaultDataClasses(provider.tier);
+    if (!allowed.includes(requirements.dataClass)) {
+      return `Provider '${provider.id}' does not allow required data class`;
+    }
+  }
+  if (requirements.maxInputChars) {
+    const maxInputChars = profile?.maxInputChars;
+    if (!maxInputChars || maxInputChars < requirements.maxInputChars) {
+      return `Provider '${provider.id}' does not advertise enough input capacity`;
+    }
+  }
+  return void 0;
+}
+function privacyTierFromProviderTier(tier) {
+  if (tier === "remote") return "external";
+  if (tier === "chrome-ai") return "host-managed";
+  return "local";
+}
+function defaultDataClasses(tier) {
+  if (tier === "remote") return ["public"];
+  return ["public", "private", "sensitive"];
+}
 function createLegacyProvider(options) {
   const { embedFn: embedFn2, llmFn: llmFn2, id = "legacy", name = "Legacy Provider" } = options;
   return {
     id,
     name,
     tier: "in-browser",
+    profile: options.profile ?? {
+      privacyTier: "local",
+      costTier: "free",
+      dataClasses: ["public", "private", "sensitive"]
+    },
     capabilities: {
       embeddings: !!embedFn2,
       chat: !!llmFn2,
@@ -7302,14 +9103,11 @@ function createLegacyProvider(options) {
       structuredOutput: false
     },
     embed: embedFn2 ? async (request) => ({
-      vectors: await embedFn2(request.texts),
+      vectors: await embedFn2(request.texts, embedOptionsFromRequest(request)),
       model: "legacy"
     }) : void 0,
     complete: llmFn2 ? async (request) => ({
-      text: await llmFn2(request.prompt, {
-        maxTokens: request.maxTokens,
-        temperature: request.temperature
-      }),
+      text: await llmFn2(request.prompt, llmOptionsFromRequest(request)),
       model: "legacy"
     }) : void 0,
     async listModels() {
@@ -7325,6 +9123,114 @@ function createLegacyProvider(options) {
     }
   };
 }
+function embedOptionsFromRequest(request) {
+  const options = {};
+  if (request.task) options.task = request.task;
+  if (request.model) options.model = request.model;
+  return Object.keys(options).length ? options : void 0;
+}
+function llmOptionsFromRequest(request) {
+  const options = {};
+  if (request.maxTokens !== void 0) options.maxTokens = request.maxTokens;
+  if (request.temperature !== void 0) options.temperature = request.temperature;
+  if (request.task) options.task = request.task;
+  if (request.model) options.model = request.model;
+  return Object.keys(options).length ? options : void 0;
+}
+
+// src/capabilities/local-discovery.ts
+var LOCAL_ENDPOINTS = [
+  { id: "ollama", name: "Ollama", baseURL: "http://localhost:11434/v1", defaultPort: 11434 },
+  { id: "lm-studio", name: "LM Studio", baseURL: "http://localhost:1234/v1", defaultPort: 1234 },
+  { id: "llama-cpp", name: "llama.cpp", baseURL: "http://localhost:8080/v1", defaultPort: 8080 },
+  { id: "vllm", name: "vLLM", baseURL: "http://localhost:8000/v1", defaultPort: 8e3 },
+  { id: "jan", name: "Jan", baseURL: "http://localhost:1337/v1", defaultPort: 1337 },
+  { id: "localai", name: "LocalAI", baseURL: "http://localhost:8080/v1", defaultPort: 8080 }
+];
+function classifyModel(modelId) {
+  const lower = modelId.toLowerCase();
+  if (lower.includes("embed") || lower.includes("e5-") || lower.includes("bge-") || lower.includes("nomic-") || lower.includes("mxbai-") || lower.includes("all-minilm") || lower.includes("gte-")) {
+    return "embedding";
+  }
+  if (lower.includes("vision") || lower.includes("llava") || lower.includes("moondream") || lower.includes("minicpm-v") || lower.includes("bakllava")) {
+    return "vision";
+  }
+  return "chat";
+}
+function inferLocalEmbeddingDimensions(models) {
+  const embeddingModel = models.find((model) => model.capabilities.embeddings)?.id.toLowerCase();
+  if (!embeddingModel) return void 0;
+  if (embeddingModel.includes("nomic-embed")) return [768];
+  if (embeddingModel.includes("bge-large")) return [1024];
+  if (embeddingModel.includes("bge-base")) return [768];
+  if (embeddingModel.includes("bge-small")) return [384];
+  if (embeddingModel.includes("all-minilm")) return [384];
+  if (embeddingModel.includes("mxbai-embed-large")) return [1024];
+  return void 0;
+}
+function createLocalProviderProfile(models = []) {
+  const embeddingDimensions = inferLocalEmbeddingDimensions(models);
+  return {
+    privacyTier: "local",
+    costTier: "free",
+    embeddingDimensions,
+    dataClasses: ["public", "private", "sensitive"]
+  };
+}
+async function probeEndpoint(endpoint, timeoutMs) {
+  try {
+    const response = await globalThis.fetch(`${endpoint.baseURL}/models`, {
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    let modelIds;
+    if (data.data && Array.isArray(data.data)) {
+      modelIds = data.data.map((m) => m.id);
+    } else if (data.models && Array.isArray(data.models)) {
+      modelIds = data.models.map((m) => m.name ?? m.model ?? "");
+    } else {
+      modelIds = [];
+    }
+    const models = modelIds.filter(Boolean).map((id) => {
+      const category = classifyModel(id);
+      return {
+        id,
+        name: id,
+        capabilities: {
+          embeddings: category === "embedding",
+          chat: category === "chat" || category === "vision",
+          vision: category === "vision"
+        }
+      };
+    });
+    return {
+      id: endpoint.id,
+      name: endpoint.name,
+      baseURL: endpoint.baseURL,
+      models
+    };
+  } catch {
+    return null;
+  }
+}
+async function discoverLocalProviders(options = {}) {
+  const { extraEndpoints = [], timeoutMs = 2e3, skipPorts = [] } = options;
+  const allEndpoints = [...LOCAL_ENDPOINTS, ...extraEndpoints];
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueEndpoints = allEndpoints.filter((ep) => {
+    if (seen.has(ep.baseURL)) return false;
+    if (skipPorts.includes(ep.defaultPort)) return false;
+    seen.add(ep.baseURL);
+    return true;
+  });
+  const results = await Promise.allSettled(
+    uniqueEndpoints.map((ep) => probeEndpoint(ep, timeoutMs))
+  );
+  return results.filter(
+    (r) => r.status === "fulfilled" && r.value !== null
+  ).map((r) => r.value);
+}
 
 // src/capabilities/openai-provider.ts
 var OpenAICompatibleProvider = class {
@@ -7332,6 +9238,7 @@ var OpenAICompatibleProvider = class {
   name;
   tier;
   capabilities;
+  profile;
   baseURL;
   apiKey;
   defaultModel;
@@ -7357,6 +9264,7 @@ var OpenAICompatibleProvider = class {
       toolCalling: false,
       structuredOutput: false
     };
+    this.profile = config.profile ?? (this.tier === "local-server" ? { privacyTier: "local", costTier: "free" } : { privacyTier: "external" });
   }
   // -------------------------------------------------------------------------
   // InferenceProvider interface
@@ -7451,15 +9359,19 @@ var OpenAICompatibleProvider = class {
     try {
       const response = await this.fetch("/models", void 0, "GET");
       const data = response;
-      return data.data.map((m) => ({
-        id: m.id,
-        name: m.id,
-        capabilities: {
-          chat: !this.isEmbeddingModel(m.id),
-          embeddings: this.isEmbeddingModel(m.id)
-        },
-        owned_by: m.owned_by
-      }));
+      return data.data.map((m) => {
+        const category = classifyModel(m.id);
+        return {
+          id: m.id,
+          name: m.id,
+          capabilities: {
+            chat: category === "chat" || category === "vision",
+            embeddings: category === "embedding",
+            vision: category === "vision"
+          },
+          owned_by: m.owned_by
+        };
+      });
     } catch {
       return [];
     }
@@ -7507,10 +9419,6 @@ var OpenAICompatibleProvider = class {
         return void 0;
     }
   }
-  isEmbeddingModel(id) {
-    const lower = id.toLowerCase();
-    return lower.includes("embed") || lower.includes("e5-") || lower.includes("bge-") || lower.includes("nomic-") || lower.includes("mxbai-") || lower.includes("all-minilm");
-  }
   isLocalURL() {
     try {
       const url = new URL(this.baseURL);
@@ -7551,299 +9459,77 @@ var OpenAICompatibleProvider = class {
   }
 };
 
-// src/capabilities/local-discovery.ts
-var LOCAL_ENDPOINTS = [
-  { id: "ollama", name: "Ollama", baseURL: "http://localhost:11434/v1", defaultPort: 11434 },
-  { id: "lm-studio", name: "LM Studio", baseURL: "http://localhost:1234/v1", defaultPort: 1234 },
-  { id: "llama-cpp", name: "llama.cpp", baseURL: "http://localhost:8080/v1", defaultPort: 8080 },
-  { id: "vllm", name: "vLLM", baseURL: "http://localhost:8000/v1", defaultPort: 8e3 },
-  { id: "jan", name: "Jan", baseURL: "http://localhost:1337/v1", defaultPort: 1337 },
-  { id: "localai", name: "LocalAI", baseURL: "http://localhost:8080/v1", defaultPort: 8080 }
-];
-function classifyModel(modelId) {
-  const lower = modelId.toLowerCase();
-  if (lower.includes("embed") || lower.includes("e5-") || lower.includes("bge-") || lower.includes("nomic-") || lower.includes("mxbai-") || lower.includes("all-minilm") || lower.includes("gte-")) {
-    return "embedding";
-  }
-  if (lower.includes("vision") || lower.includes("llava") || lower.includes("moondream") || lower.includes("minicpm-v") || lower.includes("bakllava")) {
-    return "vision";
-  }
-  return "chat";
-}
-async function probeEndpoint(endpoint, timeoutMs) {
-  try {
-    const response = await globalThis.fetch(`${endpoint.baseURL}/models`, {
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!response.ok) return null;
-    const data = await response.json();
-    let modelIds;
-    if (data.data && Array.isArray(data.data)) {
-      modelIds = data.data.map((m) => m.id);
-    } else if (data.models && Array.isArray(data.models)) {
-      modelIds = data.models.map((m) => m.name ?? m.model ?? "");
-    } else {
-      modelIds = [];
-    }
-    const models = modelIds.filter(Boolean).map((id) => {
-      const category = classifyModel(id);
-      return {
-        id,
-        name: id,
-        capabilities: {
-          embeddings: category === "embedding",
-          chat: category === "chat" || category === "vision",
-          vision: category === "vision"
-        }
-      };
-    });
-    return {
-      id: endpoint.id,
-      name: endpoint.name,
-      baseURL: endpoint.baseURL,
-      models
-    };
-  } catch {
-    return null;
-  }
-}
-async function discoverLocalProviders(options = {}) {
-  const { extraEndpoints = [], timeoutMs = 2e3, skipPorts = [] } = options;
-  const allEndpoints = [...LOCAL_ENDPOINTS, ...extraEndpoints];
-  const seen = /* @__PURE__ */ new Set();
-  const uniqueEndpoints = allEndpoints.filter((ep) => {
-    if (seen.has(ep.baseURL)) return false;
-    if (skipPorts.includes(ep.defaultPort)) return false;
-    seen.add(ep.baseURL);
-    return true;
-  });
-  const results = await Promise.allSettled(
-    uniqueEndpoints.map((ep) => probeEndpoint(ep, timeoutMs))
-  );
-  return results.filter(
-    (r) => r.status === "fulfilled" && r.value !== null
-  ).map((r) => r.value);
-}
-
-// src/capabilities/fallback-router.ts
-var DEFAULT_COOLDOWNS = {
-  rateLimit: 3e4,
-  serverError: 6e4,
-  connectionFailure: 3e5,
-  contentPolicy: 0
-};
-function classifyError(error) {
-  const msg = error instanceof Error ? error.message : String(error);
-  const lower = msg.toLowerCase();
-  if (lower.includes("429") || lower.includes("rate limit")) return "rate_limit";
-  if (lower.includes("500") || lower.includes("502") || lower.includes("503") || lower.includes("504")) return "server_error";
-  if (lower.includes("content") && (lower.includes("policy") || lower.includes("filter"))) return "content_policy";
-  if (lower.includes("context") && (lower.includes("window") || lower.includes("length") || lower.includes("too long"))) return "context_window";
-  if (lower.includes("fetch") || lower.includes("network") || lower.includes("connection") || lower.includes("econnrefused") || lower.includes("timeout")) return "connection_failure";
-  return "unknown";
+// src/capabilities/bridge-provider.ts
+function capabilitiesFromBridge(info) {
+  return {
+    embeddings: Boolean(info.capabilities.embeddings),
+    chat: Boolean(info.capabilities.chat),
+    streaming: Boolean(info.capabilities.streaming),
+    vision: false,
+    toolCalling: false,
+    structuredOutput: false
+  };
 }
-var FallbackRouter = class {
-  id = "fallback-router";
-  name = "Fallback Router";
-  tier = "remote";
-  providers;
-  cooldowns;
-  cooldownMap = /* @__PURE__ */ new Map();
-  events;
-  get capabilities() {
-    const available = this.getAvailableProviders();
-    return {
-      embeddings: available.some((p) => p.capabilities.embeddings),
-      chat: available.some((p) => p.capabilities.chat),
-      streaming: available.some((p) => p.capabilities.streaming),
-      vision: available.some((p) => p.capabilities.vision),
-      toolCalling: available.some((p) => p.capabilities.toolCalling),
-      structuredOutput: available.some((p) => p.capabilities.structuredOutput),
-      maxContextTokens: Math.max(
-        ...available.map((p) => p.capabilities.maxContextTokens ?? 0),
-        0
-      )
+var BridgeInferenceProvider = class {
+  constructor(bridge, info) {
+    this.bridge = bridge;
+    this.id = info.id;
+    this.name = info.name;
+    this.tier = info.tier;
+    this.capabilities = capabilitiesFromBridge(info);
+    this.profile = info.profile ?? {
+      privacyTier: "host-managed"
     };
   }
-  constructor(config) {
-    this.providers = [...config.providers];
-    this.cooldowns = { ...DEFAULT_COOLDOWNS, ...config.cooldowns };
-    this.events = config.events;
-  }
-  // -------------------------------------------------------------------------
-  // Provider management
-  // -------------------------------------------------------------------------
-  /** Get providers not currently in cooldown */
-  getAvailableProviders() {
-    const now2 = Date.now();
-    return this.providers.filter((p) => {
-      const cd = this.cooldownMap.get(p.id);
-      if (!cd) return true;
-      if (now2 >= cd.expiresAt) {
-        this.cooldownMap.delete(p.id);
-        return true;
-      }
-      return false;
-    });
-  }
-  /** Get providers in cooldown with their expiry info */
-  getCoolingDown() {
-    const now2 = Date.now();
-    const result = [];
-    for (const [id, entry] of this.cooldownMap) {
-      if (now2 < entry.expiresAt) {
-        result.push({ providerId: id, category: entry.category, expiresAt: entry.expiresAt });
-      }
-    }
-    return result;
-  }
-  /** Manually clear cooldown for a provider */
-  clearCooldown(providerId) {
-    this.cooldownMap.delete(providerId);
-  }
-  /** Clear all cooldowns */
-  clearAllCooldowns() {
-    this.cooldownMap.clear();
-  }
-  /** Add a provider to the chain (appended at lowest priority) */
-  addProvider(provider) {
-    this.providers.push(provider);
-  }
-  /** Remove a provider from the chain */
-  removeProvider(id) {
-    this.providers = this.providers.filter((p) => p.id !== id);
-    this.cooldownMap.delete(id);
-  }
-  /** Reorder providers (new priority order) */
-  setOrder(ids) {
-    const byId = new Map(this.providers.map((p) => [p.id, p]));
-    const reordered = [];
-    for (const id of ids) {
-      const p = byId.get(id);
-      if (p) reordered.push(p);
+  id;
+  name;
+  tier;
+  capabilities;
+  profile;
+  async embed(request) {
+    if (!this.capabilities.embeddings) {
+      throw new Error(`Bridge provider '${this.id}' does not support embeddings`);
     }
-    for (const p of this.providers) {
-      if (!ids.includes(p.id)) reordered.push(p);
+    if (!this.bridge.inference) {
+      throw new Error("Fortemi bridge inference router is unavailable");
     }
-    this.providers = reordered;
-  }
-  // -------------------------------------------------------------------------
-  // InferenceProvider interface — with fallback
-  // -------------------------------------------------------------------------
-  async embed(request) {
-    return this.withFallback(
-      (p) => p.capabilities.embeddings && !!p.embed,
-      (p) => p.embed(request)
-    );
+    return this.bridge.inference.embed(this.id, request);
   }
   async complete(request) {
-    return this.withFallback(
-      (p) => p.capabilities.chat && !!p.complete,
-      (p) => p.complete(request)
-    );
+    if (!this.capabilities.chat) {
+      throw new Error(`Bridge provider '${this.id}' does not support chat`);
+    }
+    if (!this.bridge.inference) {
+      throw new Error("Fortemi bridge inference router is unavailable");
+    }
+    return this.bridge.inference.complete(this.id, request);
   }
-  async *stream(request) {
-    const candidates = this.getAvailableProviders().filter((p) => p.capabilities.streaming && p.stream);
-    if (candidates.length === 0) {
-      throw new Error("No available providers with streaming capability");
+  stream(request) {
+    if (!this.capabilities.streaming) {
+      throw new Error(`Bridge provider '${this.id}' does not support streaming`);
     }
-    yield* candidates[0].stream(request);
+    if (!this.bridge.inference?.stream) {
+      throw new Error("Fortemi bridge streaming router is unavailable");
+    }
+    return this.bridge.inference.stream(this.id, request);
   }
   async listModels() {
-    const available = this.getAvailableProviders();
-    const results = await Promise.allSettled(
-      available.map((p) => p.listModels())
-    );
-    const models = [];
-    for (const r of results) {
-      if (r.status === "fulfilled") models.push(...r.value);
-    }
-    return models;
+    return [];
   }
   async probe() {
-    const available = this.getAvailableProviders();
-    if (available.length === 0) {
-      return { status: "down", latencyMs: 0, message: "All providers in cooldown" };
+    if (!this.bridge.inference) {
+      return { status: "down", latencyMs: 0, message: "Fortemi bridge inference router is unavailable" };
     }
-    const start = Date.now();
-    const results = await Promise.allSettled(
-      available.map((p) => p.probe())
-    );
-    const okCount = results.filter(
-      (r) => r.status === "fulfilled" && r.value.status === "ok"
-    ).length;
-    return {
-      status: okCount === available.length ? "ok" : okCount > 0 ? "degraded" : "down",
-      latencyMs: Date.now() - start,
-      message: `${okCount}/${available.length} providers healthy`
-    };
+    return this.bridge.inference.probeProvider(this.id);
   }
   dispose() {
-    for (const p of this.providers) {
-      p.dispose();
-    }
-    this.providers = [];
-    this.cooldownMap.clear();
-  }
-  // -------------------------------------------------------------------------
-  // Core fallback logic
-  // -------------------------------------------------------------------------
-  async withFallback(filter, execute) {
-    const candidates = this.getAvailableProviders().filter(filter);
-    if (candidates.length === 0) {
-      throw new Error("No available providers for this request");
-    }
-    let lastError;
-    for (const provider of candidates) {
-      try {
-        return await execute(provider);
-      } catch (err) {
-        lastError = err instanceof Error ? err : new Error(String(err));
-        const category = classifyError(err);
-        this.applyCooldown(provider.id, category);
-        const nextCandidate = candidates[candidates.indexOf(provider) + 1];
-        if (nextCandidate) {
-          this.events?.emit("provider.fallback", {
-            fromProvider: provider.id,
-            toProvider: nextCandidate.id,
-            errorCategory: category,
-            error: lastError.message
-          });
-        }
-      }
-    }
-    throw lastError ?? new Error("All providers failed");
-  }
-  applyCooldown(providerId, category) {
-    let cooldownMs;
-    switch (category) {
-      case "rate_limit":
-        cooldownMs = this.cooldowns.rateLimit;
-        break;
-      case "server_error":
-        cooldownMs = this.cooldowns.serverError;
-        break;
-      case "connection_failure":
-        cooldownMs = this.cooldowns.connectionFailure;
-        break;
-      case "content_policy":
-        cooldownMs = this.cooldowns.contentPolicy;
-        break;
-      default:
-        cooldownMs = this.cooldowns.serverError;
-    }
-    if (cooldownMs > 0) {
-      const expiresAt = Date.now() + cooldownMs;
-      this.cooldownMap.set(providerId, { expiresAt, category });
-      this.events?.emit("provider.cooldown", {
-        providerId,
-        errorCategory: category,
-        cooldownMs,
-        expiresAt
-      });
-    }
   }
 };
+async function createBridgeInferenceProviders(bridge) {
+  if (!bridge.inference) return [];
+  const providers = await bridge.inference.listProviders();
+  return providers.map((info) => new BridgeInferenceProvider(bridge, info));
+}
 
 // src/fortemi-bridge.ts
 function getFortemiBridge(host = globalThis) {
@@ -7872,6 +9558,159 @@ async function hasFortemiSecureSecrets(host = globalThis) {
   }
 }
 
+// src/capabilities/inference-runtime.ts
+function defineInferenceRuntime(config) {
+  return config;
+}
+function defineInferenceProvider(provider) {
+  return { kind: "provider", provider };
+}
+function defineOpenAICompatibleProvider(config) {
+  return { kind: "openai-compatible", config };
+}
+function defineLegacyInferenceProvider(config) {
+  return { kind: "legacy", ...config };
+}
+function mergeInferenceRuntimeConfigs(...configs) {
+  const merged = {};
+  for (const config of configs) {
+    if (!config) continue;
+    if (config.providers?.length) {
+      merged.providers = mergeConfiguredProviders(merged.providers, config.providers);
+    }
+    if (config.routes) {
+      merged.routes = { ...merged.routes ?? {}, ...config.routes };
+    }
+    if (config.activeProviderId !== void 0) {
+      merged.activeProviderId = config.activeProviderId;
+    }
+    if (config.bridgeHost !== void 0) {
+      merged.bridgeHost = config.bridgeHost;
+    }
+    if (config.includeBridgeProviders !== void 0) {
+      merged.includeBridgeProviders = config.includeBridgeProviders;
+    }
+    if (config.discoverLocal !== void 0) {
+      merged.discoverLocal = config.discoverLocal;
+    }
+    if (config.embeddingTaskSelection) {
+      merged.embeddingTaskSelection = {
+        ...merged.embeddingTaskSelection ?? {},
+        ...config.embeddingTaskSelection
+      };
+    }
+  }
+  return merged;
+}
+function getConfiguredInferenceProviderId(config) {
+  switch (config.kind) {
+    case "provider":
+      return config.provider.id;
+    case "openai-compatible":
+      return config.config.id;
+    case "legacy":
+      return config.id ?? "legacy";
+  }
+}
+function mergeConfiguredProviders(previous, next) {
+  const byId = /* @__PURE__ */ new Map();
+  for (const provider of previous ?? []) {
+    byId.set(getConfiguredInferenceProviderId(provider), provider);
+  }
+  for (const provider of next) {
+    const id = getConfiguredInferenceProviderId(provider);
+    byId.delete(id);
+    byId.set(id, provider);
+  }
+  return Array.from(byId.values());
+}
+async function configureInferenceRuntime(options = {}) {
+  const registry = options.registry ?? new ProviderRegistry(options.events);
+  setEmbeddingTaskSelectionOptions(options.embeddingTaskSelection);
+  for (const providerConfig of options.providers ?? []) {
+    registry.add(createConfiguredProvider(providerConfig));
+  }
+  if (options.includeBridgeProviders !== false) {
+    const bridge = getFortemiBridge(options.bridgeHost);
+    if (bridge) {
+      for (const provider of await createBridgeInferenceProviders(bridge)) {
+        if (!registry.get(provider.id)) registry.add(provider);
+      }
+    }
+  }
+  if (options.discoverLocal) {
+    const discoveryOptions = options.discoverLocal === true ? {} : options.discoverLocal;
+    const discovered = await discoverLocalProviders(discoveryOptions);
+    for (const provider of discovered) {
+      const id = `local:${provider.id}`;
+      if (registry.get(id)) continue;
+      registry.add(new OpenAICompatibleProvider({
+        id,
+        name: provider.name,
+        baseURL: provider.baseURL,
+        tier: "local-server",
+        defaultModel: provider.models.find((model) => model.capabilities.chat)?.id,
+        defaultEmbeddingModel: provider.models.find((model) => model.capabilities.embeddings)?.id,
+        profile: createLocalProviderProfile(provider.models)
+      }));
+    }
+  }
+  for (const [task, route] of Object.entries(options.routes ?? {})) {
+    if (route) registry.setRoute(task, route);
+  }
+  if (options.activeProviderId) {
+    registry.setActive(options.activeProviderId);
+  }
+  if (options.capabilityManager) {
+    wireCapabilities(options.capabilityManager, registry);
+  }
+  const routeValidation = registry.validateRoutes();
+  return {
+    registry,
+    providers: registry.list(),
+    routeValidation,
+    routeIssues: routeValidation.flatMap((route) => route.issues)
+  };
+}
+function createConfiguredProvider(config) {
+  switch (config.kind) {
+    case "provider":
+      return config.provider;
+    case "openai-compatible":
+      return new OpenAICompatibleProvider(config.config);
+    case "legacy":
+      return createLegacyProvider(config);
+  }
+}
+function wireCapabilities(manager, registry) {
+  if (registry.hasEmbeddings()) {
+    manager.registerLoader("semantic", async () => {
+      setEmbedFunction((texts, options) => {
+        const request = {
+          texts,
+          task: options?.task ?? "embedding.document"
+        };
+        if (options?.model) Object.assign(request, { model: options.model });
+        return registry.embed(request).then((result) => result.vectors);
+      });
+    });
+  }
+  if (registry.hasChat()) {
+    manager.registerLoader("llm", async () => {
+      setLlmFunction((prompt, options) => {
+        const request = {
+          prompt,
+          task: options?.task ?? "chat.general"
+        };
+        if (options?.model) Object.assign(request, { model: options.model });
+        if (options?.maxTokens !== void 0) Object.assign(request, { maxTokens: options.maxTokens });
+        if (options?.temperature !== void 0) Object.assign(request, { temperature: options.temperature });
+        return registry.complete(request).then((result) => result.text);
+      });
+    });
+  }
+}
+
 // src/security/plugin-content.ts
 var DEFAULT_DIRECTIVES = {
   "default-src": ["'self'"],
@@ -7913,12 +9752,12 @@ function parseSriToken(integrity) {
   const separator = token.indexOf("-");
   if (separator <= 0) throw new Error("Invalid SRI token");
   const algorithm = token.slice(0, separator).toLowerCase();
-  const digest = token.slice(separator + 1);
+  const digest2 = token.slice(separator + 1);
   if (!SUPPORTED_SRI_ALGORITHMS.has(algorithm)) {
     throw new Error("Unsupported SRI algorithm: " + algorithm);
   }
-  if (!digest) throw new Error("Invalid SRI digest");
-  return { algorithm, digest };
+  if (!digest2) throw new Error("Invalid SRI digest");
+  return { algorithm, digest: digest2 };
 }
 function toBase64(bytes) {
   const data = new Uint8Array(bytes);
@@ -7935,8 +9774,8 @@ async function computeSri(data, algorithm = "sha384") {
   if (!SUPPORTED_SRI_ALGORITHMS.has(normalized)) {
     throw new Error("Unsupported SRI algorithm: " + algorithm);
   }
-  const digest = await crypto.subtle.digest(normalized.toUpperCase().replace("SHA", "SHA-"), toArrayBuffer(data));
-  return normalized + "-" + toBase64(digest);
+  const digest2 = await crypto.subtle.digest(normalized.toUpperCase().replace("SHA", "SHA-"), toArrayBuffer(data));
+  return normalized + "-" + toBase64(digest2);
 }
 async function verifySri(data, integrity) {
   const expected = parseSriToken(integrity);
@@ -8968,12 +10807,12 @@ async function verifyShardSignature(input) {
       false,
       ["verify"]
     );
-    const digest = await sha256Hex(canonicalPayloadBytes(payload));
+    const digest2 = await sha256Hex(canonicalPayloadBytes(payload));
     signatureValid = await globalThis.crypto.subtle.verify(
       "Ed25519",
       key,
       toBufferSource(base64urlToBytes(envelope.signature)),
-      toBufferSource(new TextEncoder().encode(digest))
+      toBufferSource(new TextEncoder().encode(digest2))
     );
   } catch (err) {
     return { ok: false, reason: "malformed", detail: err instanceof Error ? err.message : String(err) };
@@ -9018,11 +10857,11 @@ async function signShard(input) {
     manifest_digest: await sha256Hex(manifest),
     blob_digests: sidecarBlobDigests(input.files)
   };
-  const digest = await sha256Hex(canonicalPayloadBytes(payload));
+  const digest2 = await sha256Hex(canonicalPayloadBytes(payload));
   const signature = await globalThis.crypto.subtle.sign(
     "Ed25519",
     input.privateKey,
-    toBufferSource(new TextEncoder().encode(digest))
+    toBufferSource(new TextEncoder().encode(digest2))
   );
   const envelope = {
     ...payload,
@@ -27567,7 +29406,7 @@ function addCanonicalFormats(ajv) {
 }
 function getLegacyAjv() {
   if (!legacyAjvInstance) {
-    legacyAjvInstance = new Ajv2020({
+    legacyAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: false
@@ -27578,7 +29417,7 @@ function getLegacyAjv() {
 }
 function getCoreAjv() {
   if (!coreAjvInstance) {
-    coreAjvInstance = new Ajv2020({
+    coreAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: true
@@ -27598,7 +29437,7 @@ function getCoreAjv() {
 }
 function getRecordAjv() {
   if (!recordAjvInstance) {
-    recordAjvInstance = new Ajv2020({
+    recordAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: true
@@ -27618,7 +29457,7 @@ function getRecordAjv() {
 }
 function getFullAjv() {
   if (!fullAjvInstance) {
-    fullAjvInstance = new Ajv2020({
+    fullAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: true
@@ -27691,7 +29530,7 @@ function profileOf(value) {
   return typeof profile === "string" ? profile : void 0;
 }
 function validateShardManifest(value) {
-  let validate;
+  let validate2;
   const profile = profileOf(value);
   if (profile === "core-v1") {
     const version = value && typeof value === "object" && !Array.isArray(value) ? coreSchemaVersion(String(value.version ?? "")) : void 0;
@@ -27701,7 +29540,7 @@ function validateShardManifest(value) {
         errors: ["(root) uses an unsupported canonical core-v1 schema version"]
       };
     }
-    validate = coreValidatorFor("manifest", version);
+    validate2 = coreValidatorFor("manifest", version);
   } else if (profile === "record-v1") {
     const version = value && typeof value === "object" && !Array.isArray(value) ? recordSchemaVersion(String(value.version ?? "")) : void 0;
     if (!version) {
@@ -27710,7 +29549,7 @@ function validateShardManifest(value) {
         errors: ["(root) uses an unsupported canonical record-v1 schema version"]
       };
     }
-    validate = recordValidatorFor("manifest", version);
+    validate2 = recordValidatorFor("manifest", version);
   } else if (profile === "full-v1") {
     const version = value && typeof value === "object" && !Array.isArray(value) ? fullSchemaVersion(String(value.version ?? "")) : void 0;
     if (!version) {
@@ -27719,12 +29558,12 @@ function validateShardManifest(value) {
         errors: ["(root) uses an unsupported canonical full-v1 schema version"]
       };
     }
-    validate = fullValidatorFor("manifest", version);
+    validate2 = fullValidatorFor("manifest", version);
   } else {
-    validate = legacyValidatorFor("manifest");
+    validate2 = legacyValidatorFor("manifest");
   }
-  const valid = validate(value);
-  return { valid, errors: formatErrors(validate.errors) };
+  const valid = validate2(value);
+  return { valid, errors: formatErrors(validate2.errors) };
 }
 function parseJsonArray(bytes, path) {
   if (!bytes) return { records: [], errors: [] };
@@ -28167,9 +30006,9 @@ async function validateFullV1ShardArchive(input) {
   return { valid: errors.length === 0, errors };
 }
 function validateShardComponentRecord(component, value, profile, version = CURRENT_SHARD_VERSION) {
-  let validate;
+  let validate2;
   if (profile === "core-v1" && component in CORE_V1_COMPONENT_FILES) {
-    validate = coreValidatorFor(component, version);
+    validate2 = coreValidatorFor(component, version);
   } else if (profile === "record-v1" && component in RECORD_V1_COMPONENT_FILES) {
     const canonicalVersion = recordSchemaVersion(version);
     if (!canonicalVersion) {
@@ -28178,7 +30017,7 @@ function validateShardComponentRecord(component, value, profile, version = CURRE
         errors: [`(root) uses an unsupported canonical record-v1 schema version ${version}`]
       };
     }
-    validate = recordValidatorFor(component, canonicalVersion);
+    validate2 = recordValidatorFor(component, canonicalVersion);
   } else if (profile === "full-v1" && component in FULL_V1_COMPONENT_FILES) {
     const canonicalVersion = fullSchemaVersion(version);
     if (!canonicalVersion) {
@@ -28187,7 +30026,7 @@ function validateShardComponentRecord(component, value, profile, version = CURRE
         errors: [`(root) uses an unsupported canonical full-v1 schema version ${version}`]
       };
     }
-    validate = fullValidatorFor(component, canonicalVersion);
+    validate2 = fullValidatorFor(component, canonicalVersion);
   } else {
     const legacyDef = LEGACY_COMPONENT_SCHEMA_DEFS[component];
     if (!legacyDef) {
@@ -28196,10 +30035,10 @@ function validateShardComponentRecord(component, value, profile, version = CURRE
         errors: [`(root) component '${component}' requires an explicit full-v1 profile`]
       };
     }
-    validate = legacyValidatorFor(legacyDef);
+    validate2 = legacyValidatorFor(legacyDef);
   }
-  const valid = validate(value);
-  return { valid, errors: formatErrors(validate.errors) };
+  const valid = validate2(value);
+  return { valid, errors: formatErrors(validate2.errors) };
 }
 function assertShardComponentRecord(component, value, profile, version = CURRENT_SHARD_VERSION) {
   const result = validateShardComponentRecord(component, value, profile, version);
@@ -28278,7 +30117,7 @@ async function promoteBlobs(blobStore, blobs) {
 
 // src/shard/full-v1-store.ts
 var decoder3 = new TextDecoder();
-var encoder = new TextEncoder();
+var encoder2 = new TextEncoder();
 function emptyCounts() {
   return {
     notes: 0,
@@ -28329,15 +30168,15 @@ function componentRecords(component, bytes) {
   const parsed = spec.encoding === "json-array" ? parseJsonArrayBytes(bytes) : parseJsonlBytes(bytes);
   return parsed;
 }
-function canonicalJson(value) {
-  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+function canonicalJson4(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson4).join(",")}]`;
   if (value && typeof value === "object") {
-    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+    return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson4(item)}`).join(",")}}`;
   }
   return JSON.stringify(value);
 }
 function encodeComponentRecords(component, records) {
-  return encoder.encode(FULL_V1_COMPONENT_FILES[component].encoding === "json-array" ? JSON.stringify(records) : records.map((record) => JSON.stringify(record)).join("\n"));
+  return encoder2.encode(FULL_V1_COMPONENT_FILES[component].encoding === "json-array" ? JSON.stringify(records) : records.map((record) => JSON.stringify(record)).join("\n"));
 }
 function attachmentBlobReferences(files) {
   const refs = /* @__PURE__ */ new Map();
@@ -28588,7 +30427,7 @@ async function exportFullV1Snapshot(db, blobStore) {
   for (const row of persisted.rows) currentRecords.get(row.component)?.push(row.record_json);
   const changed = [...currentRecords].some(([component, records]) => {
     const original = componentRecords(component, files.get(FULL_V1_COMPONENT_FILES[component].file));
-    return canonicalJson(records) !== canonicalJson(original);
+    return canonicalJson4(records) !== canonicalJson4(original);
   });
   let blobRefs;
   if (changed) {
@@ -28607,7 +30446,7 @@ async function exportFullV1Snapshot(db, blobStore) {
       name: "fortemi-react-full-v1-store",
       version: manifest.producer?.version ?? "unknown"
     };
-    files.set("manifest.json", encoder.encode(JSON.stringify(manifest, null, 2)));
+    files.set("manifest.json", encoder2.encode(JSON.stringify(manifest, null, 2)));
     files.delete("signature.json");
     blobRefs = attachmentBlobReferences(files);
   } else {
@@ -28631,7 +30470,7 @@ async function exportFullV1Snapshot(db, blobStore) {
   }
   return { success: true, archive: packTarGz(files), errors: [], capability_report: capability };
 }
-var encoder2 = new TextEncoder();
+var encoder3 = new TextEncoder();
 var decoder4 = new TextDecoder();
 function iso2(value) {
   if (value === null) return null;
@@ -28660,7 +30499,7 @@ function readRecords(files, component) {
 function writeRecords(files, component, records) {
   const spec = FULL_V1_COMPONENT_FILES[component];
   const text = spec.encoding === "json-array" ? JSON.stringify(records) : records.map((record) => JSON.stringify(record)).join("\n");
-  files.set(spec.file, encoder2.encode(text));
+  files.set(spec.file, encoder3.encode(text));
 }
 async function liveRepresentationLosses(db) {
   const tables = [
@@ -29127,7 +30966,7 @@ async function exportLiveFullV1(db, coreArchive, legacyArchive, options) {
       capability_report: capability
     };
   }
-  files.set("manifest.json", encoder2.encode(JSON.stringify(manifest, null, 2)));
+  files.set("manifest.json", encoder3.encode(JSON.stringify(manifest, null, 2)));
   for (const note of records.notes) {
     const attachments = Array.isArray(note.attachments) ? note.attachments : [];
     for (const projection of attachments) {
@@ -29172,7 +31011,7 @@ async function exportLiveFullV1(db, coreArchive, legacyArchive, options) {
 }
 
 // src/shard/shard-export.ts
-var encoder3 = new TextEncoder();
+var encoder4 = new TextEncoder();
 var CORE_V1_FILES = /* @__PURE__ */ new Set([
   "notes.jsonl",
   "collections.json",
@@ -29591,11 +31430,11 @@ async function exportShardBytes(db, options, mode) {
       const slice = shardNotes.slice(offset, offset + clusterSize);
       const href = `notes/${String(offset).padStart(6, "0")}.jsonl`;
       clusters.push({ href, offset });
-      files.set(href, encoder3.encode(slice.map((n) => JSON.stringify(n)).join("\n")));
+      files.set(href, encoder4.encode(slice.map((n) => JSON.stringify(n)).join("\n")));
     }
     layout = { clusters: { notes: clusters } };
   } else {
-    files.set("notes.jsonl", encoder3.encode(shardNotes.map((n) => JSON.stringify(n)).join("\n")));
+    files.set("notes.jsonl", encoder4.encode(shardNotes.map((n) => JSON.stringify(n)).join("\n")));
   }
   components.push("notes");
   counts.notes = notes.length;
@@ -29623,7 +31462,7 @@ async function exportShardBytes(db, options, mode) {
       mode?.nativeSchema2Presence
     );
   }
-  files.set("collections.json", encoder3.encode(JSON.stringify(shardCollections)));
+  files.set("collections.json", encoder4.encode(JSON.stringify(shardCollections)));
   components.push("collections");
   counts.collections = shardCollections.length;
   const allTagRows = await db.query(
@@ -29639,7 +31478,7 @@ async function exportShardBytes(db, options, mode) {
   const shardTags = tagsToShard(
     relevantTags.map((r) => ({ name: r.tag, created_at: r.created_at }))
   );
-  files.set("tags.json", encoder3.encode(JSON.stringify(shardTags)));
+  files.set("tags.json", encoder4.encode(JSON.stringify(shardTags)));
   components.push("tags");
   counts.tags = shardTags.length;
   const templateRows = await db.query(`SELECT * FROM template ORDER BY created_at, id`);
@@ -29655,7 +31494,7 @@ async function exportShardBytes(db, options, mode) {
         mode?.nativeSchema2Presence
       );
     }
-    files.set("templates.json", encoder3.encode(JSON.stringify(shardTemplates)));
+    files.set("templates.json", encoder4.encode(JSON.stringify(shardTemplates)));
     components.push("templates");
     counts.templates = shardTemplates.length;
   }
@@ -29680,7 +31519,7 @@ async function exportShardBytes(db, options, mode) {
     );
   }
   const linksJsonl = shardLinks.map((l) => JSON.stringify(l)).join("\n");
-  files.set("links.jsonl", encoder3.encode(linksJsonl));
+  files.set("links.jsonl", encoder4.encode(linksJsonl));
   components.push("links");
   counts.links = shardLinks.length;
   const allNoteSkosRows = await db.query(`SELECT * FROM note_skos_tag ORDER BY created_at`);
@@ -29697,25 +31536,25 @@ async function exportShardBytes(db, options, mode) {
     (row) => exportedConceptIds.has(row.source_concept_id) && exportedConceptIds.has(row.target_concept_id)
   ) : allRelationRows.rows;
   const shardSkosSchemes = filteredSchemeRows.map(skosSchemeToShard);
-  files.set("skos_schemes.json", encoder3.encode(JSON.stringify(shardSkosSchemes)));
+  files.set("skos_schemes.json", encoder4.encode(JSON.stringify(shardSkosSchemes)));
   components.push("skos_schemes");
   counts.skos_schemes = shardSkosSchemes.length;
   const shardSkosConcepts = filteredConceptRows.map(skosConceptToShard);
-  files.set("skos_concepts.json", encoder3.encode(JSON.stringify(shardSkosConcepts)));
+  files.set("skos_concepts.json", encoder4.encode(JSON.stringify(shardSkosConcepts)));
   components.push("skos_concepts");
   counts.skos_concepts = shardSkosConcepts.length;
   const skosRelationsJsonl = filteredRelationRows.map((row) => JSON.stringify(skosRelationToShard(row))).join("\n");
-  files.set("skos_relations.jsonl", encoder3.encode(skosRelationsJsonl));
+  files.set("skos_relations.jsonl", encoder4.encode(skosRelationsJsonl));
   components.push("skos_relations");
   counts.skos_relations = filteredRelationRows.length;
   const noteSkosJsonl = filteredNoteSkosRows.map((row) => JSON.stringify(noteSkosTagToShard(row))).join("\n");
-  files.set("note_skos_tags.jsonl", encoder3.encode(noteSkosJsonl));
+  files.set("note_skos_tags.jsonl", encoder4.encode(noteSkosJsonl));
   components.push("note_skos_tags");
   counts.note_skos_tags = filteredNoteSkosRows.length;
   const provenanceRows = await db.query(`SELECT * FROM provenance_edge ORDER BY started_at`);
   const filteredProvenanceRows = isFiltered ? provenanceRows.rows.filter((row) => row.entity_type !== "note" || exportedNoteIds.has(row.entity_id)) : provenanceRows.rows;
   const provenanceJsonl = filteredProvenanceRows.map((row) => JSON.stringify(provenanceEdgeToShard(row))).join("\n");
-  files.set("provenance_edges.jsonl", encoder3.encode(provenanceJsonl));
+  files.set("provenance_edges.jsonl", encoder4.encode(provenanceJsonl));
   components.push("provenance_edges");
   counts.provenance_edges = filteredProvenanceRows.length;
   if (options?.includeEmbeddings) {
@@ -29755,7 +31594,7 @@ async function exportShardBytes(db, options, mode) {
         freshness_json: { status: "unknown" }
       } : row
     ));
-    files.set("embedding_sets.json", encoder3.encode(JSON.stringify(shardEmbSets)));
+    files.set("embedding_sets.json", encoder4.encode(JSON.stringify(shardEmbSets)));
     components.push("embedding_sets");
     counts.embedding_sets = shardEmbSets.length;
     const embeddingConfigRows = await db.query(
@@ -29765,7 +31604,7 @@ async function exportShardBytes(db, options, mode) {
     );
     if (embeddingConfigRows.rows.length > 0) {
       const shardEmbeddingConfigs = embeddingConfigRows.rows.map((row) => embeddingConfigToShard(row));
-      files.set("embedding_configs.json", encoder3.encode(JSON.stringify(shardEmbeddingConfigs)));
+      files.set("embedding_configs.json", encoder4.encode(JSON.stringify(shardEmbeddingConfigs)));
       components.push("embedding_configs");
       counts.embedding_configs = shardEmbeddingConfigs.length;
     }
@@ -29778,7 +31617,7 @@ async function exportShardBytes(db, options, mode) {
       (member) => exportedSetIds.has(member.embedding_set_id) && exportedNoteIds.has(member.note_id) && (includeMaterializedSelectors || !virtualSetIds.has(member.embedding_set_id))
     );
     const membersJsonl = scopedEmbMemberRows.map((m) => JSON.stringify(embeddingSetMemberToShard(m))).join("\n");
-    files.set("embedding_set_members.jsonl", encoder3.encode(membersJsonl));
+    files.set("embedding_set_members.jsonl", encoder4.encode(membersJsonl));
     components.push("embedding_set_members");
     counts.embedding_set_members = scopedEmbMemberRows.length;
     const embRows = await db.query(
@@ -29804,7 +31643,7 @@ async function exportShardBytes(db, options, mode) {
       (embedding) => exportedSetIds.has(embedding.embedding_set_id) && exportedNoteIds.has(embedding.note_id) && (memberEmbeddingIds.size === 0 || memberEmbeddingIds.has(embedding.id))
     );
     const embJsonl = scopedEmbRows.map((e) => JSON.stringify(embeddingToShard(e))).join("\n");
-    files.set("embeddings.jsonl", encoder3.encode(embJsonl));
+    files.set("embeddings.jsonl", encoder4.encode(embJsonl));
     components.push("embeddings");
     counts.embeddings = scopedEmbRows.length;
   }
@@ -29830,7 +31669,7 @@ async function exportShardBytes(db, options, mode) {
       freshness: jsonObject4(row.freshness_json) ?? { status: "unknown" },
       created_at: iso3(row.created_at)
     }));
-    files.set("graph_sources.json", encoder3.encode(JSON.stringify(shardGraphSources)));
+    files.set("graph_sources.json", encoder4.encode(JSON.stringify(shardGraphSources)));
     components.push("graph_sources");
     counts.graph_sources = shardGraphSources.length;
   }
@@ -29846,7 +31685,7 @@ async function exportShardBytes(db, options, mode) {
       rank: row.rank,
       metadata: jsonObject4(row.metadata_json)
     })).join("\n");
-    files.set("graph_edges.jsonl", encoder3.encode(graphEdgesJsonl));
+    files.set("graph_edges.jsonl", encoder4.encode(graphEdgesJsonl));
     components.push("graph_edges");
     counts.graph_edges = scopedGraphEdgeRows.length;
   }
@@ -29882,7 +31721,7 @@ async function exportShardBytes(db, options, mode) {
       })),
       created_at: iso3(row.created_at)
     }));
-    files.set("communities.json", encoder3.encode(JSON.stringify(shardCommunitySets)));
+    files.set("communities.json", encoder4.encode(JSON.stringify(shardCommunitySets)));
     components.push("communities");
     counts.community_sets = shardCommunitySets.length;
     counts.communities = scopedCommunityRows.length;
@@ -29898,7 +31737,7 @@ async function exportShardBytes(db, options, mode) {
       source_type: row.source_type,
       metadata: jsonObject4(row.metadata_json)
     })).join("\n");
-    files.set("community_assignments.jsonl", encoder3.encode(assignmentsJsonl));
+    files.set("community_assignments.jsonl", encoder4.encode(assignmentsJsonl));
     components.push("community_assignments");
     counts.community_assignments = scopedAssignmentRows.length;
   }
@@ -29921,7 +31760,7 @@ async function exportShardBytes(db, options, mode) {
     const coreTags = [...tagsByName.values()].sort(
       (left, right) => left.name.localeCompare(right.name)
     );
-    files.set("tags.json", encoder3.encode(JSON.stringify(coreTags)));
+    files.set("tags.json", encoder4.encode(JSON.stringify(coreTags)));
     components.splice(0, components.length, ...CORE_V1_COMPONENTS);
     for (const key of Object.keys(counts)) {
       if (!CORE_V1_COMPONENTS.includes(key)) delete counts[key];
@@ -29961,7 +31800,7 @@ async function exportShardBytes(db, options, mode) {
     ...!coreV1 ? { migrated_from: null } : {},
     ...!coreV1 && layout ? { layout } : {}
   };
-  files.set("manifest.json", encoder3.encode(JSON.stringify(manifest, null, 2)));
+  files.set("manifest.json", encoder4.encode(JSON.stringify(manifest, null, 2)));
   if (options?.includeBlobs && options.blobStore) {
     const packed = /* @__PURE__ */ new Set();
     for (const row of attachmentRows.rows) {
@@ -34467,7 +36306,7 @@ function getAiwgFortemiIndexExportSchema() {
 }
 function getAjv() {
   if (!ajvInstance) {
-    ajvInstance = new Ajv2020({
+    ajvInstance = new Ajv20202({
       allErrors: true,
       strict: false,
       validateFormats: false
@@ -34512,7 +36351,7 @@ function getProjectedRecordValidator() {
   return projectedRecordValidator;
 }
 function validateAiwgFortemiIndexExportSchema(value) {
-  const validate = getExportValidator();
+  const validate2 = getExportValidator();
   const schemaValue = value && typeof value === "object" && Array.isArray(value.items) ? {
     ...value,
     items: value.items.map((item) => {
@@ -34522,15 +36361,15 @@ function validateAiwgFortemiIndexExportSchema(value) {
       return schemaRecord;
     })
   } : value;
-  const valid = validate(schemaValue);
-  return { valid, errors: formatErrors2(validate.errors) };
+  const valid = validate2(schemaValue);
+  return { valid, errors: formatErrors2(validate2.errors) };
 }
 function validateAiwgFortemiProjectedRecordSchema(value) {
-  const validate = getProjectedRecordValidator();
-  const valid = validate(value);
-  return { valid, errors: formatErrors2(validate.errors) };
+  const validate2 = getProjectedRecordValidator();
+  const valid = validate2(value);
+  return { valid, errors: formatErrors2(validate2.errors) };
 }
-var encoder4 = new TextEncoder();
+var encoder5 = new TextEncoder();
 var UUID_NAMESPACE = "7ab5d1f8-29d2-5e35-9e2f-3a45de171a9e";
 function uuid(kind, id) {
   return v5(`${kind}:${id}`, UUID_NAMESPACE);
@@ -34546,7 +36385,7 @@ function addLoss(losses, code, message, details = {}) {
   losses.push({ code, message, ...details });
 }
 function encode(values, encoding) {
-  return encoder4.encode(encoding === "json-array" ? JSON.stringify(values) : values.map((value) => JSON.stringify(value)).join("\n"));
+  return encoder5.encode(encoding === "json-array" ? JSON.stringify(values) : values.map((value) => JSON.stringify(value)).join("\n"));
 }
 function noteTitle(record, losses) {
   if (own(record, "title")) return record.title ?? null;
@@ -34714,7 +36553,7 @@ async function convertAiwgIndexToFullV1(index, options = {}) {
       tags: recordTags,
       attachments: []
     });
-    const hash = await sha256Hex(encoder4.encode(content));
+    const hash = await sha256Hex(encoder5.encode(content));
     rows.get("note_originals").push({
       id: uuid("note-original", record.id),
       note_id: noteId,
@@ -34806,7 +36645,7 @@ async function convertAiwgIndexToFullV1(index, options = {}) {
       metric: null,
       algorithm: null,
       parameters: null,
-      input_hash: `sha256:${await sha256Hex(encoder4.encode(JSON.stringify(relationshipInput)))}`,
+      input_hash: `sha256:${await sha256Hex(encoder5.encode(JSON.stringify(relationshipInput)))}`,
       freshness: { status: "fresh", checked_at: exportedAt },
       created_at: exportedAt
     });
@@ -35264,7 +37103,7 @@ async function convertAiwgIndexToFullV1(index, options = {}) {
     checksums,
     min_reader_version: "2.0.0"
   };
-  const manifestBytes = encoder4.encode(JSON.stringify(manifest, null, 2));
+  const manifestBytes = encoder5.encode(JSON.stringify(manifest, null, 2));
   files.set("manifest.json", manifestBytes);
   const validation = await validateFullV1ShardArchive(files);
   if (!validation.valid) {
@@ -35519,6 +37358,7 @@ var RECORD_COLLECTIONS = [
   "note",
   "note_original",
   "note_revised_current",
+  "note_revision",
   "note_tag",
   "link",
   "collection",
@@ -35528,6 +37368,7 @@ var RECORD_COLLECTIONS = [
   "shard_manifest",
   "source_identity",
   "source_import_run",
+  "source_import_batch",
   "deletion_receipt"
 ];
 var RECORD_STORE_CAPABILITIES = {
@@ -35650,10 +37491,10 @@ var MemoryRecordStore = class {
 };
 
 // src/records/idb-record-store.ts
-var DB_VERSION = 2;
+var DB_VERSION = 3;
 var JOURNAL_STORE = "journal";
 var META_STORE = "meta";
-var RECORD_SCHEMA_VERSION = 2;
+var RECORD_SCHEMA_VERSION = 3;
 function requestToPromise(request) {
   return new Promise((resolve, reject) => {
     request.onsuccess = () => resolve(request.result);
@@ -36210,10 +38051,11 @@ function collectionsParentFirst(collections) {
   return ordered;
 }
 async function projectNotes(db, store) {
-  const [noteRows, originals, revised, tags, links, collections, memberships] = await Promise.all([
+  const [noteRows, originals, revised, revisions, tags, links, collections, memberships] = await Promise.all([
     store.list("note"),
     store.list("note_original"),
     store.list("note_revised_current"),
+    store.list("note_revision"),
     store.list("note_tag"),
     store.list("link"),
     store.list("collection"),
@@ -36310,6 +38152,28 @@ async function projectNotes(db, store) {
       ]
     );
   }
+  for (const r of revisions) {
+    await db.query(
+      `INSERT INTO note_revision (id, note_id, revision_number, type, content, ai_metadata, model, created_at)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8)
+       ON CONFLICT (id) DO UPDATE SET
+         revision_number = EXCLUDED.revision_number,
+         type = EXCLUDED.type,
+         content = EXCLUDED.content,
+         ai_metadata = EXCLUDED.ai_metadata,
+         model = EXCLUDED.model`,
+      [
+        r.id,
+        r.note_id,
+        r.revision_number,
+        r.type,
+        r.content,
+        r.ai_metadata == null ? null : JSON.stringify(r.ai_metadata),
+        r.model,
+        r.created_at
+      ]
+    );
+  }
   for (const t of tags) {
     await db.query(
       `INSERT INTO note_tag (id, note_id, tag, created_at)
@@ -36346,6 +38210,7 @@ async function projectNotes(db, store) {
   );
   return {
     notes: noteRows.length,
+    revisions: revisions.length,
     tags: tags.length,
     links: links.length,
     collections: collections.length,
@@ -36499,7 +38364,7 @@ function createRecordBackend(store, options = {}) {
 }
 
 // src/records/record-shard.ts
-var encoder5 = new TextEncoder();
+var encoder6 = new TextEncoder();
 var decoder8 = new TextDecoder();
 function emptyCounts3() {
   return {
@@ -36757,11 +38622,11 @@ async function buildRecordShardArchive(store, options, profile) {
       const slice = shardNotes.slice(offset, offset + clusterSize);
       const href = `notes/${String(offset).padStart(6, "0")}.jsonl`;
       clusters.push({ href, offset });
-      files.set(href, encoder5.encode(slice.map((n) => JSON.stringify(n)).join("\n")));
+      files.set(href, encoder6.encode(slice.map((n) => JSON.stringify(n)).join("\n")));
     }
     layout = { clusters: { notes: clusters } };
   } else {
-    files.set("notes.jsonl", encoder5.encode(shardNotes.map((n) => JSON.stringify(n)).join("\n")));
+    files.set("notes.jsonl", encoder6.encode(shardNotes.map((n) => JSON.stringify(n)).join("\n")));
   }
   components.push("notes");
   counts.notes = shardNotes.length;
@@ -36789,7 +38654,7 @@ async function buildRecordShardArchive(store, options, profile) {
       note_count: mapped.note_count ?? 0
     };
   });
-  files.set("collections.json", encoder5.encode(JSON.stringify(shardCollections)));
+  files.set("collections.json", encoder6.encode(JSON.stringify(shardCollections)));
   components.push("collections");
   counts.collections = shardCollections.length;
   const distinctTags = [...new Set(
@@ -36806,7 +38671,7 @@ async function buildRecordShardArchive(store, options, profile) {
       created_at: tagCreatedAt.get(name) ?? (/* @__PURE__ */ new Date(0)).toISOString()
     }))
   );
-  files.set("tags.json", encoder5.encode(JSON.stringify(shardTags)));
+  files.set("tags.json", encoder6.encode(JSON.stringify(shardTags)));
   components.push("tags");
   counts.tags = shardTags.length;
   const links = await store.list("link");
@@ -36828,7 +38693,7 @@ async function buildRecordShardArchive(store, options, profile) {
     }
     return shard;
   });
-  files.set("links.jsonl", encoder5.encode(shardLinks.map((l) => JSON.stringify(l)).join("\n")));
+  files.set("links.jsonl", encoder6.encode(shardLinks.map((l) => JSON.stringify(l)).join("\n")));
   components.push("links");
   counts.links = shardLinks.length;
   const checksums = {};
@@ -36958,7 +38823,7 @@ async function buildRecordShardArchive(store, options, profile) {
       );
     }
   }
-  files.set("manifest.json", encoder5.encode(JSON.stringify(manifest, null, 2)));
+  files.set("manifest.json", encoder6.encode(JSON.stringify(manifest, null, 2)));
   if (options?.includeBlobs && options.blobStore) {
     const packed = /* @__PURE__ */ new Set();
     for (const checksum of exportedBlobChecksums) {
@@ -37344,7 +39209,7 @@ async function importShardToRecords(store, data, options) {
       id: existingOriginal?.id ?? generateId(),
       note_id: note.id,
       content: note.original_content,
-      content_hash: computeHash(encoder5.encode(note.original_content)),
+      content_hash: computeHash(encoder6.encode(note.original_content)),
       created_at: createdAt2
     };
     mutations.push({ op: "put", collection: "note_original", record: originalRecord });
@@ -37580,177 +39445,283 @@ async function importShardToRecords(store, data, options) {
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString();
 }
-function contentDigest2(content) {
-  return computeHash(new TextEncoder().encode(content));
-}
-function sourceHash2(source) {
-  return computeHash(new TextEncoder().encode([
-    source.tenant_id ?? "default",
-    source.archive_id ?? "",
-    source.namespace,
-    source.external_id
-  ].join("\0")));
-}
 function countOutcomes2(outcomes) {
   return {
-    inserted: outcomes.filter((outcome) => outcome.outcome === "inserted").length,
-    unchanged: outcomes.filter((outcome) => outcome.outcome === "unchanged").length,
-    versioned: outcomes.filter((outcome) => outcome.outcome === "versioned").length,
-    replaced: outcomes.filter((outcome) => outcome.outcome === "replaced").length,
-    conflict: outcomes.filter((outcome) => outcome.outcome === "conflict").length,
-    rejected: outcomes.filter((outcome) => outcome.outcome === "rejected").length
+    inserted: outcomes.filter((item) => item.outcome === "inserted").length,
+    unchanged: outcomes.filter((item) => item.outcome === "unchanged").length,
+    versioned: outcomes.filter((item) => item.outcome === "versioned").length,
+    replaced: outcomes.filter((item) => item.outcome === "replaced").length,
+    conflict: outcomes.filter((item) => item.outcome === "conflict").length,
+    rejected: outcomes.filter((item) => item.outcome === "rejected").length
+  };
+}
+function finish2(importRunId, batchId, dryRun, outcome, items, checkpoint) {
+  return {
+    contract_version: SOURCE_UPSERT_CONTRACT_VERSION,
+    import_run_id: importRunId,
+    batch_id: batchId,
+    dry_run: dryRun,
+    outcome,
+    ...checkpoint ? { checkpoint } : {},
+    items,
+    outcomes: items,
+    counts: countOutcomes2(items)
   };
 }
 async function findSource(store, source) {
   const identities = await store.list("source_identity");
   return identities.find((identity) => identity.tenant_id === (source.tenant_id ?? "default") && identity.archive_id === (source.archive_id ?? null) && identity.namespace === source.namespace && identity.external_id === source.external_id) ?? null;
 }
+async function upsertRecordStoreRequest(store, request, scope = {}) {
+  const items = request.items.map((item) => ({
+    source: {
+      tenant_id: scope.tenant_id ?? "default",
+      archive_id: scope.archive_id ?? null,
+      namespace: request.source_namespace,
+      external_id: item.external_id,
+      source_schema_version: request.source_schema_version,
+      import_run_id: request.import_run_id,
+      source_id: request.source_id,
+      workspace_id: request.workspace_id,
+      caller_stable_id: item.caller_stable_id
+    },
+    title: item.title,
+    content: item.content,
+    content_digest: item.content_digest,
+    format: item.format,
+    metadata: item.metadata,
+    policy: item.policy ?? request.policy
+  }));
+  const result = await upsertRecordStoreSources(store, items, {
+    dryRun: request.dry_run,
+    batchId: request.batch_id,
+    checkpoint: request.checkpoint,
+    policy: request.policy
+  });
+  return {
+    contract_version: result.contract_version,
+    import_run_id: result.import_run_id,
+    batch_id: result.batch_id,
+    dry_run: result.dry_run,
+    outcome: result.outcome,
+    ...result.checkpoint ? { checkpoint: result.checkpoint } : {},
+    counts: result.counts,
+    items: result.items
+  };
+}
 async function upsertRecordStoreSources(store, items, options = {}) {
-  const maxItems = options.maxItems ?? 500;
-  if (items.length > maxItems) throw new Error(`Source upsert batch exceeds the ${maxItems} item bound`);
   if (!store.applyBatch) throw new Error("RecordStore source upsert requires atomic applyBatch() support");
-  if (items.length === 0) {
-    return {
-      import_run_id: "",
-      dry_run: options.dryRun === true,
-      outcomes: [],
-      counts: { inserted: 0, unchanged: 0, versioned: 0, replaced: 0, conflict: 0, rejected: 0 }
-    };
+  const importRunId = items[0]?.source.import_run_id ?? "";
+  const requestDigest = sourceRequestDigest(items, options);
+  const batchId = options.batchId ?? deriveSourceBatchId(requestDigest);
+  const batchReason = batchId.length === 0 || batchId.length > 200 ? "invalid_batch_metadata" : JSON.stringify(options.checkpoint ?? {}).length > 65536 ? "checkpoint_too_large" : void 0;
+  const validation = validate(items, options.maxItems ?? 500, batchReason);
+  if (validation) return finish2(importRunId, batchId, options.dryRun === true, "rejected", validation, options.checkpoint);
+  const batches = await store.list("source_import_batch");
+  const prior = batches.find((batch2) => batch2.tenant_id === (items[0].source.tenant_id ?? "default") && batch2.archive_id === (items[0].source.archive_id ?? null) && batch2.namespace === items[0].source.namespace && batch2.batch_id === batchId);
+  if (prior) {
+    if (prior.request_digest !== requestDigest) {
+      const rejected = items.map((item, index) => ({
+        index,
+        outcome: "rejected",
+        external_id_hash: sourceIdentityHash(item.source),
+        content_digest: sourceContentDigest(item.content),
+        reason_code: "batch_id_reused_with_different_request"
+      }));
+      return finish2(importRunId, batchId, false, "rejected", rejected, options.checkpoint);
+    }
+    const receipt = prior.receipt;
+    const unchanged = receipt.items.map((item) => ({ ...item, outcome: "unchanged", reason_code: void 0, reason: void 0 }));
+    return finish2(importRunId, batchId, false, "duplicate", unchanged, receipt.checkpoint);
   }
   const outcomes = [];
   const mutations = [];
   const stamp = now();
   for (const [index, item] of items.entries()) {
-    const external_id_hash = sourceHash2(item.source);
-    const content_digest = contentDigest2(item.content);
+    const external_id_hash = sourceIdentityHash(item.source);
+    const content_digest = sourceContentDigest(item.content);
     const existing = await findSource(store, item.source);
     if (!existing) {
       const noteId = item.source.caller_stable_id ?? generateId();
-      outcomes.push({ index, outcome: "inserted", note_id: noteId, external_id_hash, content_digest });
-      if (!options.dryRun) {
-        const note2 = {
-          id: noteId,
-          archive_id: item.source.archive_id ?? null,
-          title: item.title ?? null,
-          format: item.format ?? "markdown",
-          source: `source:${item.source.namespace}`,
-          visibility: item.visibility ?? "private",
-          revision_mode: "standard",
-          is_starred: false,
-          is_pinned: false,
-          is_archived: false,
-          created_at: stamp,
-          updated_at: stamp,
-          deleted_at: null
-        };
-        const original = {
-          id: generateId(),
-          note_id: noteId,
-          content: item.content,
-          content_hash: content_digest,
-          created_at: stamp
-        };
-        const current2 = {
-          id: noteId,
-          content: item.content,
-          ai_metadata: item.metadata ?? null,
-          generation_count: 0,
-          model: null,
-          is_user_edited: false,
-          updated_at: stamp
-        };
-        const identity = {
-          id: generateId(),
-          tenant_id: item.source.tenant_id ?? "default",
-          archive_id: item.source.archive_id ?? null,
-          namespace: item.source.namespace,
-          external_id: item.source.external_id,
-          external_id_hash,
-          source_schema_version: item.source.source_schema_version,
-          content_digest,
-          import_run_id: item.source.import_run_id,
-          caller_stable_id: item.source.caller_stable_id ?? null,
-          note_id: noteId,
-          created_at: stamp,
-          updated_at: stamp
-        };
-        mutations.push(
-          { op: "put", collection: "note", record: note2 },
-          { op: "put", collection: "note_original", record: original },
-          { op: "put", collection: "note_revised_current", record: current2 },
-          { op: "put", collection: "source_identity", record: identity }
-        );
+      if (await store.get("note", noteId)) {
+        const rejected = items.map((candidate, candidateIndex) => ({
+          index: candidateIndex,
+          outcome: "rejected",
+          external_id_hash: sourceIdentityHash(candidate.source),
+          content_digest: sourceContentDigest(candidate.content),
+          reason_code: "caller_stable_id_conflict"
+        }));
+        return finish2(importRunId, batchId, false, "rejected", rejected, options.checkpoint);
       }
+      outcomes.push({ index, outcome: "inserted", note_id: noteId, external_id_hash, content_digest });
+      if (!options.dryRun) addInsertMutations(mutations, item, noteId, content_digest, external_id_hash, stamp);
       continue;
     }
     if (existing.content_digest === content_digest) {
       outcomes.push({ index, outcome: "unchanged", note_id: existing.note_id, external_id_hash, content_digest });
       continue;
     }
-    const policy = item.policy ?? "version";
+    const policy = item.policy ?? options.policy ?? "version";
     if (policy === "conflict") {
       outcomes.push({ index, outcome: "conflict", note_id: existing.note_id, external_id_hash, content_digest });
       continue;
     }
     const note = await store.get("note", existing.note_id);
     const current = await store.get("note_revised_current", existing.note_id);
-    if (!note || !current) {
-      outcomes.push({ index, outcome: "rejected", note_id: existing.note_id, external_id_hash, content_digest, reason: "source identity points to a missing note" });
-      continue;
+    const originals = await store.list("note_original");
+    const original = originals.find((candidate) => candidate.note_id === existing.note_id);
+    if (!note || !current || !original) {
+      const rejected = items.map((candidate, candidateIndex) => ({
+        index: candidateIndex,
+        outcome: "rejected",
+        note_id: candidateIndex === index ? existing.note_id : void 0,
+        external_id_hash: sourceIdentityHash(candidate.source),
+        content_digest: sourceContentDigest(candidate.content),
+        reason_code: "invalid_item"
+      }));
+      return finish2(importRunId, batchId, false, "rejected", rejected, options.checkpoint);
     }
     const outcome = policy === "replace" ? "replaced" : "versioned";
     outcomes.push({ index, outcome, note_id: existing.note_id, external_id_hash, content_digest });
     if (!options.dryRun) {
-      mutations.push(
-        {
-          op: "put",
-          collection: "note",
-          record: {
-            ...note,
-            title: item.title ?? null,
-            archive_id: item.source.archive_id ?? null,
-            format: item.format ?? "markdown",
-            visibility: item.visibility ?? "private",
-            deleted_at: null,
-            updated_at: stamp
-          }
-        },
-        {
-          op: "put",
-          collection: "note_revised_current",
-          record: { ...current, content: item.content, ai_metadata: item.metadata ?? null, is_user_edited: false, updated_at: stamp }
-        },
-        {
-          op: "put",
-          collection: "source_identity",
-          record: { ...existing, source_schema_version: item.source.source_schema_version, content_digest, import_run_id: item.source.import_run_id, updated_at: stamp }
-        }
-      );
-    }
-  }
-  if (!options.dryRun && hasMaterialChange2(outcomes)) {
-    const run = {
-      id: items[0].source.import_run_id,
-      tenant_id: items[0].source.tenant_id ?? "default",
-      archive_id: items[0].source.archive_id ?? null,
-      namespace: items[0].source.namespace,
-      started_at: stamp,
-      completed_at: stamp,
-      checkpoint: { item_count: items.length },
-      receipt: { counts: countOutcomes2(outcomes) }
+      const revisionNumber = outcome === "versioned" ? (await store.list("note_revision")).filter((row) => row.note_id === existing.note_id).length + 1 : void 0;
+      addUpdateMutations(mutations, item, existing, note, current, original, outcome, content_digest, stamp, revisionNumber);
+    }
+  }
+  if (options.dryRun) return finish2(importRunId, batchId, true, "preview", outcomes, options.checkpoint);
+  const committed = finish2(importRunId, batchId, false, "committed", outcomes, options.checkpoint);
+  const contractReceipt = {
+    contract_version: committed.contract_version,
+    import_run_id: committed.import_run_id,
+    batch_id: committed.batch_id,
+    dry_run: committed.dry_run,
+    outcome: committed.outcome,
+    ...committed.checkpoint ? { checkpoint: committed.checkpoint } : {},
+    counts: committed.counts,
+    items: committed.items
+  };
+  const run = {
+    id: sourceRunRecordId(items[0].source),
+    external_run_id: importRunId,
+    source_id: items[0].source.source_id ?? null,
+    source_schema_version: items[0].source.source_schema_version,
+    workspace_id: items[0].source.workspace_id ?? null,
+    tenant_id: items[0].source.tenant_id ?? "default",
+    archive_id: items[0].source.archive_id ?? null,
+    namespace: items[0].source.namespace,
+    started_at: stamp,
+    completed_at: stamp,
+    checkpoint: options.checkpoint ?? {},
+    receipt: contractReceipt
+  };
+  const batch = {
+    id: generateId(),
+    tenant_id: items[0].source.tenant_id ?? "default",
+    archive_id: items[0].source.archive_id ?? null,
+    namespace: items[0].source.namespace,
+    batch_id: batchId,
+    request_digest: requestDigest,
+    import_run_id: importRunId,
+    outcome: "committed",
+    checkpoint: options.checkpoint ?? {},
+    receipt: contractReceipt,
+    created_at: stamp
+  };
+  mutations.push(
+    { op: "put", collection: "source_import_run", record: run },
+    { op: "put", collection: "source_import_batch", record: batch }
+  );
+  await store.applyBatch(mutations);
+  return committed;
+}
+function addInsertMutations(mutations, item, noteId, contentDigest, externalIdHash, stamp) {
+  const note = {
+    id: noteId,
+    archive_id: item.source.archive_id ?? null,
+    title: item.title ?? null,
+    format: item.format ?? "markdown",
+    source: `source:${item.source.namespace}`,
+    visibility: item.visibility ?? "private",
+    revision_mode: "standard",
+    is_starred: false,
+    is_pinned: false,
+    is_archived: false,
+    created_at: stamp,
+    updated_at: stamp,
+    deleted_at: null
+  };
+  const original = { id: generateId(), note_id: noteId, content: item.content, content_hash: contentDigest, created_at: stamp };
+  const current = { id: noteId, content: item.content, ai_metadata: item.metadata ?? null, generation_count: 0, model: null, is_user_edited: false, updated_at: stamp };
+  const revision = { id: generateId(), note_id: noteId, revision_number: 1, type: "source-import", content: item.content, ai_metadata: item.metadata ?? null, model: null, created_at: stamp };
+  const identity = {
+    id: generateId(),
+    tenant_id: item.source.tenant_id ?? "default",
+    archive_id: item.source.archive_id ?? null,
+    namespace: item.source.namespace,
+    external_id: item.source.external_id,
+    external_id_hash: externalIdHash,
+    source_id: item.source.source_id ?? null,
+    source_schema_version: item.source.source_schema_version,
+    content_digest: contentDigest,
+    import_run_id: item.source.import_run_id,
+    caller_stable_id: item.source.caller_stable_id ?? null,
+    note_id: noteId,
+    created_at: stamp,
+    updated_at: stamp
+  };
+  mutations.push(
+    { op: "put", collection: "note", record: note },
+    { op: "put", collection: "note_original", record: original },
+    { op: "put", collection: "note_revised_current", record: current },
+    { op: "put", collection: "note_revision", record: revision },
+    { op: "put", collection: "source_identity", record: identity }
+  );
+}
+function addUpdateMutations(mutations, item, identity, note, current, original, outcome, contentDigest, stamp, revisionNumber) {
+  mutations.push(
+    { op: "put", collection: "note", record: { ...note, title: item.title ?? null, archive_id: item.source.archive_id ?? null, format: item.format ?? "markdown", visibility: item.visibility ?? "private", deleted_at: null, updated_at: stamp } },
+    { op: "put", collection: "note_revised_current", record: { ...current, content: item.content, ai_metadata: item.metadata ?? null, is_user_edited: false, updated_at: stamp } },
+    { op: "put", collection: "source_identity", record: { ...identity, source_id: item.source.source_id ?? null, source_schema_version: item.source.source_schema_version, content_digest: contentDigest, import_run_id: item.source.import_run_id, updated_at: stamp } }
+  );
+  if (outcome === "replaced") {
+    mutations.push({ op: "put", collection: "note_original", record: { ...original, content: item.content, content_hash: contentDigest } });
+  } else {
+    const revision = {
+      id: generateId(),
+      note_id: identity.note_id,
+      revision_number: revisionNumber ?? 1,
+      type: "source-import",
+      content: item.content,
+      ai_metadata: item.metadata ?? null,
+      model: null,
+      created_at: stamp
     };
-    mutations.push({ op: "put", collection: "source_import_run", record: run });
-    await store.applyBatch(mutations);
+    mutations.push({ op: "put", collection: "note_revision", record: revision });
   }
-  return {
-    import_run_id: items[0].source.import_run_id,
-    dry_run: options.dryRun === true,
-    outcomes,
-    counts: countOutcomes2(outcomes)
-  };
 }
-function hasMaterialChange2(outcomes) {
-  return outcomes.some((outcome) => outcome.outcome === "inserted" || outcome.outcome === "versioned" || outcome.outcome === "replaced");
+function validate(items, maxItems, initialReason) {
+  let reason = initialReason ?? (items.length === 0 || items.length > maxItems ? "batch_size_out_of_bounds" : null);
+  const seen = /* @__PURE__ */ new Set();
+  const stableIds = /* @__PURE__ */ new Set();
+  for (const item of items) {
+    if (!item.source.tenant_id || !item.source.namespace || !item.source.external_id || !item.source.source_schema_version || !item.source.import_run_id || !item.content) reason ??= "invalid_item";
+    if ((item.source.source_id?.length ?? 0) > 500 || item.source.source_id === "" || (item.source.workspace_id?.length ?? 0) > 500 || item.source.workspace_id === "") reason ??= "invalid_batch_metadata";
+    if ((item.format ?? "markdown").length > 100 || (item.title?.length ?? 0) > 2e3 || JSON.stringify(item.metadata ?? {}).length > 262144) reason ??= "invalid_item";
+    if (item.content_digest && item.content_digest !== sourceContentDigest(item.content)) reason ??= "content_digest_mismatch";
+    const key = `${item.source.tenant_id}\0${item.source.archive_id ?? ""}\0${item.source.namespace}\0${item.source.external_id}`;
+    if (seen.has(key)) reason ??= "duplicate_external_id_in_batch";
+    seen.add(key);
+    if (item.source.caller_stable_id && stableIds.has(item.source.caller_stable_id)) reason ??= "caller_stable_id_conflict";
+    if (item.source.caller_stable_id) stableIds.add(item.source.caller_stable_id);
+  }
+  if (!reason) return null;
+  return items.map((item, index) => ({
+    index,
+    outcome: "rejected",
+    external_id_hash: sourceIdentityHash(item.source),
+    content_digest: sourceContentDigest(item.content ?? ""),
+    reason_code: reason
+  }));
 }
 
 // src/records/lifecycle-purge.ts
@@ -37870,8 +39841,8 @@ async function purgeRecordStoreGraph(store, selector, operationKey) {
 }
 
 // src/index.ts
-var VERSION = "2026.8.0";
+var VERSION = "2026.9.1";
 
-export { AIWG_SCAN_REQUIRED_FIELDS, AllowlistTrustStore, ArchiveManager, AttachmentsRepository, CORE_V1_COMPONENTS, CURRENT_MIGRATION_HEAD, CURRENT_SHARD_VERSION, CanonicalAttachmentsRepository, CanonicalNotesRepository, CapabilityManager, CaptureKnowledgeInputSchema, CollectionsRepository, CommunitiesRepository, DB_SNAPSHOT_SCHEMA_VERSION, DbSnapshotVersionError, EMBED_REQUEST_KIND, EMBED_RESPONSE_KIND, EmbeddingSetsRepository, FORTEMI_COMPATIBILITY_PATH, FORTEMI_COMPATIBILITY_STATES, FORTEMI_REQUIRED_COMPATIBILITY_CAPABILITIES, FORTEMI_SERVER_COMPATIBILITY_REVISION, FallbackRouter, FortemiToolManifest, GetNoteInputSchema, GraphRepository, IdbRecordStore, JOB_CAPABILITIES, JOB_PRIORITIES, JobQueueWorker, LOCAL_ENDPOINTS, LifecyclePurgeRepository, LinksRepository, ListNotesInputSchema, ManageArchiveInputSchema, ManageAttachmentsInputSchema, ManageCapabilitiesInputSchema, ManageCollectionsInputSchema, ManageLinksInputSchema, ManageNoteInputSchema, ManageTagsInputSchema, MemoryBlobStore, MemoryRecordStore, MigrationRunner, NotesRepository, OpenAICompatibleProvider, PGliteStorageBackend, PGliteStorageBackendFactory, PGliteWorkerClient, PGliteWorkerStorageBackend, PGliteWorkerStorageBackendFactory, ProvenanceRepository, ProviderRegistry, RECORD_COLLECTIONS, RECORD_SCHEMA_VERSION, RECORD_STORE_CAPABILITIES, REGISTERED_METADATA_PATHS, SHARD_FORMAT, SIGNATURE_ENTRY, SIGNING_ENVELOPE_VERSION, SUPPORTED_PGLITE_VERSION, SearchInputSchema, SearchRepository, SkosRepository, SourceUpsertRepository, TagsRepository, TransactionProxy, TypedEventBus, VERSION, aiRevisionHandler, aiwgFortemiIndexFromKnowledgeShard, aiwgFortemiIndexToCommunityGraph, aiwgFortemiIndexToKnowledgeShard, aiwgFortemiIndexToKnowledgeShardWithReport, allMigrations, appendPluginScript, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, assertAiwgStaticEmbeddingSet, assertShardComponentRecord, buildAiwgChunkedIndex, buildAiwgStaticEmbeddingSet, buildMetadataPredicateConditions, buildNoteConditions, buildPluginCsp, captureKnowledge, chunkText, classifyError, classifyModel, clearPrefetchedShard, collectionFromShard, collectionToShard, computeBlobHash, computeHash, computeSri, conceptTaggingHandler, cosineSimilarity, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, createBlobStore, createCosineSemanticProvider, createCspReportHandler, createFortemi, createLazyBlobStore, createLegacyProvider, createPGliteBackend, createPGliteInstance, createRecordBackend, createRecordStore, createRemoteBackend, createRoutes, createShardBackend, createShardCapabilityReport, createWorkerEmbedFunction, defaultStorageBackendFactory, detectCommunities, detectGpuCapabilities, detectInferenceCapabilities, discoverLocalProviders, dropAttachmentProjection, dropNoteProjection, dumpDbSnapshot, embeddingConfigToShard, embeddingFromShard, embeddingGenerationHandler, embeddingSetFromShard, embeddingSetMemberToShard, embeddingSetToShard, embeddingToShard, enqueueFullWorkflow, enqueueJob, enqueueNoteCreationJobs, estimateModelFit, estimateVramMB, estimateVramTier, exportShard, exportShardFromRecords, exportShardFromRecordsWithReport, exportShardWithReport, fetchAndValidateFortemiCompatibility, fetchPluginScript, filterAiwgRecordsByPrivacy, findAiwgStaticDuplicatePairs, formatFortemiCompatibilitySummary, fortemiCompatibilityUrl, fortemiManifest, fromPrefetched, generateId, getAiwgFortemiFacets, getAiwgFortemiIndexExportSchema, getEmbedFunction, getFortemiBridge, getFortemiSecretStore, getJobQueueStatus, getKnowledgeShardContractReceipt, getKnowledgeShardProfileRegistry, getKnowledgeShardSchema, getLlmFunction, getNote, getPrefetchedSha256, handleEmbedRequests, hasFortemiSecureSecrets, importShard, importShardToRecords, isPluginScriptAllowed, isShardPrefetched, isShardSigningSupported, linkFromShard, linkToShard, linkingHandler, listNotes, manageArchive, manageAttachments, manageCapabilities, manageCollections, manageLinks, manageNote, manageTags, matchRoute, migrateLegacyBlobStore, noteFromShard, noteSkosTagToShard, noteToShard, openShard, packTarGz, parseCspReport, prefetchShard, previewRecordStorePurge, profileSupportError, projectAttachments, projectNotes, projectRecords, provenanceEdgeToShard, purgeRecordStoreGraph, queryAiwgFortemiIndex, queryAiwgHybridIndex, queryAiwgSemanticIndex, registerLlmCapability, registerSemanticCapability, registerSemanticCapabilityWorker, registerServiceWorker, restoreDbSnapshot, searchTool, selectBackend, selectLlmModel, setEmbedFunction, setLlmFunction, sha256Hex, sidecarBlobDigests, signShard, skosConceptToShard, skosRelationToShard, skosSchemeToShard, suggestTags, tagsToShard, templateToShard, titleGenerationHandler, unpackTarGz, unregisterLlmCapability, unregisterSemanticCapability, upsertRecordStoreSources, urlLinkToShard, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport, validateAiwgFortemiIndexExportSchema, validateAiwgFortemiProjectedRecordSchema, validateAiwgStaticEmbeddingSet, validateChecksums, validateCoreV1ShardArchive, validateFortemiCompatibilityResponse, validateFullV1ShardArchive, validateRecordV1ShardArchive, validateShardArchive, validateShardComponentRecord, validateShardManifest, verifyDbSnapshotMeta, verifyShardSignature, verifySri };
+export { AIWG_SCAN_REQUIRED_FIELDS, AllowlistTrustStore, ArchiveManager, AttachmentsRepository, BridgeInferenceProvider, CORE_V1_COMPONENTS, CURRENT_MIGRATION_HEAD, CURRENT_SHARD_VERSION, CanonicalAttachmentsRepository, CanonicalNotesRepository, CapabilityManager, CaptureKnowledgeInputSchema, CollectionsRepository, CommunitiesRepository, DATASET_EXECUTION_CAPABILITY_IDS, DATASET_EXECUTION_CONTRACT, DATASET_EXECUTION_SCHEMA_VERSION, DATASET_INGEST_CONTRACT, DATASET_INGEST_SCHEMA_VERSION, DATASET_LINEAGE_CONTRACT, DATASET_LINEAGE_SCHEMA_VERSION, DATASET_MATERIALIZATION_CONTRACT, DATASET_MATERIALIZATION_KINDS, DATASET_MATERIALIZATION_SCHEMA_VERSION, DB_SNAPSHOT_SCHEMA_VERSION, DEFAULT_LARGE_DOCUMENT_CHARS, DEFAULT_LARGE_DOCUMENT_CHUNKS, DatasetIngestError, DatasetIngestExecutor, DatasetLineageLedger, DatasetMaterializationError, DbSnapshotVersionError, EMBED_REQUEST_KIND, EMBED_RESPONSE_KIND, EmbeddingSetsRepository, FORTEMI_BROWSER_LOCAL_DATASET_EXECUTION_DESCRIPTOR, FORTEMI_COMPATIBILITY_PATH, FORTEMI_COMPATIBILITY_STATES, FORTEMI_PORTABLE_SHARD_DATASET_EXECUTION_DESCRIPTOR, FORTEMI_REQUIRED_COMPATIBILITY_CAPABILITIES, FORTEMI_SERVER_COMPATIBILITY_REVISION, FORTEMI_STATIC_CACHE_DATASET_EXECUTION_DESCRIPTOR, FallbackRouter, FortemiToolManifest, GetNoteInputSchema, GraphRepository, IdbRecordStore, JOB_CAPABILITIES, JOB_PRIORITIES, JobQueueWorker, LINEAGE_ENTITY_KINDS, LINEAGE_RELATIONSHIP_KINDS, LOCAL_ENDPOINTS, LifecyclePurgeRepository, LineageValidationError, LinksRepository, ListNotesInputSchema, ManageArchiveInputSchema, ManageAttachmentsInputSchema, ManageCapabilitiesInputSchema, ManageCollectionsInputSchema, ManageLinksInputSchema, ManageNoteInputSchema, ManageTagsInputSchema, MemoryBlobStore, MemoryDatasetIngestStore, MemoryRecordStore, MigrationRunner, NotesRepository, OpenAICompatibleProvider, PGliteStorageBackend, PGliteStorageBackendFactory, PGliteWorkerClient, PGliteWorkerStorageBackend, PGliteWorkerStorageBackendFactory, ProvenanceRepository, ProviderRegistry, RECORD_COLLECTIONS, RECORD_SCHEMA_VERSION, RECORD_STORE_CAPABILITIES, REGISTERED_METADATA_PATHS, SHARD_FORMAT, SIGNATURE_ENTRY, SIGNING_ENVELOPE_VERSION, SOURCE_UPSERT_CONTRACT_VERSION, SOURCE_UPSERT_MAX_ITEMS, SUPPORTED_PGLITE_VERSION, SearchInputSchema, SearchRepository, SkosRepository, SourceUpsertRepository, TagsRepository, TransactionProxy, TypedEventBus, VERSION, aiRevisionHandler, aiwgFortemiIndexFromKnowledgeShard, aiwgFortemiIndexToCommunityGraph, aiwgFortemiIndexToKnowledgeShard, aiwgFortemiIndexToKnowledgeShardWithReport, allMigrations, appendPluginScript, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, assertAiwgStaticEmbeddingSet, assertShardComponentRecord, buildAiwgChunkedIndex, buildAiwgStaticEmbeddingSet, buildMetadataPredicateConditions, buildNoteConditions, buildPluginCsp, captureKnowledge, chunkText, classifyError, classifyModel, clearPrefetchedShard, collectionFromShard, collectionToShard, compareDatasetIncrementalParity, computeBlobHash, computeHash, computeLineageDigest, computeSri, conceptTaggingHandler, configureInferenceRuntime, cosineSimilarity, createAiwgFetchChunkLoader, createAiwgFetchDetailLoader, createAiwgIndexController, createAiwgReviewDecisionExport, createBlobStore, createBridgeInferenceProviders, createCosineSemanticProvider, createCspReportHandler, createFortemi, createLazyBlobStore, createLegacyProvider, createLocalProviderProfile, createPGliteBackend, createPGliteInstance, createRecordBackend, createRecordStore, createRemoteBackend, createRoutes, createShardBackend, createShardCapabilityReport, createWorkerEmbedFunction, datasetDestinationScopeKey, defaultStorageBackendFactory, defineInferenceProvider, defineInferenceRuntime, defineLegacyInferenceProvider, defineOpenAICompatibleProvider, deriveDatasetIngestIdempotencyKey, detectCommunities, detectGpuCapabilities, detectInferenceCapabilities, digestDatasetMaterializationValue, discoverLocalProviders, dropAttachmentProjection, dropNoteProjection, dumpDbSnapshot, embeddingConfigToShard, embeddingFromShard, embeddingGenerationHandler, embeddingSetFromShard, embeddingSetMemberToShard, embeddingSetToShard, embeddingToShard, enqueueFullWorkflow, enqueueJob, enqueueNoteCreationJobs, estimateModelFit, estimateVramMB, estimateVramTier, executeDatasetMaterialization, executeDatasetRetrieval, exportShard, exportShardFromRecords, exportShardFromRecordsWithReport, exportShardWithReport, fetchAndValidateFortemiCompatibility, fetchPluginScript, filterAiwgRecordsByPrivacy, findAiwgStaticDuplicatePairs, formatFortemiCompatibilitySummary, fortemiCompatibilityUrl, fortemiManifest, fromPrefetched, generateId, getAiwgFortemiFacets, getAiwgFortemiIndexExportSchema, getConfiguredInferenceProviderId, getEmbedFunction, getEmbeddingTaskSelectionOptions, getFortemiBridge, getFortemiSecretStore, getJobQueueStatus, getKnowledgeShardContractReceipt, getKnowledgeShardProfileRegistry, getKnowledgeShardSchema, getLlmFunction, getNote, getPrefetchedSha256, getProviderRouteRequirementIssue, handleEmbedRequests, hasFortemiSecureSecrets, importShard, importShardToRecords, inferInferenceTaskCapability, inferLocalEmbeddingDimensions, isPluginScriptAllowed, isShardPrefetched, isShardSigningSupported, linkFromShard, linkToShard, linkingHandler, listNotes, manageArchive, manageAttachments, manageCapabilities, manageCollections, manageLinks, manageNote, manageTags, matchRoute, mergeInferenceRuntimeConfigs, migrateLegacyBlobStore, negotiateDatasetExecutionCapabilities, negotiateDatasetMaterializationProfile, noteFromShard, noteSkosTagToShard, noteToShard, openShard, packTarGz, parseCspReport, prefetchShard, previewRecordStorePurge, profileSupportError, projectAttachments, projectNotes, projectRecords, provenanceEdgeToShard, providerSatisfiesRouteRequirements, purgeRecordStoreGraph, queryAiwgFortemiIndex, queryAiwgHybridIndex, queryAiwgSemanticIndex, registerLlmCapability, registerSemanticCapability, registerSemanticCapabilityWorker, registerServiceWorker, restoreDbSnapshot, searchTool, selectBackend, selectEmbeddingTask, selectLlmModel, setEmbedFunction, setEmbeddingTaskSelectionOptions, setLlmFunction, sha256Hex, sidecarBlobDigests, signShard, skosConceptToShard, skosRelationToShard, skosSchemeToShard, suggestTags, tagsToShard, templateToShard, titleGenerationHandler, unpackTarGz, unregisterLlmCapability, unregisterSemanticCapability, upsertRecordStoreRequest, upsertRecordStoreSources, urlLinkToShard, validateAiwgFortemiChunkManifest, validateAiwgFortemiChunkPart, validateAiwgFortemiIndexExport, validateAiwgFortemiIndexExportSchema, validateAiwgFortemiProjectedRecordSchema, validateAiwgStaticEmbeddingSet, validateChecksums, validateCoreV1ShardArchive, validateDatasetBenchmarkEvidence, validateDatasetExecutionDescriptor, validateFortemiCompatibilityResponse, validateFullV1ShardArchive, validateProviderRoute, validateRecordV1ShardArchive, validateShardArchive, validateShardComponentRecord, validateShardManifest, verifyDbSnapshotMeta, verifyShardSignature, verifySri };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map