@gmickel/gno 1.28.0 → 1.29.0

package/src/core/retrieval-qrels.ts

@@ -7,10 +7,12 @@ import type {
   RetrievalTraceTerminalStatus,
   StoreResult,
 } from "../store/types";
+import type { EgressLineage } from "./egress-provenance";
 import type { EvidenceTarget } from "./retrieval-trace-management-helpers";
 
 import { hashTraceCanonical } from "../store/retrieval-trace-codec";
 import { err, ok } from "../store/types";
+import { mergeEgressLineages } from "./egress-provenance";
 import { parseRetrievalTraceFilters } from "./retrieval-trace-filters";
 import { stableTarget, targetKey } from "./retrieval-trace-management-helpers";
 
@@ -85,6 +87,7 @@ export interface RetrievalQrelsCase {
 export interface RetrievalTraceQrelsArtifact {
   schemaVersion: "1.0";
   format: "qrels";
+  egressLineage: EgressLineage;
   cases: RetrievalQrelsCase[];
 }
 
@@ -400,6 +403,9 @@ export const buildRetrievalQrelsArtifact = (
   return ok({
     schemaVersion: "1.0",
     format: "qrels",
+    egressLineage: mergeEgressLineages(
+      bundles.map(({ trace }) => trace.egressLineage)
+    ),
     cases: cases.sort((a, b) => a.caseId.localeCompare(b.caseId)),
   });
 };

package/src/core/retrieval-replay.ts

@@ -1,9 +1,14 @@
 /** Read-only comparison of persisted retrieval baselines with one candidate. */
 
 import type { SearchResult } from "../pipeline/types";
-import type { DocumentRow, StoreResult } from "../store/types";
+import type {
+  DocumentRow,
+  RetrievalTraceExportManifestRow,
+  StoreResult,
+} from "../store/types";
 import type {
   RetrievalQrelsCase,
+  RetrievalTraceQrelsArtifact,
   RetrievalQrel,
   RetrievalQrelsEvidence,
 } from "./retrieval-qrels";
@@ -23,6 +28,7 @@ import { computeRetrievalMetrics } from "../bench/metrics";
 import { diagnoseQueryTarget } from "../pipeline/diagnose";
 import { hashTraceCanonical } from "../store/retrieval-trace-codec";
 import { ok } from "../store/types";
+import { isMigratedLegacyEgressLineage } from "./egress-provenance";
 import { buildRetrievalQrelsArtifact } from "./retrieval-qrels";
 import {
   buildRetrievalReplaySearchOptions,
@@ -74,6 +80,16 @@ const reconstructionReason = (message: string): RetrievalReplayReason | null =>
       message.includes(`${reason}:`)
   ) ?? null;
 
+const artifactMatchesManifest = (
+  artifact: RetrievalTraceQrelsArtifact,
+  manifest: RetrievalTraceExportManifestRow
+): boolean => {
+  if (hashTraceCanonical(artifact) === manifest.artifactHash) return true;
+  if (!isMigratedLegacyEgressLineage(manifest.egressLineage)) return false;
+  const { egressLineage: _legacyProjection, ...legacyArtifact } = artifact;
+  return hashTraceCanonical(legacyArtifact) === manifest.artifactHash;
+};
+
 const targetMatchesResult = (
   qrel: RetrievalQrel,
   result: SearchResult
@@ -376,9 +392,7 @@ export const replayRetrievalTraces = async (
       )
     );
   }
-  if (
-    hashTraceCanonical(artifact.value) !== stored.value.manifest.artifactHash
-  ) {
+  if (!artifactMatchesManifest(artifact.value, stored.value.manifest)) {
     return ok(unreplayable(validatedInput, "manifest_hash_mismatch"));
   }
   let currentFingerprints;

package/src/core/retrieval-trace-export.ts

@@ -6,6 +6,7 @@ import type {
   StorePort,
   StoreResult,
 } from "../store/types";
+import type { EgressLineage } from "./egress-provenance";
 import type {
   ExportRetrievalTracesInput,
   ExportRetrievalTracesResult,
@@ -14,6 +15,7 @@ import type {
 
 import { hashTraceCanonical } from "../store/retrieval-trace-codec";
 import { err, ok } from "../store/types";
+import { mergeEgressLineages } from "./egress-provenance";
 import { buildRetrievalQrelsArtifact } from "./retrieval-qrels";
 
 const validateTraceIds = (traceIds: unknown): StoreResult<string[]> => {
@@ -38,6 +40,9 @@ const agenticArtifact = (
 ): RetrievalTraceArtifact => ({
   schemaVersion: "1.0",
   format: "agentic-receipt",
+  egressLineage: mergeEgressLineages(
+    bundles.map(({ trace }) => trace.egressLineage)
+  ),
   traces: bundles.map(({ exports: _exports, ...trace }) => trace),
 });
 
@@ -54,7 +59,10 @@ export const exportRetrievalTraces = async <
 >(
   store: StorePort,
   clock: () => number,
-  input: ExportRetrievalTracesInput<Format>
+  input: ExportRetrievalTracesInput<Format>,
+  deps: {
+    authorize?: (lineage: EgressLineage) => Promise<StoreResult<EgressLineage>>;
+  } = {}
 ): Promise<StoreResult<ExportRetrievalTracesResult<Format>>> => {
   const format = input.format ?? "agentic-receipt";
   if (!["agentic-receipt", "qrels"].includes(format)) {
@@ -77,13 +85,20 @@ export const exportRetrievalTraces = async <
   }
   const built = buildArtifact(format, bundles);
   if (!built.ok) return built;
-  const artifactHash = hashTraceCanonical(built.value);
+  const authorized = await deps.authorize?.(built.value.egressLineage);
+  if (authorized && !authorized.ok) return authorized;
+  const artifact = {
+    ...built.value,
+    egressLineage: authorized?.value ?? built.value.egressLineage,
+  } as RetrievalTraceArtifact;
+  const artifactHash = hashTraceCanonical(artifact);
   const exportId = `trace-export-${artifactHash.slice(0, 40)}`;
   const appended = await store.appendRetrievalTraceExportManifest({
     exportId,
     traceIds: traceIds.value,
     format,
     artifactHash,
+    egressLineage: artifact.egressLineage,
     createdAtMs: clock(),
   });
   if (!appended.ok) return appended;
@@ -94,9 +109,13 @@ export const exportRetrievalTraces = async <
   }
   const reconstructed = buildArtifact(format, complete.value.traces);
   if (!reconstructed.ok) return reconstructed;
+  const reconstructedCurrent = {
+    ...reconstructed.value,
+    egressLineage: complete.value.manifest.egressLineage,
+  } as RetrievalTraceArtifact;
   if (
     complete.value.manifest.traceIds.join("\0") !== traceIds.value.join("\0") ||
-    hashTraceCanonical(reconstructed.value) !==
+    hashTraceCanonical(reconstructedCurrent) !==
       complete.value.manifest.artifactHash
   ) {
     return err(
@@ -108,6 +127,6 @@ export const exportRetrievalTraces = async <
     schemaVersion: "1.0",
     result: appended.value,
     manifest: complete.value.manifest,
-    artifact: reconstructed.value,
+    artifact: reconstructedCurrent,
   } as ExportRetrievalTracesResult<Format>);
 };

package/src/core/retrieval-trace-management-helpers.ts

@@ -44,6 +44,7 @@ export const summaryOf = (
   queryShape: trace.queryShape,
   goalShape: trace.goalShape,
   fingerprints: trace.fingerprints,
+  egressLineage: trace.egressLineage,
   createdAtMs: trace.createdAtMs,
   updatedAtMs: trace.updatedAtMs,
   expiresAtMs: trace.expiresAtMs,

package/src/core/retrieval-trace-management-types.ts

@@ -10,6 +10,7 @@ import type {
   RetrievalTracePurgeResult as StoredRetrievalTracePurgeResult,
   RetrievalTraceRow,
 } from "../store/types";
+import type { EgressLineage } from "./egress-provenance";
 import type { RetrievalTraceQrelsArtifact } from "./retrieval-qrels";
 
 export interface RetrievalTraceSummary {
@@ -21,6 +22,7 @@ export interface RetrievalTraceSummary {
   queryShape: RetrievalTraceRow["queryShape"];
   goalShape: RetrievalTraceRow["goalShape"];
   fingerprints: RetrievalTraceRow["fingerprints"];
+  egressLineage: EgressLineage;
   createdAtMs: number;
   updatedAtMs: number;
   expiresAtMs: number;
@@ -87,6 +89,7 @@ export interface LabelRetrievalTraceResult {
 export interface RetrievalTraceAgenticArtifact {
   schemaVersion: "1.0";
   format: "agentic-receipt";
+  egressLineage: EgressLineage;
   traces: Array<Omit<RetrievalTraceBundle, "exports">>;
 }
 

package/src/core/retrieval-trace-management.ts

@@ -6,6 +6,7 @@ import type {
   StorePort,
   StoreResult,
 } from "../store/types";
+import type { EgressLineage } from "./egress-provenance";
 import type {
   ReplayRetrievalTraceInput,
   ReplayRetrievalTraceResult,
@@ -56,16 +57,21 @@ const DOCID_PATTERN = /^#[a-f0-9]{6,}$/;
 
 interface ManagementDeps {
   clock?: () => number;
+  authorizeExport?: (
+    lineage: EgressLineage
+  ) => Promise<StoreResult<EgressLineage>>;
 }
 
 export class RetrievalTraceManagementService {
   private readonly clock: () => number;
+  private readonly authorizeExport?: ManagementDeps["authorizeExport"];
 
   constructor(
     private readonly store: StorePort,
     deps: ManagementDeps = {}
   ) {
     this.clock = deps.clock ?? Date.now;
+    this.authorizeExport = deps.authorizeExport;
   }
 
   async list(
@@ -219,7 +225,9 @@ export class RetrievalTraceManagementService {
   async export<Format extends RetrievalTraceExportFormat = "agentic-receipt">(
     input: ExportRetrievalTracesInput<Format>
   ): Promise<StoreResult<ExportRetrievalTracesResult<Format>>> {
-    return exportRetrievalTraces(this.store, this.clock, input);
+    return exportRetrievalTraces(this.store, this.clock, input, {
+      authorize: this.authorizeExport,
+    });
   }
 
   async replay(

package/src/core/retrieval-trace-session.ts

@@ -16,6 +16,13 @@ import {
   SEARCH_RESULTS_TRACE_METADATA,
 } from "../pipeline/types";
 import { err, ok } from "../store/types";
+import { contextCapsuleEgressLineage } from "./context-capsule";
+import {
+  createEgressLineage,
+  legacyLocalOnlyEgressLineage,
+  mergeEgressLineages,
+  resolveEgressLineage,
+} from "./egress-provenance";
 import {
   MIN_RETRIEVAL_TRACE_RECORDS,
   RetrievalTraceRecorder,
@@ -140,6 +147,26 @@ const evidenceFromCapsule = (
       : { graphExpanded: item.graphExpanded }),
   }));
 
+const requestedCollectionScope = (
+  filters: Record<string, unknown> | undefined
+): string[] | undefined => {
+  const collections = filters?.collections;
+  if (Array.isArray(collections) && collections.length > 0) {
+    if (!collections.every((value) => typeof value === "string")) {
+      throw new TypeError("Trace collection scope must contain only names");
+    }
+    return collections;
+  }
+  const collection = filters?.collection;
+  if (collection === undefined || collection === null || collection === "") {
+    return undefined;
+  }
+  if (typeof collection !== "string") {
+    throw new TypeError("Trace collection scope must be a name");
+  }
+  return [collection];
+};
+
 export class RetrievalTraceSession {
   readonly traceId: string;
 
@@ -154,6 +181,7 @@ export class RetrievalTraceSession {
     private readonly recorder: RetrievalTraceRecorder,
     traceId: string,
     private readonly clock: () => number,
+    private egressLineage: ReturnType<typeof createEgressLineage>,
     private readonly operationId = traceId,
     private readonly maxRecords = 100_000
   ) {
@@ -180,11 +208,37 @@ export class RetrievalTraceSession {
       clock,
       idFactory: input.idFactory,
     });
+    const collections = await input.store.getCollections();
+    if (!collections.ok) return collections;
+    let egressLineage;
+    try {
+      const requestedScope = requestedCollectionScope(input.filters);
+      egressLineage =
+        collections.value.length === 0
+          ? legacyLocalOnlyEgressLineage()
+          : resolveEgressLineage(
+              collections.value.map((collection) => ({
+                collection: collection.name,
+                policy: collection.egressPolicy,
+                source: collection.egressPolicySource,
+              })),
+              requestedScope
+            );
+    } catch (cause) {
+      return err(
+        "INVALID_INPUT",
+        cause instanceof Error
+          ? cause.message
+          : "Invalid retrieval trace collection scope",
+        cause
+      );
+    }
     const started = await recorder.start({
       query: input.query,
       goal: input.goal,
       filters: input.filters,
       fingerprints: await input.fingerprints(),
+      egressLineage,
     });
     if (!started.ok) return started;
     if (!started.value.recorded) return ok(null);
@@ -192,6 +246,7 @@ export class RetrievalTraceSession {
       recorder,
       started.value.traceId,
       clock,
+      egressLineage,
       started.value.traceId,
       input.config.retention.maxRecordsPerTrace
     );
@@ -233,6 +288,7 @@ export class RetrievalTraceSession {
       new RetrievalTraceRecorder(input.store, input.config, { clock }),
       input.traceId,
       clock,
+      stored.value.trace.egressLineage,
       crypto.randomUUID(),
       input.config.retention.maxRecordsPerTrace
     );
@@ -257,6 +313,13 @@ export class RetrievalTraceSession {
     latencyMs?: number
   ): Promise<StoreResult<"inserted" | "duplicate" | "disabled">> {
     if (!this.hasCapacity(2)) return ok("disabled");
+    const resultLineages = result.results.flatMap((item) =>
+      item.egressLineage ? [item.egressLineage] : []
+    );
+    if (resultLineages.length > 0) {
+      const widened = await this.ensureLineageCoverage(resultLineages);
+      if (!widened.ok) return widened;
+    }
     const ranked = result.results.flatMap((item, index) => {
       const evidence = evidenceFromResult(item, index + 1);
       return evidence ? [evidence] : [];
@@ -317,6 +380,12 @@ export class RetrievalTraceSession {
     latencyMs?: number
   ): Promise<StoreResult<"inserted" | "duplicate" | "disabled">> {
     if (!this.hasCapacity(2)) return ok("disabled");
+    if (capsule.schemaVersion === "1.0" || capsule.schemaVersion === "1.1") {
+      const widened = await this.ensureLineageCoverage([
+        contextCapsuleEgressLineage(capsule),
+      ]);
+      if (!widened.ok) return widened;
+    }
     const payload = {
       evidence: evidenceFromCapsule(capsule),
       capsuleId: capsule.capsuleId,
@@ -449,6 +518,31 @@ export class RetrievalTraceSession {
     return appended;
   }
 
+  private async ensureLineageCoverage(
+    lineages: ReturnType<typeof createEgressLineage>[]
+  ): Promise<StoreResult<"inserted" | "duplicate">> {
+    let merged;
+    try {
+      merged = mergeEgressLineages([this.egressLineage, ...lineages]);
+    } catch (cause) {
+      return err(
+        "INVALID_INPUT",
+        cause instanceof Error
+          ? cause.message
+          : "Conflicting retrieval trace policy lineage",
+        cause
+      );
+    }
+    if (merged.digest === this.egressLineage.digest) return ok("duplicate");
+    const persisted = await this.recorder.mergeEgressLineage(
+      this.traceId,
+      merged
+    );
+    if (!persisted.ok) return persisted;
+    this.egressLineage = merged;
+    return persisted;
+  }
+
   private hasCapacity(records: number): boolean {
     return this.persistedRecords + records + 1 <= this.maxRecords;
   }

package/src/core/retrieval-trace.ts

@@ -16,6 +16,7 @@ import type {
   StorePort,
   StoreResult,
 } from "../store/types";
+import type { EgressLineage } from "./egress-provenance";
 
 import {
   parseRetrievalTraceEventInput,
@@ -23,6 +24,10 @@ import {
   parseRetrievalTraceRunInput,
 } from "../store/retrieval-trace-codec";
 import { err, ok } from "../store/types";
+import {
+  egressLineageSchema,
+  legacyLocalOnlyEgressLineage,
+} from "./egress-provenance";
 import { canonicalizeRetrievalTraceFilters } from "./retrieval-trace-filter-normalization";
 
 const sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
@@ -80,6 +85,7 @@ const startTraceSchema = z
         index: sha256Schema,
       })
       .strict(),
+    egressLineage: egressLineageSchema.default(legacyLocalOnlyEgressLineage()),
   })
   .strict();
 
@@ -186,6 +192,7 @@ export interface StartRetrievalTraceInput {
   goal?: string;
   filters?: z.input<typeof traceFiltersSchema>;
   fingerprints: RetrievalTraceFingerprints;
+  egressLineage?: EgressLineage;
 }
 
 export type RetrievalTraceWriteResult =
@@ -318,6 +325,7 @@ export class RetrievalTraceRecorder {
       goalDigest: replay && goal !== undefined ? sha256(goal) : null,
       goalShape: textShape(goal),
       filters: replay ? filters : projectMetadataObject(filters),
+      egressLineage: parsed.data.egressLineage,
       fingerprints: parsed.data.fingerprints,
       status: "open",
       createdAtMs: nowMs,
@@ -371,6 +379,20 @@ export class RetrievalTraceRecorder {
     }
   }
 
+  async mergeEgressLineage(
+    traceId: string,
+    lineage: EgressLineage
+  ): Promise<StoreResult<RetrievalTraceAppendResult>> {
+    if (!this.config?.enabled) return ok("duplicate");
+    if (!this.store.mergeRetrievalTraceEgressLineage) {
+      return err(
+        "CONSTRAINT_VIOLATION",
+        "Store cannot widen retrieval trace policy lineage"
+      );
+    }
+    return this.store.mergeRetrievalTraceEgressLineage(traceId, lineage);
+  }
+
   async appendEvent(
     input: RetrievalTraceEventInput
   ): Promise<StoreResult<RetrievalTraceAppendResult | "disabled">> {

package/src/ingestion/record-adapter.ts

@@ -5,7 +5,12 @@ import type {
   RecordAdapterEvent,
   RecordAdapterInput,
 } from "../converters/types";
+import type { EgressLineage } from "../core/egress-provenance";
 
+import {
+  egressLineageSchema,
+  legacyLocalOnlyEgressLineage,
+} from "../core/egress-provenance";
 import {
   type AccountedCanonicalRecord,
   adapterFailureMessage,
@@ -27,6 +32,7 @@ export interface RecordAdapterRunResult {
   adapterId: string;
   adapterVersion: string;
   adapterFingerprint: string;
+  egressLineage: EgressLineage;
   records: CanonicalRecord[];
   failures: RecordAdapterFailure[];
   failedRecordKeys: string[];
@@ -83,10 +89,14 @@ const closeIterator = async (
 /** Consume one adapter snapshot while centrally enforcing every global cap. */
 export async function runRecordAdapter(
   adapter: RecordAdapter,
-  input: RecordAdapterInput
+  input: RecordAdapterInput,
+  options: { egressLineage?: EgressLineage } = {}
 ): Promise<RecordAdapterRunResult> {
   const adapterIdentity = normalizeRecordAdapterIdentity(adapter);
   const adapterFingerprint = recordAdapterFingerprint(adapter);
+  const egressLineage = egressLineageSchema.parse(
+    options.egressLineage ?? legacyLocalOnlyEgressLineage(input.collection)
+  );
   const accepted = new Map<string, AccountedCanonicalRecord>();
   const seenKeys = new Set<string>();
   const failedRecordKeys = new Set<string>();
@@ -418,6 +428,7 @@ export async function runRecordAdapter(
     adapterId: adapterIdentity.id,
     adapterVersion: adapterIdentity.version,
     adapterFingerprint,
+    egressLineage,
     records: [...accepted.values()]
       .sort((left, right) => left.recordKey.localeCompare(right.recordKey))
       .map(

package/src/ingestion/record-container.ts

@@ -15,11 +15,13 @@ import type {
   WalkEntry,
 } from "./types";
 
+import { resolveConfiguredEgressPolicy } from "../config/types";
 import { DEFAULT_RECORD_ADAPTER_LIMITS } from "../converters/types";
 import {
   diffDocumentStructure,
   extractDocumentStructure,
 } from "../core/change-diff";
+import { createEgressLineage } from "../core/egress-provenance";
 import { normalizeTag, validateTag } from "../core/tags";
 import { runRecordAdapter } from "./record-adapter";
 import { recordVirtualPath } from "./record-path";
@@ -432,29 +434,42 @@ const recordProvenanceChanged = (
 export async function processRecordContainer(
   input: RecordContainerInput
 ): Promise<FileSyncResult> {
-  const snapshot = await runRecordAdapter(input.adapter, {
-    sourcePath: input.entry.absPath,
-    relativePath: input.entry.relPath,
-    collection: input.collection.name,
-    mime: input.mime,
-    ext: input.ext,
-    open: (signal) => sourceStream(input.entry.absPath, signal),
-    limits: {
-      ...DEFAULT_RECORD_ADAPTER_LIMITS,
-      timeoutMs: Math.min(
-        DEFAULT_RECORD_ADAPTER_LIMITS.timeoutMs ?? 60_000,
-        input.options.limits?.timeoutMs ?? Number.POSITIVE_INFINITY
-      ),
-      maxSourceBytes: Math.min(
-        DEFAULT_RECORD_ADAPTER_LIMITS.maxSourceBytes,
-        input.options.limits?.maxBytes ?? Number.POSITIVE_INFINITY
-      ),
-      maxTotalChars: Math.min(
-        DEFAULT_RECORD_ADAPTER_LIMITS.maxTotalChars,
-        input.options.limits?.maxOutputChars ?? Number.POSITIVE_INFINITY
-      ),
+  const effectiveEgress = resolveConfiguredEgressPolicy(input.collection);
+  const snapshot = await runRecordAdapter(
+    input.adapter,
+    {
+      sourcePath: input.entry.absPath,
+      relativePath: input.entry.relPath,
+      collection: input.collection.name,
+      mime: input.mime,
+      ext: input.ext,
+      open: (signal) => sourceStream(input.entry.absPath, signal),
+      limits: {
+        ...DEFAULT_RECORD_ADAPTER_LIMITS,
+        timeoutMs: Math.min(
+          DEFAULT_RECORD_ADAPTER_LIMITS.timeoutMs ?? 60_000,
+          input.options.limits?.timeoutMs ?? Number.POSITIVE_INFINITY
+        ),
+        maxSourceBytes: Math.min(
+          DEFAULT_RECORD_ADAPTER_LIMITS.maxSourceBytes,
+          input.options.limits?.maxBytes ?? Number.POSITIVE_INFINITY
+        ),
+        maxTotalChars: Math.min(
+          DEFAULT_RECORD_ADAPTER_LIMITS.maxTotalChars,
+          input.options.limits?.maxOutputChars ?? Number.POSITIVE_INFINITY
+        ),
+      },
     },
-  });
+    {
+      egressLineage: createEgressLineage([
+        {
+          collection: input.collection.name,
+          policy: effectiveEgress.policy,
+          source: effectiveEgress.source,
+        },
+      ]),
+    }
+  );
 
   const reconcileAndApply = async (): Promise<AppliedRecordReconciliation> => {
     const priorDocuments = mustOk(
@@ -615,6 +630,7 @@ export async function processRecordContainer(
     adapterId: snapshot.adapterId,
     adapterVersion: snapshot.adapterVersion,
     adapterFingerprint: snapshot.adapterFingerprint,
+    egressLineage: snapshot.egressLineage,
     snapshotState: snapshot.snapshotState,
     authoritative: snapshot.authoritative,
     stoppedByCap: snapshot.stoppedByCap,

package/src/ingestion/sync.ts

@@ -53,6 +53,7 @@ import {
   normalizeRelationEdgeType,
   normalizeRelationTarget,
 } from "../core/change-diff";
+import { enforceCollectionEgress } from "../core/egress-enforcement";
 import {
   normalizeMarkdownPath,
   normalizeWikiName,
@@ -1598,10 +1599,24 @@ export class SyncService {
 
     // 1. Run preflight commands
     if (options.runUpdateCmd !== false && collection.updateCmd) {
+      enforceCollectionEgress({
+        collections: [collection],
+        action: "export",
+        destinationZone: "remote",
+        caller: { authenticated: true, operationAuthorized: true },
+        contentClass: "source",
+      });
       await runUpdateCmd(collection.path, collection.updateCmd);
     }
 
     if (options.gitPull && (await isGitRepo(collection.path))) {
+      enforceCollectionEgress({
+        collections: [collection],
+        action: "export",
+        destinationZone: "remote",
+        caller: { authenticated: true, operationAuthorized: true },
+        contentClass: "metadata",
+      });
       await gitPull(collection.path);
     }
 

package/src/ingestion/types.ts

@@ -11,6 +11,7 @@ import type {
   RecordAdapterFailure,
   RecordAttachmentInventoryItem,
 } from "../converters/types";
+import type { EgressLineage } from "../core/egress-provenance";
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Walker Types
@@ -203,6 +204,7 @@ export interface FileSyncResult {
     adapterId: string;
     adapterVersion: string;
     adapterFingerprint: string;
+    egressLineage?: EgressLineage;
     snapshotState: "complete" | "partial";
     authoritative: boolean;
     stoppedByCap: boolean;

package/src/llm/errors.ts

@@ -18,6 +18,7 @@ export type LlmErrorCode =
   | "INVALID_MODEL_FILE"
   | "MODEL_DOWNLOAD_INTERCEPTED"
   | "INFERENCE_FAILED"
+  | "EGRESS_DENIED"
   | "TIMEOUT"
   | "OUT_OF_MEMORY"
   | "INVALID_URI"
@@ -202,6 +203,15 @@ export function inferenceFailedError(uri: string, cause?: unknown): LlmError {
   });
 }
 
+export function egressDeniedInferenceError(cause?: unknown): LlmError {
+  return llmError("EGRESS_DENIED", {
+    message: "Operation blocked by collection egress policy",
+    retryable: false,
+    cause,
+    suggestion: "Review the collection egress policy and model destination.",
+  });
+}
+
 export function timeoutError(
   uri: string,
   operation: "load" | "inference",