@gmickel/gno 1.28.0 → 1.29.1

package/src/pipeline/egress-lineage.ts

@@ -0,0 +1,124 @@
+/** Attach complete collection policy ownership to observable search results. */
+
+import type { EgressLineage } from "../core/egress-provenance";
+import type {
+  CollectionRow,
+  DocumentRow,
+  StorePort,
+  StoreResult,
+} from "../store/types";
+import type { SearchResult } from "./types";
+
+import { parseUri } from "../app/constants";
+import { createEgressLineage } from "../core/egress-provenance";
+import { err, ok } from "../store/types";
+
+type EgressLineageStore = Pick<
+  StorePort,
+  "getCollections" | "getDocumentsByMirrorHashes"
+>;
+
+export const attachSearchResultEgressLineage = async (
+  store: EgressLineageStore,
+  results: SearchResult[],
+  options: {
+    ownershipHashes?: readonly string[];
+    ownershipDocuments?: readonly Pick<
+      DocumentRow,
+      "collection" | "mirrorHash"
+    >[];
+    collections?: readonly CollectionRow[];
+  } = {}
+): Promise<StoreResult<void>> => {
+  if (results.length === 0) return ok(undefined);
+  const mirrorHashes = [
+    ...new Set(
+      options.ownershipHashes ??
+        results
+          .map((result) => result.conversion?.mirrorHash)
+          .filter((hash): hash is string => Boolean(hash))
+    ),
+  ];
+  let ownershipDocuments = options.ownershipDocuments;
+  if (ownershipDocuments === undefined) {
+    if (typeof store.getDocumentsByMirrorHashes !== "function") {
+      ownershipDocuments = [];
+    } else {
+      const documentsResult = await store.getDocumentsByMirrorHashes(
+        mirrorHashes,
+        {
+          activeOnly: true,
+        }
+      );
+      if (!documentsResult.ok) return documentsResult;
+      ownershipDocuments = documentsResult.value;
+    }
+  }
+  let collectionRows = options.collections;
+  if (collectionRows === undefined) {
+    const collectionsResult = await store.getCollections();
+    if (!collectionsResult.ok) return collectionsResult;
+    collectionRows = collectionsResult.value;
+  }
+  const policyByCollection = new Map(
+    collectionRows.map((collection) => [
+      collection.name,
+      {
+        collection: collection.name,
+        policy: collection.egressPolicy,
+        source: collection.egressPolicySource,
+      },
+    ])
+  );
+  const lineageByMirrorHash = new Map<string, EgressLineage>();
+  for (const mirrorHash of mirrorHashes) {
+    const ownerCollections = [
+      ...new Set([
+        ...ownershipDocuments
+          .filter((document) => document.mirrorHash === mirrorHash)
+          .map((owner) => owner.collection),
+        ...results
+          .filter((result) => result.conversion?.mirrorHash === mirrorHash)
+          .map((result) => parseUri(result.uri)?.collection)
+          .filter((collection): collection is string => Boolean(collection)),
+      ]),
+    ];
+    const policies = ownerCollections.map((collection) =>
+      policyByCollection.get(collection)
+    );
+    if (policies.some((policy) => policy === undefined)) {
+      return err(
+        "INVALID_INPUT",
+        "Search result policy lineage references an unknown collection"
+      );
+    }
+    if (policies.length === 0) continue;
+    try {
+      lineageByMirrorHash.set(
+        mirrorHash,
+        createEgressLineage(
+          policies as NonNullable<(typeof policies)[number]>[]
+        )
+      );
+    } catch (error) {
+      return err(
+        "INVALID_INPUT",
+        "Search result policy lineage is incomplete",
+        error
+      );
+    }
+  }
+  for (const result of results) {
+    const lineage = result.conversion?.mirrorHash
+      ? lineageByMirrorHash.get(result.conversion.mirrorHash)
+      : undefined;
+    if (!lineage) {
+      return err(
+        "INVALID_INPUT",
+        "Search result policy lineage could not be resolved"
+      );
+    }
+    result.egressLineage = lineage;
+  }
+  return ok(undefined);
+};

package/src/pipeline/hybrid.ts

@@ -32,6 +32,7 @@ import {
   sortByFinalScoreStable,
 } from "./content-type-boost";
 import { formatQueryForEmbedding } from "./contextual";
+import { attachSearchResultEgressLineage } from "./egress-lineage";
 import { expandQuery } from "./expansion";
 import {
   buildExplainResults,
@@ -1169,6 +1170,19 @@ export async function searchHybrid(
       }
     : undefined;
   await attachSearchResultContexts(store, finalResults);
+  const lineageResult = await attachSearchResultEgressLineage(
+    store,
+    finalResults,
+    {
+      ownershipHashes: [...neededHashes],
+      ownershipDocuments:
+        options.collection === undefined ? documents : undefined,
+      collections: collectionsResult.ok ? collectionsResult.value : undefined,
+    }
+  );
+  if (!lineageResult.ok) {
+    return err("QUERY_FAILED", lineageResult.error.message);
+  }
 
   const output: SearchResults = {
     results: finalResults,

package/src/pipeline/search.ts

@@ -24,6 +24,7 @@ import {
   hasAuxiliaryRanking,
   sortByFinalScoreStable,
 } from "./content-type-boost";
+import { attachSearchResultEgressLineage } from "./egress-lineage";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
@@ -433,6 +434,17 @@ export async function searchBm25(
     if (metadata) metadata.retrievalRank = index + 1;
   }
   await attachSearchResultContexts(store, finalResults);
+  const lineageResult = await attachSearchResultEgressLineage(
+    store,
+    finalResults,
+    {
+      ownershipHashes: uniqueHashes,
+      collections: collectionsResult.ok ? collectionsResult.value : undefined,
+    }
+  );
+  if (!lineageResult.ok) {
+    return err("QUERY_FAILED", lineageResult.error.message);
+  }
 
   const output: SearchResults = {
     results: finalResults,

package/src/pipeline/types.ts

@@ -10,6 +10,7 @@ import type {
   ContextCapsuleV1,
   ContextCapsuleVerification,
 } from "../core/context-capsule";
+import type { EgressLineage } from "../core/egress-provenance";
 import type { RecordEvidenceMetadata } from "../core/record-metadata";
 import type { RetrievalTraceSession } from "../core/retrieval-trace-session";
 import type { StoreResult } from "../store/types";
@@ -89,6 +90,8 @@ export interface SearchResult {
   conversion?: SearchResultConversion;
   /** Bounded logical-record provenance for file/export adapters. */
   record?: RecordEvidenceMetadata;
+  /** Complete, most-restrictive collection ownership for this derived result. */
+  egressLineage?: EgressLineage;
   [SEARCH_RESULT_PLANNER_METADATA]?: SearchResultPlannerMetadata;
 }
 

package/src/pipeline/vsearch.ts

@@ -22,6 +22,7 @@ import {
   sortByFinalScoreStable,
 } from "./content-type-boost";
 import { formatQueryForEmbedding } from "./contextual";
+import { attachSearchResultEgressLineage } from "./egress-lineage";
 import { matchesExcludedChunks, matchesExcludedText } from "./exclude";
 import { selectBestChunkForSteering } from "./intent";
 import { hasProjectAffinity } from "./project-affinity";
@@ -143,17 +144,18 @@ export async function searchVectorWithEmbedding(
   }
 
   // Cache docs to avoid N+1 queries (filtered by collection and tags)
-  const docsByMirrorHash = await buildDocumentMap(store, {
-    collection: options.collection,
-    relPathPrefix: options.retrievalScope?.relPathPrefix,
-    tagsAll: options.tagsAll,
-    tagsAny: options.tagsAny,
-    since: temporalRange.since,
-    until: temporalRange.until,
-    categories: options.categories,
-    author: options.author,
-    mirrorHashes: uniqueHashes,
-  });
+  const { documents: docsByMirrorHash, ownershipDocuments } =
+    await buildDocumentMap(store, {
+      collection: options.collection,
+      relPathPrefix: options.retrievalScope?.relPathPrefix,
+      tagsAll: options.tagsAll,
+      tagsAny: options.tagsAny,
+      since: temporalRange.since,
+      until: temporalRange.until,
+      categories: options.categories,
+      author: options.author,
+      mirrorHashes: uniqueHashes,
+    });
 
   // Pre-fetch all chunks in one batch query (eliminates N+1)
   const chunksMapResult = await store.getChunksBatch(uniqueHashes);
@@ -423,6 +425,18 @@ export async function searchVectorWithEmbedding(
     if (metadata) metadata.retrievalRank = index + 1;
   }
   await attachSearchResultContexts(store, finalResults);
+  const lineageResult = await attachSearchResultEgressLineage(
+    store,
+    finalResults,
+    {
+      ownershipHashes: uniqueHashes,
+      ownershipDocuments,
+      collections: collectionsResult.ok ? collectionsResult.value : undefined,
+    }
+  );
+  if (!lineageResult.ok) {
+    return err("QUERY_FAILED", lineageResult.error.message);
+  }
 
   const output: SearchResults = {
     results: finalResults,
@@ -560,28 +574,35 @@ function matchesCategoryFilter(
 async function buildDocumentMap(
   store: StorePort,
   options: DocumentMapOptions = {}
-): Promise<Map<string, DocumentInfo[]>> {
-  const result = new Map<string, DocumentInfo[]>();
+): Promise<{
+  documents: Map<string, DocumentInfo[]>;
+  ownershipDocuments: DocumentRow[];
+}> {
+  const documents = new Map<string, DocumentInfo[]>();
 
   if (options.mirrorHashes && options.mirrorHashes.length === 0) {
-    return result;
+    return { documents, ownershipDocuments: [] };
   }
 
   const docs = options.mirrorHashes
     ? await store.getDocumentsByMirrorHashes(options.mirrorHashes, {
-        collection: options.collection,
         activeOnly: true,
       })
     : await store.listDocuments(options.collection);
   if (!docs.ok) {
-    return result;
+    return { documents, ownershipDocuments: [] };
   }
 
   // Filter docs with mirrorHash.
   // listDocuments path still needs explicit active filter.
-  const activeDocs = options.mirrorHashes
+  const ownershipDocuments = options.mirrorHashes
     ? docs.value.filter((d) => d.mirrorHash)
     : docs.value.filter((d) => d.mirrorHash && d.active);
+  const activeDocs = options.collection
+    ? ownershipDocuments.filter(
+        (document) => document.collection === options.collection
+      )
+    : ownershipDocuments;
   const temporalRange: TemporalRange = {
     since: options.since,
     until: options.until,
@@ -674,10 +695,10 @@ async function buildDocumentMap(
       recordAnchors: doc.recordAnchors,
       recordAdapterFingerprint: doc.recordAdapterFingerprint,
     };
-    const matchingDocuments = result.get(doc.mirrorHash!) ?? [];
+    const matchingDocuments = documents.get(doc.mirrorHash!) ?? [];
     matchingDocuments.push(documentInfo);
-    result.set(doc.mirrorHash!, matchingDocuments);
+    documents.set(doc.mirrorHash!, matchingDocuments);
   }
 
-  return result;
+  return { documents, ownershipDocuments };
 }

package/src/publish/artifact.ts

@@ -4,6 +4,7 @@
  * @module src/publish/artifact
  */
 
+import type { EgressLineage } from "../core/egress-provenance";
 import type { DocumentRow } from "../store/types";
 
 import { deriveDocid } from "../app/constants";
@@ -11,6 +12,10 @@ import {
   contextCapsuleEvidenceIdentity,
   sha256Text,
 } from "../core/context-capsule-validation";
+import {
+  egressLineageSchema,
+  legacyLocalOnlyEgressLineage,
+} from "../core/egress-provenance";
 import { stripFrontmatter } from "../ingestion/frontmatter";
 import {
   MAX_PUBLISH_SLUG_LENGTH,
@@ -71,6 +76,7 @@ export interface PublicPublishDocument {
 export interface PublicPublishManifest {
   capabilities: typeof PUBLIC_PUBLISH_CAPABILITIES;
   documents: PublicPublishDocument[];
+  egressLineage: EgressLineage;
   generatedAt: string;
   projectionRevision: string;
   schemaVersion: typeof PUBLIC_PUBLISH_MANIFEST_SCHEMA_VERSION;
@@ -116,6 +122,7 @@ export interface EncryptedPublishArtifactSpace {
 }
 
 export interface PublishArtifactV1 {
+  egressLineage: EgressLineage;
   exportedAt: string;
   source: string;
   spaces: PublishArtifactSpace[];
@@ -123,6 +130,7 @@ export interface PublishArtifactV1 {
 }
 
 export interface PublishArtifactV2 {
+  egressLineage: EgressLineage;
   exportedAt: string;
   source: string;
   spaces: EncryptedPublishArtifactSpace[];
@@ -279,6 +287,7 @@ const buildPublicPublishDocument = (
 };
 
 export const buildPublicPublishManifest = (input: {
+  egressLineage?: EgressLineage;
   exportedAt: string;
   homeNoteSlug?: string;
   notes: PublishArtifactNote[];
@@ -288,7 +297,11 @@ export const buildPublicPublishManifest = (input: {
   title: string;
   visibility: "public";
 }): PublicPublishManifest => {
-  const validated = validateAndProjectPublishSpaceInput(input);
+  const { egressLineage: providedLineage, ...spaceInput } = input;
+  const validated = validateAndProjectPublishSpaceInput(spaceInput);
+  const egressLineage = egressLineageSchema.parse(
+    providedLineage ?? legacyLocalOnlyEgressLineage("legacy")
+  );
   if (validated.visibility !== "public") {
     throw new Error("Public publish manifests require public visibility");
   }
@@ -304,6 +317,7 @@ export const buildPublicPublishManifest = (input: {
   const revisionProjection = {
     capabilities: PUBLIC_PUBLISH_CAPABILITIES,
     documents,
+    egressLineage,
     homeNoteSlug: validated.homeNoteSlug ?? null,
     notes: validated.notes
       .map((note) => ({
@@ -324,6 +338,7 @@ export const buildPublicPublishManifest = (input: {
   return {
     capabilities: { ...PUBLIC_PUBLISH_CAPABILITIES },
     documents,
+    egressLineage,
     generatedAt: exportedAt,
     projectionRevision: sha256Text(canonicalJson(revisionProjection)),
     schemaVersion: PUBLIC_PUBLISH_MANIFEST_SCHEMA_VERSION,
@@ -332,6 +347,7 @@ export const buildPublicPublishManifest = (input: {
 };
 
 export const buildPublishArtifact = (input: {
+  egressLineage?: EgressLineage;
   homeNoteSlug?: string;
   notes: PublishArtifactNote[];
   routeSlug: string;
@@ -340,7 +356,11 @@ export const buildPublishArtifact = (input: {
   title: string;
   visibility: Exclude<PublishVisibility, "encrypted">;
 }): PublishArtifactV1 => {
-  const validated = validateAndProjectPublishSpaceInput(input);
+  const { egressLineage: providedLineage, ...spaceInput } = input;
+  const validated = validateAndProjectPublishSpaceInput(spaceInput);
+  const egressLineage = egressLineageSchema.parse(
+    providedLineage ?? legacyLocalOnlyEgressLineage("legacy")
+  );
   const exportedAt = new Date().toISOString();
   const base = {
     ...(validated.homeNoteSlug === undefined
@@ -357,6 +377,7 @@ export const buildPublishArtifact = (input: {
       ? {
           ...base,
           manifest: buildPublicPublishManifest({
+            egressLineage,
             exportedAt,
             homeNoteSlug: validated.homeNoteSlug,
             notes: validated.notes,
@@ -374,6 +395,7 @@ export const buildPublishArtifact = (input: {
         };
 
   return {
+    egressLineage,
     exportedAt,
     source: validated.routeSlug,
     spaces: [space],
@@ -382,14 +404,20 @@ export const buildPublishArtifact = (input: {
 };
 
 export const buildEncryptedPublishArtifact = (input: {
+  egressLineage?: EgressLineage;
   encryptedPayload: EncryptedArtifactPayload;
   routeSlug: string;
   secretToken: string;
   sourceType: "note" | "collection";
 }): PublishArtifactV2 => {
-  const validated = validateAndProjectEncryptedPublishInput(input);
+  const { egressLineage: providedLineage, ...encryptedInput } = input;
+  const validated = validateAndProjectEncryptedPublishInput(encryptedInput);
+  const egressLineage = egressLineageSchema.parse(
+    providedLineage ?? legacyLocalOnlyEgressLineage("legacy")
+  );
   const exportedAt = requirePublishDateTime(new Date().toISOString());
   return {
+    egressLineage,
     exportedAt,
     source: validated.routeSlug,
     spaces: [

package/src/publish/export-service.ts

@@ -7,6 +7,7 @@
 import type { Collection } from "../config/types";
 import type { DocumentRow, StorePort, TagRow } from "../store/types";
 
+import { enforceCollectionEgressWithAudit } from "../core/egress-enforcement";
 import { parseRef } from "../core/ref-parser";
 import { parseFrontmatter, stripFrontmatter } from "../ingestion/frontmatter";
 import { getContentBatch } from "../store/content-batch";
@@ -217,6 +218,15 @@ async function exportCollectionArtifact(
     target,
   ]);
   const visibility = resolveVisibility(options.visibility);
+  const { lineage } = await enforceCollectionEgressWithAudit({
+    collections,
+    collectionNames: [collection.name],
+    action: "export",
+    destinationZone: "local_process",
+    caller: { authenticated: true, operationAuthorized: true },
+    contentClass: "source",
+    store,
+  });
 
   if (visibility === "encrypted") {
     if (!options.encryptionPassphrase) {
@@ -237,6 +247,7 @@ async function exportCollectionArtifact(
     });
 
     return buildEncryptedPublishArtifact({
+      egressLineage: lineage,
       encryptedPayload: encrypted.encryptedPayload,
       routeSlug,
       secretToken: encrypted.secretToken,
@@ -245,6 +256,7 @@ async function exportCollectionArtifact(
   }
 
   return buildPublishArtifact({
+    egressLineage: lineage,
     homeNoteSlug: chooseHomeNoteSlug(notes),
     notes,
     routeSlug,
@@ -257,6 +269,7 @@ async function exportCollectionArtifact(
 
 async function exportDocumentArtifact(
   store: StorePort,
+  collections: Collection[],
   target: string,
   options: PublishExportCoreOptions,
   warnings: SanitizeWarning[]
@@ -283,6 +296,15 @@ async function exportDocumentArtifact(
   const slug = deriveExportedSlug(doc);
   const visibility = resolveVisibility(options.visibility);
   const routeSlug = derivePublishSlug([options.routeSlug ?? "", slug, target]);
+  const { lineage } = await enforceCollectionEgressWithAudit({
+    collections,
+    collectionNames: [doc.collection],
+    action: "export",
+    destinationZone: "local_process",
+    caller: { authenticated: true, operationAuthorized: true },
+    contentClass: "source",
+    store,
+  });
 
   if (visibility === "encrypted") {
     if (!options.encryptionPassphrase) {
@@ -310,6 +332,7 @@ async function exportDocumentArtifact(
     });
 
     return buildEncryptedPublishArtifact({
+      egressLineage: lineage,
       encryptedPayload: encrypted.encryptedPayload,
       routeSlug,
       secretToken: encrypted.secretToken,
@@ -318,6 +341,7 @@ async function exportDocumentArtifact(
   }
 
   return buildPublishArtifact({
+    egressLineage: lineage,
     notes: [
       {
         markdown,
@@ -357,6 +381,7 @@ export async function exportPublishArtifact(input: {
     )) ??
     (await exportDocumentArtifact(
       input.store,
+      input.collections,
       input.target,
       input.options,
       warnings