@fortemi/core 2026.7.15 → 2026.9.0

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 {
@@ -926,6 +1993,85 @@ var migration0022 = {
   `
 };
 
+// src/migrations/0023_source_metadata_purge.ts
+var migration0023 = {
+  version: 23,
+  name: "0023_source_metadata_purge",
+  sql: `
+    CREATE TABLE IF NOT EXISTS source_identity (
+      id TEXT PRIMARY KEY,
+      tenant_id TEXT NOT NULL DEFAULT 'default',
+      archive_id TEXT,
+      namespace TEXT NOT NULL,
+      external_id TEXT NOT NULL,
+      external_id_hash TEXT NOT NULL,
+      source_schema_version TEXT NOT NULL,
+      content_digest TEXT NOT NULL,
+      import_run_id TEXT NOT NULL,
+      caller_stable_id TEXT,
+      note_id TEXT NOT NULL REFERENCES note(id) ON DELETE CASCADE,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      UNIQUE (tenant_id, archive_id, namespace, external_id)
+    );
+
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_source_identity_scope_key
+      ON source_identity(tenant_id, COALESCE(archive_id, ''), namespace, external_id);
+    CREATE INDEX IF NOT EXISTS idx_source_identity_note ON source_identity(note_id);
+    CREATE INDEX IF NOT EXISTS idx_source_identity_import_run ON source_identity(import_run_id);
+    CREATE INDEX IF NOT EXISTS idx_source_identity_hash ON source_identity(external_id_hash);
+
+    CREATE TABLE IF NOT EXISTS source_import_run (
+      id TEXT PRIMARY KEY,
+      tenant_id TEXT NOT NULL DEFAULT 'default',
+      archive_id TEXT,
+      namespace TEXT NOT NULL,
+      started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      completed_at TIMESTAMPTZ,
+      checkpoint JSONB NOT NULL DEFAULT '{}',
+      receipt JSONB NOT NULL DEFAULT '{}'
+    );
+
+    CREATE TABLE IF NOT EXISTS metadata_index_path (
+      path TEXT PRIMARY KEY,
+      value_type TEXT NOT NULL,
+      indexed_at TIMESTAMPTZ NOT NULL DEFAULT now()
+    );
+
+    INSERT INTO metadata_index_path (path, value_type) VALUES
+      ('provider', 'string'),
+      ('model', 'string'),
+      ('role', 'string'),
+      ('event_kind', 'string'),
+      ('sensitivity', 'string'),
+      ('import_run_id', 'string')
+    ON CONFLICT (path) DO NOTHING;
+
+    CREATE INDEX IF NOT EXISTS idx_note_metadata_provider
+      ON note_revised_current ((ai_metadata ->> 'provider'));
+    CREATE INDEX IF NOT EXISTS idx_note_metadata_model
+      ON note_revised_current ((ai_metadata ->> 'model'));
+    CREATE INDEX IF NOT EXISTS idx_note_metadata_role
+      ON note_revised_current ((ai_metadata ->> 'role'));
+    CREATE INDEX IF NOT EXISTS idx_note_metadata_event_kind
+      ON note_revised_current ((ai_metadata ->> 'event_kind'));
+    CREATE INDEX IF NOT EXISTS idx_note_metadata_sensitivity
+      ON note_revised_current ((ai_metadata ->> 'sensitivity'));
+
+    CREATE TABLE IF NOT EXISTS deletion_receipt (
+      id TEXT PRIMARY KEY,
+      operation_key TEXT NOT NULL UNIQUE,
+      tenant_id TEXT NOT NULL DEFAULT 'default',
+      archive_id TEXT,
+      selector_hash TEXT NOT NULL,
+      outcome TEXT NOT NULL,
+      counts JSONB NOT NULL,
+      completed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      policy JSONB NOT NULL DEFAULT '{}'
+    );
+  `
+};
+
 // src/migrations/index.ts
 var allMigrations = [
   migration0001,
@@ -949,7 +2095,8 @@ var allMigrations = [
   migration0019,
   migration0020,
   migration0021,
-  migration0022
+  migration0022,
+  migration0023
 ];
 
 // src/data-archive.ts
@@ -1055,13 +2202,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 {
@@ -1732,7 +2872,7 @@ var EmbeddingSetsRepository = class {
     const set = await this.get(setId);
     if (set.kind !== "virtual") throw new Error(`Embedding set is not virtual: ${setId}`);
     const definition = this.definitionFromRow(set);
-    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const now2 = (/* @__PURE__ */ new Date()).toISOString();
     const materialization = definition.materialization ? { ...definition.materialization, freshness: "stale" } : null;
     await this.db.query(
       `UPDATE embedding_set
@@ -1741,7 +2881,7 @@ var EmbeddingSetsRepository = class {
       [
         setId,
         jsonParam(materialization),
-        jsonParam({ status: "stale", sourceHash: definition.materialization?.inputHash, checkedAt: now, reason })
+        jsonParam({ status: "stale", sourceHash: definition.materialization?.inputHash, checkedAt: now2, reason })
       ]
     );
   }
@@ -2004,6 +3144,90 @@ var EmbeddingSetsRepository = class {
   }
 };
 
+// src/repositories/metadata-predicates.ts
+var REGISTERED_METADATA_PATHS = [
+  "provider",
+  "model",
+  "role",
+  "event_kind",
+  "sensitivity",
+  "import_run_id"
+];
+var REGISTERED_SET = new Set(REGISTERED_METADATA_PATHS);
+var MAX_PREDICATES = 8;
+var MAX_IN_VALUES = 32;
+var MAX_VALUE_LENGTH = 256;
+function assertRegisteredPath(path) {
+  if (!REGISTERED_SET.has(path) || path.includes(".") || path.includes("/")) {
+    throw new Error(`Unsupported metadata predicate path: ${path}`);
+  }
+}
+function assertBoundedValue(value) {
+  if (typeof value === "string" && value.length > MAX_VALUE_LENGTH) {
+    throw new Error("Metadata predicate value exceeds the 256 character bound");
+  }
+}
+function jsonAccessor(path) {
+  if (path === "import_run_id") return "si.import_run_id";
+  return `c.ai_metadata ->> '${path}'`;
+}
+function buildMetadataPredicateConditions(options, startIdx) {
+  const predicates = options.metadataPredicates ?? [];
+  if (predicates.length > MAX_PREDICATES) {
+    throw new Error(`Metadata predicate count exceeds the ${MAX_PREDICATES} predicate bound`);
+  }
+  const conditions = [];
+  const params = [];
+  const joins = [];
+  let idx = startIdx;
+  let needsSourceJoin = options.tenant_id !== void 0 || options.archive_id !== void 0;
+  if (options.tenant_id !== void 0) {
+    conditions.push(`COALESCE(si.tenant_id, 'default') = $${idx++}`);
+    params.push(options.tenant_id);
+  }
+  if (options.archive_id !== void 0) {
+    conditions.push(`si.archive_id IS NOT DISTINCT FROM $${idx++}`);
+    params.push(options.archive_id);
+  }
+  for (const predicate of predicates) {
+    assertRegisteredPath(predicate.path);
+    const lhs = jsonAccessor(predicate.path);
+    if (predicate.path === "import_run_id") needsSourceJoin = true;
+    if (predicate.op === "eq") {
+      assertBoundedValue(predicate.value);
+      conditions.push(`${lhs} IS NOT DISTINCT FROM $${idx++}`);
+      params.push(predicate.value == null ? null : String(predicate.value));
+    } else if (predicate.op === "in") {
+      if (predicate.value.length > MAX_IN_VALUES) {
+        throw new Error(`Metadata predicate membership exceeds the ${MAX_IN_VALUES} value bound`);
+      }
+      for (const value of predicate.value) assertBoundedValue(value);
+      conditions.push(`${lhs} = ANY($${idx++})`);
+      params.push(predicate.value.map((value) => value == null ? null : String(value)));
+    } else if (predicate.op === "range") {
+      if (predicate.gte === void 0 && predicate.lte === void 0) {
+        throw new Error("Metadata range predicate requires gte or lte");
+      }
+      if (predicate.gte !== void 0) {
+        assertBoundedValue(predicate.gte);
+        conditions.push(`${lhs} >= $${idx++}`);
+        params.push(String(predicate.gte));
+      }
+      if (predicate.lte !== void 0) {
+        assertBoundedValue(predicate.lte);
+        conditions.push(`${lhs} <= $${idx++}`);
+        params.push(String(predicate.lte));
+      }
+    } else {
+      conditions.push(predicate.value === false ? `${lhs} IS NULL` : `${lhs} IS NOT NULL`);
+    }
+  }
+  if (needsSourceJoin) {
+    joins.push("LEFT JOIN source_identity si ON si.note_id = n.id");
+  }
+  return { conditions, joins, params, nextIdx: idx };
+}
+
 // src/repositories/search-repository.ts
 var ATTACHMENT_TEXT_JOIN2 = `
        LEFT JOIN (
@@ -2072,6 +3296,41 @@ var SearchRepository = class {
   attachEmbeddingStatus(results, embeddingSet) {
     return results.map((r) => ({ ...r, has_embedding: embeddingSet.has(r.id) }));
   }
+  async fetchLocatorMap(noteIds, metadataPaths = []) {
+    const locators = /* @__PURE__ */ new Map();
+    if (noteIds.length === 0) return locators;
+    const result = await this.db.query(
+      `SELECT note_id, namespace, external_id_hash, import_run_id, source_schema_version
+       FROM source_identity
+       WHERE note_id = ANY($1)
+       ORDER BY created_at ASC`,
+      [noteIds]
+    );
+    for (const row of result.rows) {
+      const existing = locators.get(row.note_id) ?? [];
+      existing.push({
+        note_id: row.note_id,
+        chunk: { kind: "current", index: 0 },
+        source: {
+          namespace: row.namespace,
+          external_id_hash: row.external_id_hash,
+          import_run_id: row.import_run_id,
+          schema_version: row.source_schema_version
+        },
+        metadata_paths: [...metadataPaths]
+      });
+      locators.set(row.note_id, existing);
+    }
+    for (const noteId of noteIds) {
+      if (!locators.has(noteId)) {
+        locators.set(noteId, [{ note_id: noteId, chunk: { kind: "current", index: 0 }, metadata_paths: [...metadataPaths] }]);
+      }
+    }
+    return locators;
+  }
+  metadataPaths(options) {
+    return [...new Set((options.metadataPredicates ?? []).map((predicate) => predicate.path))];
+  }
   async search(query, options = {}, queryEmbedding) {
     const { limit = 20, offset = 0 } = options;
     const mode = options.mode ?? "auto";
@@ -2098,17 +3357,21 @@ var SearchRepository = class {
     const resolvedEmbeddingSet = await this.resolveEmbeddingSet(options);
     const tsqFn = this.tsqueryFn(query);
     const { conditions, params, nextIdx } = buildNoteConditions(options, 2);
+    const metadata = buildMetadataPredicateConditions(options, nextIdx);
+    conditions.push(...metadata.conditions);
+    params.push(...metadata.params);
     conditions.unshift(
       `(n.tsv @@ ${tsqFn}('english', $1) OR
         ${COMBINED_TEXT_VECTOR_SQL2} @@ ${tsqFn}('english', $1))`
     );
-    let paramIdx = this.scopeToResolvedEmbeddingSet(conditions, params, nextIdx, resolvedEmbeddingSet);
+    let paramIdx = this.scopeToResolvedEmbeddingSet(conditions, params, metadata.nextIdx, resolvedEmbeddingSet);
     const allParams = [query, ...params];
     const where = conditions.join(" AND ");
     const countResult = await this.db.query(
       `SELECT COUNT(*) as count
        FROM note n
        LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${metadata.joins.join("\n")}
        ${ATTACHMENT_TEXT_JOIN2}
        WHERE ${where}`,
       allParams
@@ -2129,6 +3392,7 @@ var SearchRepository = class {
               ) as snippet
        FROM note n
        LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${metadata.joins.join("\n")}
        ${ATTACHMENT_TEXT_JOIN2}
        WHERE ${where}
        ORDER BY rank DESC, n.created_at DESC
@@ -2145,12 +3409,14 @@ var SearchRepository = class {
       const idsResult = await this.db.query(
         `SELECT n.id FROM note n
          LEFT JOIN note_revised_current c ON c.note_id = n.id
+         ${metadata.joins.join("\n")}
          ${ATTACHMENT_TEXT_JOIN2}
          WHERE ${where}`,
         allParams
       );
       facets = await this.fetchFacets(idsResult.rows.map((r) => r.id));
     }
+    const locatorMap = await this.fetchLocatorMap(resultIds, this.metadataPaths(options));
     const baseResults = result.rows.map((r) => ({
       id: r.id,
       title: r.title,
@@ -2158,7 +3424,8 @@ var SearchRepository = class {
       rank: r.rank,
       created_at: r.created_at,
       updated_at: r.updated_at,
-      tags: tagMap.get(r.id) ?? []
+      tags: tagMap.get(r.id) ?? [],
+      locators: locatorMap.get(r.id) ?? []
     }));
     return {
       results: this.attachEmbeddingStatus(baseResults, embeddingSet),
@@ -2176,12 +3443,17 @@ var SearchRepository = class {
     const vectorStr = `[${queryEmbedding.join(",")}]`;
     const resolvedEmbeddingSet = await this.resolveEmbeddingSet(options);
     const { conditions, params, nextIdx } = buildNoteConditions(options, 1);
-    let paramIdx = this.scopeToResolvedEmbeddingRows(conditions, params, nextIdx, resolvedEmbeddingSet);
+    const metadata = buildMetadataPredicateConditions(options, nextIdx);
+    conditions.push(...metadata.conditions);
+    params.push(...metadata.params);
+    let paramIdx = this.scopeToResolvedEmbeddingRows(conditions, params, metadata.nextIdx, resolvedEmbeddingSet);
     const where = conditions.join(" AND ");
     const countResult = await this.db.query(
       `SELECT COUNT(*) as count
        FROM embedding e
        JOIN note n ON n.id = e.note_id
+       LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${metadata.joins.join("\n")}
        WHERE ${where}`,
       params
     );
@@ -2196,6 +3468,7 @@ var SearchRepository = class {
        FROM embedding e
        JOIN note n ON n.id = e.note_id
        LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${metadata.joins.join("\n")}
        ${ATTACHMENT_TEXT_JOIN2}
        WHERE ${where}
        ORDER BY e.vector <=> $${vecIdx}::vector ASC
@@ -2204,9 +3477,15 @@ var SearchRepository = class {
     );
     const tagMap = await this.fetchTagMap(result.rows.map((r) => r.id));
     const facets = options.include_facets ? await this.fetchFacets((await this.db.query(
-      `SELECT n.id FROM embedding e JOIN note n ON n.id = e.note_id WHERE ${where}`,
+      `SELECT n.id
+           FROM embedding e
+           JOIN note n ON n.id = e.note_id
+           LEFT JOIN note_revised_current c ON c.note_id = n.id
+           ${metadata.joins.join("\n")}
+           WHERE ${where}`,
       params
     )).rows.map((r) => r.id)) : void 0;
+    const locatorMap = await this.fetchLocatorMap(result.rows.map((r) => r.id), this.metadataPaths(options));
     return {
       results: result.rows.map((r) => ({
         id: r.id,
@@ -2216,7 +3495,8 @@ var SearchRepository = class {
         created_at: r.created_at,
         updated_at: r.updated_at,
         tags: tagMap.get(r.id) ?? [],
-        has_embedding: true
+        has_embedding: true,
+        locators: locatorMap.get(r.id) ?? []
       })),
       total,
       query: "",
@@ -2234,12 +3514,15 @@ var SearchRepository = class {
     const tsqFn = this.tsqueryFn(query);
     const resolvedEmbeddingSet = await this.resolveEmbeddingSet(options);
     const textCond = buildNoteConditions(options, 2);
+    const textMeta = buildMetadataPredicateConditions(options, textCond.nextIdx);
     const textConditions = [
       ...textCond.conditions,
+      ...textMeta.conditions,
       `(n.tsv @@ ${tsqFn}('english', $1) OR
         ${COMBINED_TEXT_VECTOR_SQL2} @@ ${tsqFn}('english', $1))`
     ];
-    this.scopeToResolvedEmbeddingSet(textConditions, textCond.params, textCond.nextIdx, resolvedEmbeddingSet);
+    textCond.params.push(...textMeta.params);
+    this.scopeToResolvedEmbeddingSet(textConditions, textCond.params, textMeta.nextIdx, resolvedEmbeddingSet);
     const textWhere = textConditions.join(" AND ");
     const textParams = [query, ...textCond.params];
     const textResult = await this.db.query(
@@ -2250,6 +3533,7 @@ var SearchRepository = class {
               ) as rank
        FROM note n
        LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${textMeta.joins.join("\n")}
        ${ATTACHMENT_TEXT_JOIN2}
        WHERE ${textWhere}
        ORDER BY rank DESC
@@ -2257,13 +3541,18 @@ var SearchRepository = class {
       textParams
     );
     const vecCond = buildNoteConditions(options, 1);
-    vecCond.nextIdx = this.scopeToResolvedEmbeddingRows(vecCond.conditions, vecCond.params, vecCond.nextIdx, resolvedEmbeddingSet);
+    const vecMeta = buildMetadataPredicateConditions(options, vecCond.nextIdx);
+    vecCond.conditions.push(...vecMeta.conditions);
+    vecCond.params.push(...vecMeta.params);
+    vecCond.nextIdx = this.scopeToResolvedEmbeddingRows(vecCond.conditions, vecCond.params, vecMeta.nextIdx, resolvedEmbeddingSet);
     const vecWhere = vecCond.conditions.join(" AND ");
     const vecVecIdx = vecCond.nextIdx;
     const vectorResult = await this.db.query(
       `SELECT n.id, (e.vector <=> $${vecVecIdx}::vector) as distance
        FROM embedding e
        JOIN note n ON n.id = e.note_id
+       LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${vecMeta.joins.join("\n")}
        WHERE ${vecWhere}
        ORDER BY e.vector <=> $${vecVecIdx}::vector ASC
        LIMIT 100`,
@@ -2296,6 +3585,7 @@ var SearchRepository = class {
       this.fetchTagMap(pageIds),
       this.fetchEmbeddingStatus(pageIds, resolvedEmbeddingSet, options.embeddingSetId)
     ]);
+    const locatorMap = await this.fetchLocatorMap(pageIds, this.metadataPaths(options));
     const facets = options.include_facets ? await this.fetchFacets(sortedIds) : void 0;
     return {
       results: pageIds.map((id) => {
@@ -2309,7 +3599,8 @@ var SearchRepository = class {
           created_at: r.created_at,
           updated_at: r.updated_at,
           tags: tagMap.get(id) ?? [],
-          has_embedding: embeddingSet.has(id)
+          has_embedding: embeddingSet.has(id),
+          locators: locatorMap.get(id) ?? []
         };
       }).filter((r) => r !== null),
       total,
@@ -2325,10 +3616,17 @@ var SearchRepository = class {
     const { limit = 20, offset = 0 } = options;
     const resolvedEmbeddingSet = await this.resolveEmbeddingSet(options);
     const { conditions, params, nextIdx } = buildNoteConditions(options, 1);
-    let paramIdx = this.scopeToResolvedEmbeddingSet(conditions, params, nextIdx, resolvedEmbeddingSet);
+    const metadata = buildMetadataPredicateConditions(options, nextIdx);
+    conditions.push(...metadata.conditions);
+    params.push(...metadata.params);
+    let paramIdx = this.scopeToResolvedEmbeddingSet(conditions, params, metadata.nextIdx, resolvedEmbeddingSet);
     const where = conditions.join(" AND ");
     const countResult = await this.db.query(
-      `SELECT COUNT(*) as count FROM note n WHERE ${where}`,
+      `SELECT COUNT(*) as count
+       FROM note n
+       LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${metadata.joins.join("\n")}
+       WHERE ${where}`,
       params
     );
     const total = parseInt(countResult.rows[0].count, 10);
@@ -2338,6 +3636,7 @@ var SearchRepository = class {
               LEFT(${COMBINED_TEXT_SQL}, 200) as snippet
        FROM note n
        LEFT JOIN note_revised_current c ON c.note_id = n.id
+       ${metadata.joins.join("\n")}
        ${ATTACHMENT_TEXT_JOIN2}
        WHERE ${where}
        ORDER BY n.created_at DESC
@@ -2346,6 +3645,7 @@ var SearchRepository = class {
     );
     const resultIds = result.rows.map((r) => r.id);
     const embeddingSet = await this.fetchEmbeddingStatus(resultIds, resolvedEmbeddingSet, options.embeddingSetId);
+    const locatorMap = await this.fetchLocatorMap(resultIds, this.metadataPaths(options));
     return {
       results: result.rows.map((r) => ({
         id: r.id,
@@ -2355,7 +3655,8 @@ var SearchRepository = class {
         created_at: r.created_at,
         updated_at: r.updated_at,
         tags: [],
-        has_embedding: embeddingSet.has(r.id)
+        has_embedding: embeddingSet.has(r.id),
+        locators: locatorMap.get(r.id) ?? []
       })),
       total,
       query: "",
@@ -3945,8 +5246,8 @@ async function migrateLegacyBlobStore(archiveName, target, indexedDbFactory) {
 
 // src/blob-store.ts
 var MemoryBlobStore = class {
-  constructor(now = Date.now) {
-    this.now = now;
+  constructor(now2 = Date.now) {
+    this.now = now2;
   }
   entries = /* @__PURE__ */ new Map();
   async put(bytes) {
@@ -4019,12 +5320,12 @@ function toChecksum(hex) {
   return CHECKSUM_PREFIX + hex;
 }
 var BytecaskBlobStore = class {
-  constructor(facade, adapter, index, probe, now = Date.now) {
+  constructor(facade, adapter, index, probe, now2 = Date.now) {
     this.facade = facade;
     this.adapter = adapter;
     this.index = index;
     this.probe = probe;
-    this.now = now;
+    this.now = now2;
   }
   async put(bytes) {
     return toChecksum(await this.facade.put(bytes));
@@ -4159,6 +5460,482 @@ function createLazyBlobStore(archiveName, options) {
   };
 }
 
+// src/repositories/source-upsert-repository.ts
+var DEFAULT_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");
+}
+function sourceHash(source) {
+  return computeHash(new TextEncoder().encode([
+    source.tenant_id ?? "default",
+    source.archive_id ?? "",
+    source.namespace,
+    source.external_id
+  ].join("\0")));
+}
+function contentDigest(content) {
+  return computeHash(new TextEncoder().encode(content));
+}
+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 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"
+    ]
+  );
+  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_revised_current (note_id, content, ai_metadata)
+     VALUES ($1, $2, $3::jsonb)`,
+    [noteId, input.content, JSON.stringify(input.metadata ?? null)]
+  );
+}
+async function updateNote(tx, input, noteId, outcome) {
+  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]
+    );
+  }
+  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 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)
+        ]
+      );
+    }
+  }
+  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
+    ]
+  );
+  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`,
+    [input.content, JSON.stringify(input.metadata ?? null), noteId]
+  );
+}
+var SourceUpsertRepository = class {
+  constructor(db, events) {
+    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)
+        });
+      }
+    }
+    if (outcomes.some((outcome) => outcome.reason)) {
+      return this.finish(items[0].source?.import_run_id ?? "", options.dryRun === true, outcomes);
+    }
+    if (options.dryRun) {
+      const preview = [];
+      for (const [index, item] of items.entries()) {
+        const externalIdHash = sourceHash(item.source);
+        const digest2 = 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: digest2 });
+        } else if (existing.rows[0].content_digest === digest2) {
+          preview.push({ index, outcome: "unchanged", note_id: existing.rows[0].note_id, external_id_hash: externalIdHash, content_digest: digest2 });
+        } else if ((item.policy ?? "version") === "conflict") {
+          preview.push({ index, outcome: "conflict", note_id: existing.rows[0].note_id, external_id_hash: externalIdHash, content_digest: digest2 });
+        } else {
+          preview.push({
+            index,
+            outcome: item.policy === "replace" ? "replaced" : "versioned",
+            note_id: existing.rows[0].note_id,
+            external_id_hash: externalIdHash,
+            content_digest: digest2
+          });
+        }
+      }
+      return this.finish(items[0].source.import_run_id, true, preview);
+    }
+    await this.db.transaction(async (tx) => {
+      for (const [index, item] of items.entries()) {
+        const externalIdHash = sourceHash(item.source);
+        const digest2 = 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 noteId = item.source.caller_stable_id ?? generateId();
+          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,
+              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: digest2 };
+          continue;
+        }
+        const row = existing.rows[0];
+        if (row.content_digest === digest2) {
+          outcomes[index] = { index, outcome: "unchanged", note_id: row.note_id, external_id_hash: externalIdHash, content_digest: digest2 };
+          continue;
+        }
+        const policy = item.policy ?? "version";
+        if (policy === "conflict") {
+          outcomes[index] = { index, outcome: "conflict", note_id: row.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 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,
+            digest2,
+            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: digest2 };
+      }
+      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) })
+          ]
+        );
+      }
+    });
+    if (hasMaterialChange(outcomes)) {
+      this.events?.emit("source.upserted", { importRunId: items[0].source.import_run_id, counts: countOutcomes(outcomes) });
+    }
+    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) };
+  }
+};
+function hasMaterialChange(outcomes) {
+  return outcomes.some((outcome) => outcome.outcome === "inserted" || outcome.outcome === "versioned" || outcome.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
+  };
+}
+
+// src/repositories/lifecycle-purge-repository.ts
+function zeroCounts() {
+  return {
+    notes: 0,
+    revisions: 0,
+    links: 0,
+    tags: 0,
+    embeddings: 0,
+    attachments: 0,
+    blobs: 0,
+    graph_edges: 0,
+    provenance_edges: 0,
+    source_identities: 0
+  };
+}
+function selectorHash(selector) {
+  return computeHash(new TextEncoder().encode(JSON.stringify({
+    tenant_id: selector.tenant_id ?? "default",
+    archive_id: selector.archive_id ?? null,
+    note_ids: [...selector.note_ids ?? []].sort(),
+    source: selector.source ? {
+      namespace: selector.source.namespace,
+      external_id_hash: selector.source.external_id ? computeHash(new TextEncoder().encode(selector.source.external_id)) : null
+    } : null
+  })));
+}
+function buildSelectorWhere(selector, startIdx) {
+  const clauses = [];
+  const params = [];
+  let idx = startIdx;
+  if (selector.note_ids?.length) {
+    clauses.push(`n.id = ANY($${idx++})`);
+    params.push([...selector.note_ids]);
+  }
+  if (selector.tenant_id !== void 0 || selector.archive_id !== void 0 || selector.source) {
+    clauses.push(`EXISTS (
+      SELECT 1 FROM source_identity si
+      WHERE si.note_id = n.id
+        AND si.tenant_id = $${idx++}
+        AND si.archive_id IS NOT DISTINCT FROM $${idx++}
+        ${selector.source ? `AND si.namespace = $${idx++}` : ""}
+        ${selector.source?.external_id ? `AND si.external_id = $${idx++}` : ""}
+    )`);
+    params.push(selector.tenant_id ?? "default", selector.archive_id ?? null);
+    if (selector.source) params.push(selector.source.namespace);
+    if (selector.source?.external_id) params.push(selector.source.external_id);
+  }
+  if (clauses.length === 0) throw new Error("Purge selector must target note_ids or source identity");
+  return { sql: clauses.join(" AND "), params };
+}
+async function selectedNoteIds(db, selector) {
+  const where = buildSelectorWhere(selector, 1);
+  const result = await db.query(
+    `SELECT n.id FROM note n WHERE ${where.sql} ORDER BY n.id`,
+    where.params
+  );
+  return result.rows.map((row) => row.id);
+}
+var LifecyclePurgeRepository = class {
+  constructor(db, events) {
+    this.db = db;
+    this.events = events;
+  }
+  async preview(selector) {
+    const noteIds = await selectedNoteIds(this.db, selector);
+    return { selector_hash: selectorHash(selector), counts: await this.count(noteIds) };
+  }
+  async purge(selector, operationKey) {
+    const existing = await this.db.query(
+      `SELECT id, operation_key, tenant_id, archive_id, selector_hash, outcome, counts, completed_at, policy
+       FROM deletion_receipt
+       WHERE operation_key = $1`,
+      [operationKey]
+    );
+    if (existing.rows[0]) return existing.rows[0];
+    const hash = selectorHash(selector);
+    let receipt;
+    await this.db.transaction(async (tx) => {
+      const noteIds = await selectedNoteIds(tx, selector);
+      const counts = await this.count(noteIds, tx);
+      await this.deleteSelected(tx, noteIds);
+      receipt = {
+        id: generateId(),
+        operation_key: operationKey,
+        tenant_id: selector.tenant_id ?? "default",
+        archive_id: selector.archive_id ?? null,
+        selector_hash: hash,
+        outcome: "completed",
+        counts,
+        completed_at: (/* @__PURE__ */ new Date()).toISOString(),
+        policy: {
+          authority: "fortemi#1092",
+          mode: "terminal-purge",
+          receipt_contains_content: false
+        }
+      };
+      await tx.query(
+        `INSERT INTO deletion_receipt
+          (id, operation_key, tenant_id, archive_id, selector_hash, outcome, counts, completed_at, policy)
+         VALUES ($1, $2, $3, $4, $5, 'completed', $6::jsonb, $7, $8::jsonb)`,
+        [
+          receipt.id,
+          receipt.operation_key,
+          receipt.tenant_id,
+          receipt.archive_id,
+          receipt.selector_hash,
+          JSON.stringify(receipt.counts),
+          receipt.completed_at,
+          JSON.stringify(receipt.policy)
+        ]
+      );
+    });
+    const completedReceipt = receipt;
+    if (!completedReceipt) throw new Error("Purge transaction did not produce a receipt");
+    this.events?.emit("purge.completed", { receiptId: completedReceipt.id, counts: completedReceipt.counts });
+    return completedReceipt;
+  }
+  async count(noteIds, db = this.db) {
+    const counts = zeroCounts();
+    if (noteIds.length === 0) return counts;
+    const params = [noteIds];
+    const rows = await Promise.all([
+      db.query("SELECT COUNT(*) AS count FROM note WHERE id = ANY($1)", params),
+      db.query("SELECT COUNT(*) AS count FROM note_revision WHERE note_id = ANY($1)", params),
+      db.query("SELECT COUNT(*) AS count FROM link WHERE source_note_id = ANY($1) OR target_note_id = ANY($1)", params),
+      db.query("SELECT COUNT(*) AS count FROM note_tag WHERE note_id = ANY($1)", params),
+      db.query("SELECT COUNT(*) AS count FROM embedding WHERE note_id = ANY($1)", params),
+      db.query("SELECT COUNT(*) AS count FROM attachment WHERE note_id = ANY($1)", params),
+      db.query(
+        `SELECT COUNT(*) AS count FROM attachment_blob ab
+         WHERE EXISTS (SELECT 1 FROM attachment a WHERE a.blob_id = ab.id AND a.note_id = ANY($1))`,
+        params
+      ),
+      db.query("SELECT COUNT(*) AS count FROM graph_edge_artifact WHERE from_note_id = ANY($1) OR to_note_id = ANY($1)", params),
+      db.query(
+        `SELECT COUNT(*) AS count FROM provenance_edge
+         WHERE (entity_type = 'note' AND entity_id = ANY($1))
+            OR (attributes ->> 'note_id') = ANY($1)`,
+        params
+      ),
+      db.query("SELECT COUNT(*) AS count FROM source_identity WHERE note_id = ANY($1)", params)
+    ]);
+    const values = rows.map((row) => Number.parseInt(row.rows[0]?.count ?? "0", 10));
+    [
+      counts.notes,
+      counts.revisions,
+      counts.links,
+      counts.tags,
+      counts.embeddings,
+      counts.attachments,
+      counts.blobs,
+      counts.graph_edges,
+      counts.provenance_edges,
+      counts.source_identities
+    ] = values;
+    return counts;
+  }
+  async deleteSelected(tx, noteIds) {
+    if (noteIds.length === 0) return;
+    const params = [noteIds];
+    await tx.query("DELETE FROM community_assignment WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM graph_edge_artifact WHERE from_note_id = ANY($1) OR to_note_id = ANY($1)", params);
+    await tx.query("DELETE FROM embedding_set_member WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM embedding WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM attachment_embedding WHERE attachment_id IN (SELECT id FROM attachment WHERE note_id = ANY($1))", params);
+    await tx.query("DELETE FROM attachment WHERE note_id = ANY($1)", params);
+    await tx.query(
+      `DELETE FROM attachment_blob ab
+       WHERE NOT EXISTS (SELECT 1 FROM attachment a WHERE a.blob_id = ab.id)`
+    );
+    await tx.query("DELETE FROM source_identity WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM provenance_edge WHERE (entity_type = $2 AND entity_id = ANY($1)) OR (attributes ->> $3) = ANY($1)", [noteIds, "note", "note_id"]);
+    await tx.query("DELETE FROM job_queue WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM collection_note WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM note_tag WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM link WHERE source_note_id = ANY($1) OR target_note_id = ANY($1)", params);
+    await tx.query("DELETE FROM note_revision WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM note_revised_current WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM note_original WHERE note_id = ANY($1)", params);
+    await tx.query("DELETE FROM shard_field_presence WHERE component = $2 AND record_id = ANY($1)", [noteIds, "notes"]);
+    await tx.query("DELETE FROM note WHERE id = ANY($1)", params);
+  }
+};
+
 // src/repositories/graph-repository.ts
 var SIMILARITY_GRAPH_ALGORITHM = "knn-batched-v1";
 var DEFAULT_GRAPH_BATCH_SIZE = 64;
@@ -4874,7 +6651,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(
@@ -4915,7 +6692,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`,
@@ -4956,7 +6733,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;
@@ -6239,10 +8016,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;
 }
@@ -6268,7 +8059,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();
@@ -6277,7 +8069,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
@@ -6436,6 +8228,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) {
@@ -6443,6 +8455,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)) {
@@ -6480,6 +8493,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;
@@ -6511,27 +8554,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() {
@@ -6553,29 +8620,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,
@@ -6585,14 +8980,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() {
@@ -6608,6 +9000,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 {
@@ -6615,6 +9115,7 @@ var OpenAICompatibleProvider = class {
   name;
   tier;
   capabilities;
+  profile;
   baseURL;
   apiKey;
   defaultModel;
@@ -6640,6 +9141,7 @@ var OpenAICompatibleProvider = class {
       toolCalling: false,
       structuredOutput: false
     };
+    this.profile = config.profile ?? (this.tier === "local-server" ? { privacyTier: "local", costTier: "free" } : { privacyTier: "external" });
   }
   // -------------------------------------------------------------------------
   // InferenceProvider interface
@@ -6734,15 +9236,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 [];
     }
@@ -6790,10 +9296,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);
@@ -6834,299 +9336,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";
+// 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
+  };
 }
-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
+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"
     };
-  } 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";
-}
-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 now = Date.now();
-    return this.providers.filter((p) => {
-      const cd = this.cooldownMap.get(p.id);
-      if (!cd) return true;
-      if (now >= cd.expiresAt) {
-        this.cooldownMap.delete(p.id);
-        return true;
-      }
-      return false;
-    });
-  }
-  /** Get providers in cooldown with their expiry info */
-  getCoolingDown() {
-    const now = Date.now();
-    const result = [];
-    for (const [id, entry] of this.cooldownMap) {
-      if (now < 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) {
@@ -7155,6 +9435,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'"],
@@ -7196,12 +9629,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);
@@ -7218,8 +9651,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);
@@ -8251,12 +10684,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) };
@@ -8301,11 +10734,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,
@@ -26850,7 +29283,7 @@ function addCanonicalFormats(ajv) {
 }
 function getLegacyAjv() {
   if (!legacyAjvInstance) {
-    legacyAjvInstance = new Ajv2020({
+    legacyAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: false
@@ -26861,7 +29294,7 @@ function getLegacyAjv() {
 }
 function getCoreAjv() {
   if (!coreAjvInstance) {
-    coreAjvInstance = new Ajv2020({
+    coreAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: true
@@ -26881,7 +29314,7 @@ function getCoreAjv() {
 }
 function getRecordAjv() {
   if (!recordAjvInstance) {
-    recordAjvInstance = new Ajv2020({
+    recordAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: true
@@ -26901,7 +29334,7 @@ function getRecordAjv() {
 }
 function getFullAjv() {
   if (!fullAjvInstance) {
-    fullAjvInstance = new Ajv2020({
+    fullAjvInstance = new Ajv20202({
       allErrors: true,
       strict: true,
       validateFormats: true
@@ -27561,7 +29994,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,
@@ -27612,15 +30045,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();
@@ -27871,7 +30304,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) {
@@ -27890,7 +30323,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 {
@@ -27914,7 +30347,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;
@@ -27943,7 +30376,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 = [
@@ -27959,13 +30392,13 @@ async function liveRepresentationLosses(db) {
     const result = await db.query(
       `SELECT COUNT(*) AS count FROM ${table} WHERE deleted_at IS NOT NULL`
     );
-    const count = Number(result.rows[0]?.count ?? 0);
-    if (count > 0) {
+    const count2 = Number(result.rows[0]?.count ?? 0);
+    if (count2 > 0) {
       losses.push({
         code: "unrepresentable-live-tombstone",
         component,
-        count,
-        message: `${count} ${table} tombstone(s) have no full-v1 wire field`,
+        count: count2,
+        message: `${count2} ${table} tombstone(s) have no full-v1 wire field`,
         action: "reject",
         reason: "full-v1-live-production"
       });
@@ -27997,15 +30430,15 @@ async function liveRepresentationLosses(db) {
   for (const row of vectorDimensions.rows) {
     const dimension = Number(row.dimension);
     if (dimension === 768) continue;
-    const count = Number(row.count);
+    const count2 = Number(row.count);
     losses.push({
       code: "unrepresentable-live-embedding-dimension",
       component: "embeddings",
-      count,
+      count: count2,
       field_path: "/vector",
       source_state: "value",
       destination_capability: "full-v1 requires exactly 768 vector dimensions",
-      message: `${count} embedding vector(s) have ${dimension} dimensions`,
+      message: `${count2} embedding vector(s) have ${dimension} dimensions`,
       action: "reject",
       reason: "full-v1-live-production"
     });
@@ -28410,7 +30843,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) {
@@ -28455,7 +30888,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",
@@ -28565,16 +30998,27 @@ async function collectCoreV1Losses(db, options) {
     { component: "community_assignments", table: "community_assignment" }
   ];
   for (const { component, table } of componentCounts) {
-    const count = await rowCount(db, `SELECT COUNT(*) AS count FROM ${table}`);
-    if (count > 0) {
+    const count2 = await rowCount(db, `SELECT COUNT(*) AS count FROM ${table}`);
+    if (count2 > 0) {
       losses.push({
         code: "component-outside-profile",
         component,
-        count,
-        message: `${count} ${component} record(s) are outside core-v1 and were omitted.`
+        count: count2,
+        message: `${count2} ${component} record(s) are outside core-v1 and were omitted.`
       });
     }
   }
+  const sourceIdentities = await rowCount(db, "SELECT COUNT(*) AS count FROM source_identity");
+  if (sourceIdentities > 0) {
+    losses.push({
+      code: "source-identity-outside-profile",
+      count: sourceIdentities,
+      field_path: "source_identity",
+      action: "omit",
+      destination_capability: "core-v1 does not declare source-addressed identity mappings",
+      message: `${sourceIdentities} source identity mapping(s) are outside core-v1 and were omitted.`
+    });
+  }
   const nullRevisions = await rowCount(
     db,
     `SELECT COUNT(*) AS count
@@ -28863,11 +31307,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;
@@ -28895,7 +31339,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(
@@ -28911,7 +31355,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`);
@@ -28927,7 +31371,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;
   }
@@ -28952,7 +31396,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`);
@@ -28969,25 +31413,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) {
@@ -29027,7 +31471,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(
@@ -29037,7 +31481,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;
     }
@@ -29050,7 +31494,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(
@@ -29076,7 +31520,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;
   }
@@ -29102,7 +31546,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;
   }
@@ -29118,7 +31562,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;
   }
@@ -29154,7 +31598,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;
@@ -29170,7 +31614,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;
   }
@@ -29193,7 +31637,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];
@@ -29233,7 +31677,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) {
@@ -30718,13 +33162,13 @@ function noteSearchText(note) {
 }
 function countOccurrences(haystack, needle) {
   if (!needle) return 0;
-  let count = 0;
+  let count2 = 0;
   let index = haystack.indexOf(needle);
   while (index !== -1) {
-    count += 1;
+    count2 += 1;
     index = haystack.indexOf(needle, index + needle.length);
   }
-  return count;
+  return count2;
 }
 function noteMatchesTokens(note, tokens) {
   if (tokens.length === 0) return true;
@@ -31202,7 +33646,7 @@ function hasPositiveInteger(value) {
 }
 function isFacetCounts(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
-  return Object.values(value).every((counts) => !!counts && typeof counts === "object" && !Array.isArray(counts) && Object.values(counts).every((count) => hasNonNegativeInteger(count)));
+  return Object.values(value).every((counts) => !!counts && typeof counts === "object" && !Array.isArray(counts) && Object.values(counts).every((count2) => hasNonNegativeInteger(count2)));
 }
 function isPlainRecord(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
@@ -33739,7 +36183,7 @@ function getAiwgFortemiIndexExportSchema() {
 }
 function getAjv() {
   if (!ajvInstance) {
-    ajvInstance = new Ajv2020({
+    ajvInstance = new Ajv20202({
       allErrors: true,
       strict: false,
       validateFormats: false
@@ -33802,7 +36246,7 @@ function validateAiwgFortemiProjectedRecordSchema(value) {
   const valid = validate(value);
   return { valid, errors: formatErrors2(validate.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);
@@ -33818,7 +36262,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;
@@ -33986,7 +36430,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,
@@ -34078,7 +36522,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
     });
@@ -34536,7 +36980,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) {
@@ -34797,13 +37241,20 @@ var RECORD_COLLECTIONS = [
   "collection_note",
   "attachment",
   "attachment_blob",
-  "shard_manifest"
+  "shard_manifest",
+  "source_identity",
+  "source_import_run",
+  "deletion_receipt"
 ];
 var RECORD_STORE_CAPABILITIES = {
   crud: true,
   journal: true,
   atomicBatch: true,
   boundedTextScan: true,
+  sourceAddressedUpsert: true,
+  deletionReceipts: true,
+  typedMetadataPredicates: false,
+  evidenceLocators: true,
   fullTextSearch: false,
   vectorSearch: false,
   sqlJoins: false
@@ -35764,7 +38215,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 {
@@ -35992,7 +38443,7 @@ async function buildRecordShardArchive(store, options, profile) {
     (attachment) => exportedNoteIds.has(attachment.note_id)
   );
   const projectedAttachmentCount = browserNotes.reduce(
-    (count, note) => count + (note.attachments?.length ?? 0),
+    (count2, note) => count2 + (note.attachments?.length ?? 0),
     0
   );
   const sourceNoteById = new Map(notes.map((note) => [note.id, note]));
@@ -36022,11 +38473,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;
@@ -36054,7 +38505,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(
@@ -36071,7 +38522,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");
@@ -36093,7 +38544,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 = {};
@@ -36146,6 +38597,17 @@ async function buildRecordShardArchive(store, options, profile) {
         message: `${collectionStateLosses} collection lifecycle state(s) are outside record-v1 and were omitted.`
       });
     }
+    const sourceIdentities = await store.list("source_identity");
+    if (sourceIdentities.length > 0) {
+      losses.push({
+        code: "source-identity-outside-profile",
+        count: sourceIdentities.length,
+        field_path: "source_identity",
+        action: "omit",
+        destination_capability: "record-v1 does not declare source-addressed identity mappings",
+        message: `${sourceIdentities.length} source identity mapping(s) are outside record-v1 and were omitted.`
+      });
+    }
   }
   let manifest = isRecordV1 ? {
     version: recordSchemaVersion2,
@@ -36212,7 +38674,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) {
@@ -36428,9 +38890,9 @@ async function importShardToRecords(store, data, options) {
   }
   for (const component of manifest.components ?? []) {
     if (UNSUPPORTED_COMPONENTS.includes(component)) {
-      const count = manifest.counts?.[component];
+      const count2 = manifest.counts?.[component];
       const key = component === "communities" ? "communities" : component;
-      skipped[key] = (skipped[key] ?? 0) + (typeof count === "number" ? count : 0);
+      skipped[key] = (skipped[key] ?? 0) + (typeof count2 === "number" ? count2 : 0);
       warnings.push(
         `Shard component '${component}' is not supported by the canonical record tier and was skipped. Import into a PGlite-backed store to preserve it.`
       );
@@ -36598,7 +39060,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 });
@@ -36830,9 +39292,302 @@ async function importShardToRecords(store, data, options) {
   };
 }
 
+// src/records/source-upsert.ts
+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
+  };
+}
+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 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 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 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 }
+        );
+      }
+      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";
+    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 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) }
+    };
+    mutations.push({ op: "put", collection: "source_import_run", record: run });
+    await store.applyBatch(mutations);
+  }
+  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");
+}
+
+// src/records/lifecycle-purge.ts
+function hashSelector(selector) {
+  return computeHash(new TextEncoder().encode(JSON.stringify({
+    tenant_id: selector.tenant_id ?? "default",
+    archive_id: selector.archive_id ?? null,
+    note_ids: [...selector.note_ids ?? []].sort(),
+    source: selector.source ? {
+      namespace: selector.source.namespace,
+      external_id_hash: selector.source.external_id ? computeHash(new TextEncoder().encode(selector.source.external_id)) : null
+    } : null
+  })));
+}
+function zeroCounts2() {
+  return {
+    notes: 0,
+    revisions: 0,
+    links: 0,
+    tags: 0,
+    embeddings: 0,
+    attachments: 0,
+    blobs: 0,
+    graph_edges: 0,
+    provenance_edges: 0,
+    source_identities: 0
+  };
+}
+async function selectedNoteIds2(store, selector) {
+  const notes = await store.list("note");
+  if (selector.note_ids?.length) return notes.filter((note) => selector.note_ids.includes(note.id)).map((note) => note.id);
+  if (!selector.source) throw new Error("Purge selector must target note_ids or source identity");
+  const identities = await store.list("source_identity");
+  return identities.filter((identity) => identity.tenant_id === (selector.tenant_id ?? "default") && identity.archive_id === (selector.archive_id ?? null) && identity.namespace === selector.source.namespace && (selector.source.external_id === void 0 || identity.external_id === selector.source.external_id)).map((identity) => identity.note_id);
+}
+async function count(store, noteIds) {
+  const counts = zeroCounts2();
+  if (noteIds.length === 0) return counts;
+  const noteSet = new Set(noteIds);
+  counts.notes = (await store.list("note")).filter((record) => noteSet.has(record.id)).length;
+  counts.revisions = 0;
+  counts.links = (await store.list("link")).filter((record) => noteSet.has(record.source_note_id) || noteSet.has(record.target_note_id)).length;
+  counts.tags = (await store.list("note_tag")).filter((record) => noteSet.has(record.note_id)).length;
+  counts.attachments = (await store.list("attachment")).filter((record) => noteSet.has(record.note_id)).length;
+  const purgedBlobIds = new Set((await store.list("attachment")).filter((record) => noteSet.has(record.note_id)).map((record) => record.blob_id));
+  counts.blobs = (await store.list("attachment_blob")).filter((record) => purgedBlobIds.has(record.id)).length;
+  counts.source_identities = (await store.list("source_identity")).filter((record) => noteSet.has(record.note_id)).length;
+  return counts;
+}
+async function previewRecordStorePurge(store, selector) {
+  return { selector_hash: hashSelector(selector), counts: await count(store, await selectedNoteIds2(store, selector)) };
+}
+async function purgeRecordStoreGraph(store, selector, operationKey) {
+  if (!store.applyBatch) throw new Error("RecordStore purge requires atomic applyBatch() support");
+  const prior = (await store.list("deletion_receipt")).find((receipt2) => receipt2.operation_key === operationKey);
+  if (prior) return {
+    id: prior.id,
+    operation_key: prior.operation_key,
+    tenant_id: prior.tenant_id,
+    archive_id: prior.archive_id,
+    selector_hash: prior.selector_hash,
+    outcome: "completed",
+    counts: prior.counts,
+    completed_at: prior.completed_at,
+    policy: prior.policy
+  };
+  const noteIds = await selectedNoteIds2(store, selector);
+  const noteSet = new Set(noteIds);
+  const counts = await count(store, noteIds);
+  const mutations = [];
+  for (const collection of ["note_revised_current", "note_original", "note_tag", "collection_note", "attachment", "source_identity"]) {
+    for (const record of await store.list(collection)) {
+      const noteId = collection === "note_revised_current" ? record.id : "note_id" in record && typeof record.note_id === "string" ? record.note_id : null;
+      if (noteId && noteSet.has(noteId)) {
+        mutations.push({ op: "delete", collection, id: record.id });
+      }
+    }
+  }
+  for (const record of await store.list("link")) {
+    if (noteSet.has(record.source_note_id) || noteSet.has(record.target_note_id)) mutations.push({ op: "delete", collection: "link", id: record.id });
+  }
+  for (const record of await store.list("note")) {
+    if (noteSet.has(record.id)) mutations.push({ op: "delete", collection: "note", id: record.id });
+  }
+  const liveBlobIds = new Set((await store.list("attachment")).filter((record) => !noteSet.has(record.note_id)).map((record) => record.blob_id));
+  for (const record of await store.list("attachment_blob")) {
+    if (!liveBlobIds.has(record.id)) mutations.push({ op: "delete", collection: "attachment_blob", id: record.id });
+  }
+  const receipt = {
+    id: generateId(),
+    operation_key: operationKey,
+    tenant_id: selector.tenant_id ?? "default",
+    archive_id: selector.archive_id ?? null,
+    selector_hash: hashSelector(selector),
+    outcome: "completed",
+    counts,
+    completed_at: (/* @__PURE__ */ new Date()).toISOString(),
+    policy: {
+      authority: "fortemi#1092",
+      mode: "terminal-purge",
+      receipt_contains_content: false
+    }
+  };
+  mutations.push({ op: "put", collection: "deletion_receipt", record: receipt });
+  await store.applyBatch(mutations);
+  return {
+    id: receipt.id,
+    operation_key: receipt.operation_key,
+    tenant_id: receipt.tenant_id,
+    archive_id: receipt.archive_id,
+    selector_hash: receipt.selector_hash,
+    outcome: "completed",
+    counts,
+    completed_at: receipt.completed_at,
+    policy: receipt.policy
+  };
+}
+
 // src/index.ts
-var VERSION = "2026.7.15";
+var VERSION = "2026.9.0";
 
-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, 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, SHARD_FORMAT, SIGNATURE_ENTRY, SIGNING_ENVELOPE_VERSION, SUPPORTED_PGLITE_VERSION, SearchInputSchema, SearchRepository, SkosRepository, TagsRepository, TransactionProxy, TypedEventBus, VERSION, aiRevisionHandler, aiwgFortemiIndexFromKnowledgeShard, aiwgFortemiIndexToCommunityGraph, aiwgFortemiIndexToKnowledgeShard, aiwgFortemiIndexToKnowledgeShardWithReport, allMigrations, appendPluginScript, assertAiwgFortemiChunkManifest, assertAiwgFortemiChunkPart, assertAiwgFortemiIndexExport, assertAiwgStaticEmbeddingSet, assertShardComponentRecord, buildAiwgChunkedIndex, buildAiwgStaticEmbeddingSet, 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, profileSupportError, projectAttachments, projectNotes, projectRecords, provenanceEdgeToShard, 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, 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, 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, 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