@tearleads/client-sdk 0.1.116 → 0.1.118

package/data/persistence/verifiedCitations/citationScope.js

@@ -0,0 +1,121 @@
+import { MAX_CONTAINER_PATH_LENGTH } from "../../../internal/validators/util/index.js";
+import { and, eq, inArray } from "drizzle-orm";
+import { documentContainerProjection } from "../../sqlite/schema/index.js";
+import { containers } from "../../sqlite/schema/containerSchema.js";
+import { documentDiscoveryHeads, pendingDocumentDiscoveries, } from "../../sqlite/schema/documentDiscoveryEvidenceSchema.js";
+import { verifiedAccessManifestBundles as bundles } from "../../sqlite/schema/verifiedManifestBundleSchema.js";
+/** The requested object first, then each container whose lineage it cites. */
+async function containerLineage(db, containerId, prefix = []) {
+    const lineage = [...prefix, containerId];
+    while (lineage.length < MAX_CONTAINER_PATH_LENGTH) {
+        const [row] = await db
+            .select({ parentId: containers.parentId })
+            .from(containers)
+            .where(eq(containers.id, lineage.at(-1) ?? ""))
+            .limit(1);
+        const parentId = row?.parentId;
+        if (!parentId || lineage.includes(parentId))
+            break;
+        lineage.push(parentId);
+    }
+    return lineage;
+}
+/**
+ * A container the device has not stored yet has no local parent, so its
+ * listing names one: the lineage continues through the listed parent's
+ * stored lineage. A wrong parent only changes which held hashes are cited.
+ */
+async function containerTargetLineage(db, target) {
+    const parentId = target.listing?.parentId;
+    if (!parentId || parentId === target.id)
+        return containerLineage(db, target.id);
+    const [stored] = await db
+        .select({ id: containers.id })
+        .from(containers)
+        .where(eq(containers.id, target.id))
+        .limit(1);
+    return stored
+        ? containerLineage(db, target.id)
+        : containerLineage(db, parentId, [target.id]);
+}
+export async function citedObjects(db, target) {
+    if (target.kind === "container")
+        return (await containerTargetLineage(db, target)).map((id) => ({
+            kind: "container",
+            id,
+        }));
+    // Linked containers, containers listing the document before its signed
+    // placement is checked, and a container whose metadata document it is.
+    const placements = [
+        ...(await db
+            .select({ containerId: documentContainerProjection.containerId })
+            .from(documentContainerProjection)
+            .where(eq(documentContainerProjection.documentId, target.id))),
+        ...(await db
+            .select({ containerId: pendingDocumentDiscoveries.containerId })
+            .from(pendingDocumentDiscoveries)
+            .where(eq(pendingDocumentDiscoveries.documentId, target.id))),
+        ...(await db
+            .select({ containerId: containers.id })
+            .from(containers)
+            .where(eq(containers.metadataDocumentId, target.id))),
+    ];
+    const containerIds = new Set();
+    for (const { containerId } of placements)
+        if (containerId)
+            for (const id of await containerLineage(db, containerId))
+                containerIds.add(id);
+    return [
+        { kind: "document", id: target.id },
+        ...[...containerIds].map((id) => ({ kind: "container", id })),
+    ];
+}
+/**
+ * The one organization every local source places the read in. Verified
+ * ownership (stored verified bundles of the target and of the containers on
+ * its walk, and a document's verified discovery head) and local placement
+ * (listed container rows reached through links, pending listings, metadata,
+ * or parents) must all agree: any disagreement, or no source at all, yields
+ * null, so the read is sent with no hints rather than another
+ * organization's.
+ */
+export async function targetOrganization(db, target, objects) {
+    const containerIds = objects
+        .filter((object) => object.kind === "container")
+        .map((object) => object.id);
+    const listed = containerIds.length === 0
+        ? []
+        : await db
+            .select({ organizationId: containers.organizationId })
+            .from(containers)
+            .where(inArray(containers.id, containerIds));
+    const verifiedContainers = containerIds.length === 0
+        ? []
+        : await db
+            .select({ organizationId: bundles.organizationId })
+            .from(bundles)
+            .where(and(eq(bundles.objectKind, "container"), inArray(bundles.objectId, containerIds)));
+    const verifiedTarget = await db
+        .select({ organizationId: bundles.organizationId })
+        .from(bundles)
+        .where(and(eq(bundles.objectKind, target.kind), eq(bundles.objectId, target.id)));
+    const discovered = target.kind === "document"
+        ? await db
+            .select({ organizationId: documentDiscoveryHeads.organizationId })
+            .from(documentDiscoveryHeads)
+            .where(eq(documentDiscoveryHeads.documentId, target.id))
+        : [];
+    // The listing that placed an unstored container must agree as well.
+    const listing = target.listing ? [target.listing] : [];
+    const sources = [
+        listed,
+        verifiedContainers,
+        verifiedTarget,
+        discovered,
+        listing,
+    ];
+    const organizations = new Set(sources.flat().map((row) => row.organizationId));
+    const [organizationId] = organizations;
+    return organizations.size === 1 && organizationId ? organizationId : null;
+}
+//# sourceMappingURL=citationScope.js.map

package/data/persistence/verifiedCitations/citationScope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"citationScope.js","sourceRoot":"","sources":["citationScope.ts"],"names":[],"mappings":"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","sourcesContent":["import type { WriterProjectionTarget } from \"@tearleads/api-client\";\nimport { MAX_CONTAINER_PATH_LENGTH } from \"@tearleads/validators/util\";\nimport { and, eq, inArray } from \"drizzle-orm\";\nimport { documentContainerProjection } from \"../../sqlite/schema\";\nimport { containers } from \"../../sqlite/schema/containerSchema\";\nimport {\n  documentDiscoveryHeads,\n  pendingDocumentDiscoveries,\n} from \"../../sqlite/schema/documentDiscoveryEvidenceSchema\";\nimport { verifiedAccessManifestBundles as bundles } from \"../../sqlite/schema/verifiedManifestBundleSchema\";\nimport type { ClientSQLiteDatabase } from \"../../sqlite/sqlitePersistenceRuntime\";\n\n/** An object whose verified bytes a projection read may cite. */\nexport interface CitedObject {\n  readonly kind: string;\n  readonly id: string;\n}\n\n/** The requested object first, then each container whose lineage it cites. */\nasync function containerLineage(\n  db: ClientSQLiteDatabase,\n  containerId: string,\n  prefix: readonly string[] = [],\n): Promise<string[]> {\n  const lineage = [...prefix, containerId];\n  while (lineage.length < MAX_CONTAINER_PATH_LENGTH) {\n    const [row] = await db\n      .select({ parentId: containers.parentId })\n      .from(containers)\n      .where(eq(containers.id, lineage.at(-1) ?? \"\"))\n      .limit(1);\n    const parentId = row?.parentId;\n    if (!parentId || lineage.includes(parentId)) break;\n    lineage.push(parentId);\n  }\n  return lineage;\n}\n\n/**\n * A container the device has not stored yet has no local parent, so its\n * listing names one: the lineage continues through the listed parent's\n * stored lineage. A wrong parent only changes which held hashes are cited.\n */\nasync function containerTargetLineage(\n  db: ClientSQLiteDatabase,\n  target: WriterProjectionTarget,\n): Promise<string[]> {\n  const parentId = target.listing?.parentId;\n  if (!parentId || parentId === target.id)\n    return containerLineage(db, target.id);\n  const [stored] = await db\n    .select({ id: containers.id })\n    .from(containers)\n    .where(eq(containers.id, target.id))\n    .limit(1);\n  return stored\n    ? containerLineage(db, target.id)\n    : containerLineage(db, parentId, [target.id]);\n}\n\nexport async function citedObjects(\n  db: ClientSQLiteDatabase,\n  target: WriterProjectionTarget,\n): Promise<{ readonly kind: string; readonly id: string }[]> {\n  if (target.kind === \"container\")\n    return (await containerTargetLineage(db, target)).map((id) => ({\n      kind: \"container\",\n      id,\n    }));\n  // Linked containers, containers listing the document before its signed\n  // placement is checked, and a container whose metadata document it is.\n  const placements = [\n    ...(await db\n      .select({ containerId: documentContainerProjection.containerId })\n      .from(documentContainerProjection)\n      .where(eq(documentContainerProjection.documentId, target.id))),\n    ...(await db\n      .select({ containerId: pendingDocumentDiscoveries.containerId })\n      .from(pendingDocumentDiscoveries)\n      .where(eq(pendingDocumentDiscoveries.documentId, target.id))),\n    ...(await db\n      .select({ containerId: containers.id })\n      .from(containers)\n      .where(eq(containers.metadataDocumentId, target.id))),\n  ];\n  const containerIds = new Set<string>();\n  for (const { containerId } of placements)\n    if (containerId)\n      for (const id of await containerLineage(db, containerId))\n        containerIds.add(id);\n  return [\n    { kind: \"document\", id: target.id },\n    ...[...containerIds].map((id) => ({ kind: \"container\", id })),\n  ];\n}\n\n/**\n * The one organization every local source places the read in. Verified\n * ownership (stored verified bundles of the target and of the containers on\n * its walk, and a document's verified discovery head) and local placement\n * (listed container rows reached through links, pending listings, metadata,\n * or parents) must all agree: any disagreement, or no source at all, yields\n * null, so the read is sent with no hints rather than another\n * organization's.\n */\nexport async function targetOrganization(\n  db: ClientSQLiteDatabase,\n  target: WriterProjectionTarget,\n  objects: readonly { readonly kind: string; readonly id: string }[],\n): Promise<string | null> {\n  const containerIds = objects\n    .filter((object) => object.kind === \"container\")\n    .map((object) => object.id);\n  const listed =\n    containerIds.length === 0\n      ? []\n      : await db\n          .select({ organizationId: containers.organizationId })\n          .from(containers)\n          .where(inArray(containers.id, containerIds));\n  const verifiedContainers =\n    containerIds.length === 0\n      ? []\n      : await db\n          .select({ organizationId: bundles.organizationId })\n          .from(bundles)\n          .where(\n            and(\n              eq(bundles.objectKind, \"container\"),\n              inArray(bundles.objectId, containerIds),\n            ),\n          );\n  const verifiedTarget = await db\n    .select({ organizationId: bundles.organizationId })\n    .from(bundles)\n    .where(\n      and(eq(bundles.objectKind, target.kind), eq(bundles.objectId, target.id)),\n    );\n  const discovered =\n    target.kind === \"document\"\n      ? await db\n          .select({ organizationId: documentDiscoveryHeads.organizationId })\n          .from(documentDiscoveryHeads)\n          .where(eq(documentDiscoveryHeads.documentId, target.id))\n      : [];\n  // The listing that placed an unstored container must agree as well.\n  const listing = target.listing ? [target.listing] : [];\n  const sources = [\n    listed,\n    verifiedContainers,\n    verifiedTarget,\n    discovered,\n    listing,\n  ];\n  const organizations = new Set(\n    sources.flat().map((row) => row.organizationId),\n  );\n  const [organizationId] = organizations;\n  return organizations.size === 1 && organizationId ? organizationId : null;\n}\n"]}

package/data/persistence/verifiedCitations/kekLevelCitations.d.ts

@@ -0,0 +1,33 @@
+import { type ContainerKekWireLevel } from "../../../internal/validators/response/index.js";
+/**
+ * Typed rows in the verified-bundle cache that hold one container KEK level
+ * each. `manifestHash` (the cache key) and `bundleDigest` are the level's
+ * citation digest, the SHA-256 of `bundleJson`, its canonical wire bytes;
+ * `objectId` and `epoch` are the level's container and key epoch.
+ */
+export declare const KEK_LEVEL_OBJECT_KIND = "container-kek-level";
+/** A KEK level a projection verification accepted, with its organization. */
+export interface VerifiedKekLevel {
+    readonly kekLevel: ContainerKekWireLevel;
+    readonly organizationId: string;
+}
+export interface KekLevelRow {
+    readonly manifestHash: string;
+    readonly organizationId: string;
+    readonly objectKind: string;
+    readonly objectId: string;
+    readonly epoch: number;
+    readonly bundleJson: string;
+    readonly bundleDigest: string;
+}
+/** Null when the level has no canonical form; such a level is not cited. */
+export declare function kekLevelRow({ kekLevel, organizationId, }: VerifiedKekLevel): Promise<KekLevelRow | null>;
+/**
+ * The stored level, or null for a damaged row: its bytes must parse as a
+ * full KEK level whose recomputed digest is the row's key.
+ */
+export declare function readStoredKekLevel(row: {
+    readonly bundleDigest: string;
+    readonly bundleJson: string;
+    readonly manifestHash: string;
+}): Promise<ContainerKekWireLevel | null>;

package/data/persistence/verifiedCitations/kekLevelCitations.js

@@ -0,0 +1,44 @@
+import { computeContainerKekLevelDigest, readKeyingCanonicalJson, serializeKeyingCanonicalJson, } from "../../../internal/crypto/index.js";
+import { isContainerKekWireLevel, } from "../../../internal/validators/response/index.js";
+/**
+ * Typed rows in the verified-bundle cache that hold one container KEK level
+ * each. `manifestHash` (the cache key) and `bundleDigest` are the level's
+ * citation digest, the SHA-256 of `bundleJson`, its canonical wire bytes;
+ * `objectId` and `epoch` are the level's container and key epoch.
+ */
+export const KEK_LEVEL_OBJECT_KIND = "container-kek-level";
+/** Null when the level has no canonical form; such a level is not cited. */
+export async function kekLevelRow({ kekLevel, organizationId, }) {
+    const digest = await computeContainerKekLevelDigest(kekLevel);
+    if (digest === null)
+        return null;
+    return {
+        manifestHash: digest,
+        organizationId,
+        objectKind: KEK_LEVEL_OBJECT_KIND,
+        objectId: kekLevel.containerId,
+        epoch: kekLevel.containerKeyEpoch,
+        // Canonical: the digest above is the SHA-256 of exactly these bytes.
+        bundleJson: serializeKeyingCanonicalJson(readKeyingCanonicalJson(kekLevel, "Verified KEK level")),
+        bundleDigest: digest,
+    };
+}
+/**
+ * The stored level, or null for a damaged row: its bytes must parse as a
+ * full KEK level whose recomputed digest is the row's key.
+ */
+export async function readStoredKekLevel(row) {
+    if (row.bundleDigest !== row.manifestHash)
+        return null;
+    try {
+        const level = JSON.parse(row.bundleJson);
+        return isContainerKekWireLevel(level) &&
+            (await computeContainerKekLevelDigest(level)) === row.manifestHash
+            ? level
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=kekLevelCitations.js.map

package/data/persistence/verifiedCitations/kekLevelCitations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kekLevelCitations.js","sourceRoot":"","sources":["kekLevelCitations.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,4BAA4B,GAC7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,uBAAuB,GACxB,MAAM,gCAAgC,CAAC;AAExC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAAqB,CAAC;AAkB3D,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,QAAQ,EACR,cAAc,GACG;IACjB,MAAM,MAAM,GAAG,MAAM,8BAA8B,CAAC,QAAQ,CAAC,CAAC;IAC9D,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACjC,OAAO;QACL,YAAY,EAAE,MAAM;QACpB,cAAc;QACd,UAAU,EAAE,qBAAqB;QACjC,QAAQ,EAAE,QAAQ,CAAC,WAAW;QAC9B,KAAK,EAAE,QAAQ,CAAC,iBAAiB;QACjC,qEAAqE;QACrE,UAAU,EAAE,4BAA4B,CACtC,uBAAuB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CACxD;QACD,YAAY,EAAE,MAAM;KACrB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAIxC;IACC,IAAI,GAAG,CAAC,YAAY,KAAK,GAAG,CAAC,YAAY;QAAE,OAAO,IAAI,CAAC;IACvD,IAAI,CAAC;QACH,MAAM,KAAK,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAClD,OAAO,uBAAuB,CAAC,KAAK,CAAC;YACnC,CAAC,MAAM,8BAA8B,CAAC,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,YAAY;YAClE,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,IAAI,CAAC;IACX,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import {\n  computeContainerKekLevelDigest,\n  readKeyingCanonicalJson,\n  serializeKeyingCanonicalJson,\n} from \"@tearleads/crypto\";\nimport {\n  type ContainerKekWireLevel,\n  isContainerKekWireLevel,\n} from \"@tearleads/validators/response\";\n\n/**\n * Typed rows in the verified-bundle cache that hold one container KEK level\n * each. `manifestHash` (the cache key) and `bundleDigest` are the level's\n * citation digest, the SHA-256 of `bundleJson`, its canonical wire bytes;\n * `objectId` and `epoch` are the level's container and key epoch.\n */\nexport const KEK_LEVEL_OBJECT_KIND = \"container-kek-level\";\n\n/** A KEK level a projection verification accepted, with its organization. */\nexport interface VerifiedKekLevel {\n  readonly kekLevel: ContainerKekWireLevel;\n  readonly organizationId: string;\n}\n\nexport interface KekLevelRow {\n  readonly manifestHash: string;\n  readonly organizationId: string;\n  readonly objectKind: string;\n  readonly objectId: string;\n  readonly epoch: number;\n  readonly bundleJson: string;\n  readonly bundleDigest: string;\n}\n\n/** Null when the level has no canonical form; such a level is not cited. */\nexport async function kekLevelRow({\n  kekLevel,\n  organizationId,\n}: VerifiedKekLevel): Promise<KekLevelRow | null> {\n  const digest = await computeContainerKekLevelDigest(kekLevel);\n  if (digest === null) return null;\n  return {\n    manifestHash: digest,\n    organizationId,\n    objectKind: KEK_LEVEL_OBJECT_KIND,\n    objectId: kekLevel.containerId,\n    epoch: kekLevel.containerKeyEpoch,\n    // Canonical: the digest above is the SHA-256 of exactly these bytes.\n    bundleJson: serializeKeyingCanonicalJson(\n      readKeyingCanonicalJson(kekLevel, \"Verified KEK level\"),\n    ),\n    bundleDigest: digest,\n  };\n}\n\n/**\n * The stored level, or null for a damaged row: its bytes must parse as a\n * full KEK level whose recomputed digest is the row's key.\n */\nexport async function readStoredKekLevel(row: {\n  readonly bundleDigest: string;\n  readonly bundleJson: string;\n  readonly manifestHash: string;\n}): Promise<ContainerKekWireLevel | null> {\n  if (row.bundleDigest !== row.manifestHash) return null;\n  try {\n    const level: unknown = JSON.parse(row.bundleJson);\n    return isContainerKekWireLevel(level) &&\n      (await computeContainerKekLevelDigest(level)) === row.manifestHash\n      ? level\n      : null;\n  } catch {\n    return null;\n  }\n}\n"]}

package/data/persistence/verifiedManifestBundlePersistence.d.ts

@@ -1,14 +1,15 @@
-import type { VerifiedManifestCitations, WriterProjectionTarget } from "../../internal/api-client/index.js";
+import type { HeldProjectionCitation, VerifiedManifestCitations, WriterProjectionTarget } from "../../internal/api-client/index.js";
 import { type AccessManifestBundleWireResponse } from "../../internal/validators/response/index.js";
 import { verifiedAccessManifestBundles as bundles } from "../sqlite/schema/verifiedManifestBundleSchema.js";
 import { type ClientSQLiteTransactionScope } from "../sqlite/sqlitePersistenceRuntime.js";
 import { type ExecSql } from "../sqlite/sqlSchema.js";
+import { type VerifiedKekLevel } from "./verifiedCitations/kekLevelCitations.js";
 /**
  * Bounds local bytes (a bundle is ~10–20 KB). Evicting the least recently
  * verified rows only makes a later read carry those bundles again.
  */
 export declare const MAX_VERIFIED_MANIFEST_BUNDLES = 1024;
-export interface VerifiedManifestBundle {
+interface VerifiedBundle {
     readonly bundle: AccessManifestBundleWireResponse;
     readonly checkpoint: {
         readonly objectKind: string;
@@ -17,12 +18,14 @@ export interface VerifiedManifestBundle {
         readonly epoch: number;
     };
 }
+/** Bytes a projection verification accepted: a bundle or a KEK level. */
+export type VerifiedManifestBundle = VerifiedBundle | VerifiedKekLevel;
 /** A verified bundle's exact JSON and that JSON's digest. */
 export type VerifiedManifestBundleRow = Omit<typeof bundles.$inferInsert, "verifiedAt">;
 /**
- * Prepares rows for bundles that just passed projection verification. The
- * digests are computed here, before the checkpoint transaction that writes
- * them begins.
+ * Prepares rows for bundles and KEK levels that just passed projection
+ * verification. The digests are computed here, before the checkpoint
+ * transaction that writes them begins.
  */
 export declare function verifiedManifestBundleRows(entries: readonly VerifiedManifestBundle[]): Promise<VerifiedManifestBundleRow[]>;
 /**
@@ -33,15 +36,17 @@ export declare function verifiedManifestBundleRows(entries: readonly VerifiedMan
  */
 export declare function writeVerifiedManifestBundlesInTransaction(tx: ClientSQLiteTransactionScope, rows: readonly VerifiedManifestBundleRow[], verifiedAt: string): Promise<void>;
 /**
- * Verified bundles of the target's object and of the containers its
- * projection walks, newest epochs first; then the most recently verified rows
- * of its organization, since a just-verified parent is the likeliest part of
- * a new child's projection. Citations never leave the target's organization:
- * an object whose organization the device cannot place cites nothing.
- * Damaged rows are dropped.
+ * The latest verified KEK level of each container the target's projection
+ * walks; then verified bundles of those objects, newest epochs first; then
+ * the most recently verified bundles of its organization, since a
+ * just-verified parent is the likeliest part of a new child's projection.
+ * Citations never leave the target's organization: an object whose
+ * organization the device cannot place cites nothing. Damaged rows are
+ * dropped.
  */
-export declare function loadVerifiedManifestCitations(execSql: ExecSql, target: WriterProjectionTarget, limit?: number): Promise<AccessManifestBundleWireResponse[]>;
+export declare function loadVerifiedManifestCitations(execSql: ExecSql, target: WriterProjectionTarget, limit?: number): Promise<HeldProjectionCitation[]>;
 /** Cites from whichever database the signed-in identity currently uses. */
 export declare function createVerifiedManifestCitations(resolveExecSql: () => ExecSql | null): VerifiedManifestCitations;
 /** Drops an organization's verified bundles when a remote reset forgets it. */
 export declare function deleteVerifiedManifestBundlesForOrganization(tx: ClientSQLiteTransactionScope, organizationId: string): Promise<void>;
+export {};

package/data/persistence/verifiedManifestBundlePersistence.js

@@ -1,15 +1,15 @@
 import { toFingerprint } from "../../internal/crypto/index.js";
 import { isAccessManifestBundleWireResponse, } from "../../internal/validators/response/index.js";
-import { KNOWN_MANIFEST_HINT_LIMIT, MAX_CONTAINER_PATH_LENGTH, } from "../../internal/validators/util/index.js";
-import { and, asc, desc, eq, inArray, sql } from "drizzle-orm";
-import { containerTables, documentContainerProjection, documentContainerProjectionTables, } from "../sqlite/schema/index.js";
-import { containers } from "../sqlite/schema/containerSchema.js";
-import { documentDiscoveryHeads, pendingDocumentDiscoveries, } from "../sqlite/schema/documentDiscoveryEvidenceSchema.js";
+import { KNOWN_MANIFEST_HINT_LIMIT } from "../../internal/validators/util/index.js";
+import { and, asc, desc, eq, inArray, ne, notInArray, sql } from "drizzle-orm";
+import { containerTables, documentContainerProjectionTables, } from "../sqlite/schema/index.js";
 import { verifiedAccessManifestBundles as bundles, verifiedManifestBundleTables, } from "../sqlite/schema/verifiedManifestBundleSchema.js";
 import { sqliteInsertBatchSize } from "../sqlite/sqliteBindBudget.js";
 import { getClientSQLitePersistenceRuntime, } from "../sqlite/sqlitePersistenceRuntime.js";
 import { excludedValue } from "../sqlite/sqliteUpsert.js";
 import { ensureSqlTables } from "../sqlite/sqlSchema.js";
+import { citedObjects, targetOrganization, } from "./verifiedCitations/citationScope.js";
+import { KEK_LEVEL_OBJECT_KIND, kekLevelRow, readStoredKekLevel, } from "./verifiedCitations/kekLevelCitations.js";
 /**
  * Bounds local bytes (a bundle is ~10–20 KB). Evicting the least recently
  * verified rows only makes a later read carry those bundles again.
@@ -43,11 +43,29 @@ async function pruneInTransaction(tx) {
         await tx.delete(bundles).where(inArray(bundles.manifestHash, batch)).run();
 }
 /**
- * Prepares rows for bundles that just passed projection verification. The
- * digests are computed here, before the checkpoint transaction that writes
- * them begins.
+ * Prepares rows for bundles and KEK levels that just passed projection
+ * verification. The digests are computed here, before the checkpoint
+ * transaction that writes them begins.
  */
-export function verifiedManifestBundleRows(entries) {
+export async function verifiedManifestBundleRows(entries) {
+    const bundleEntries = [];
+    const levelEntries = [];
+    for (const entry of entries)
+        if ("kekLevel" in entry)
+            levelEntries.push(entry);
+        else
+            bundleEntries.push(entry);
+    // One level per container: its newest epoch, the last one seen on a tie.
+    const levelRows = new Map();
+    for (const level of levelEntries) {
+        const row = await kekLevelRow(level);
+        const held = row && levelRows.get(row.objectId);
+        if (row && (!held || held.epoch <= row.epoch))
+            levelRows.set(row.objectId, row);
+    }
+    return [...(await bundleRows(bundleEntries)), ...levelRows.values()];
+}
+function bundleRows(entries) {
     const unique = new Map(entries.map((entry) => [entry.bundle.manifestHash, entry]));
     return Promise.all([...unique.values()].map(async ({ bundle, checkpoint }) => {
         const bundleJson = JSON.stringify(bundle);
@@ -101,8 +119,21 @@ export async function writeVerifiedManifestBundlesInTransaction(tx, rows, verifi
             },
         })
             .run();
+    await dropSupersededKekLevels(tx, rows);
     await pruneInTransaction(tx);
 }
+/**
+ * A container keeps only its latest verified level: the API serves its
+ * current level, so an older one can never be cited usefully again.
+ */
+async function dropSupersededKekLevels(tx, rows) {
+    const levels = rows.filter((row) => row.objectKind === KEK_LEVEL_OBJECT_KIND);
+    for (const batch of batches(levels))
+        await tx
+            .delete(bundles)
+            .where(and(eq(bundles.objectKind, KEK_LEVEL_OBJECT_KIND), inArray(bundles.objectId, batch.map((row) => row.objectId)), notInArray(bundles.manifestHash, batch.map((row) => row.manifestHash))))
+            .run();
+}
 async function storedDigests(tx, manifestHashes) {
     const digests = new Map();
     for (const batch of batches(manifestHashes)) {
@@ -118,94 +149,6 @@ async function storedDigests(tx, manifestHashes) {
     }
     return digests;
 }
-/** The requested object first, then each container whose lineage it cites. */
-async function containerLineage(db, containerId) {
-    const lineage = [containerId];
-    while (lineage.length < MAX_CONTAINER_PATH_LENGTH) {
-        const [row] = await db
-            .select({ parentId: containers.parentId })
-            .from(containers)
-            .where(eq(containers.id, lineage.at(-1) ?? ""))
-            .limit(1);
-        const parentId = row?.parentId;
-        if (!parentId || lineage.includes(parentId))
-            break;
-        lineage.push(parentId);
-    }
-    return lineage;
-}
-async function citedObjects(db, target) {
-    if (target.kind === "container")
-        return (await containerLineage(db, target.id)).map((id) => ({
-            kind: "container",
-            id,
-        }));
-    // Linked containers, containers listing the document before its signed
-    // placement is checked, and a container whose metadata document it is.
-    const placements = [
-        ...(await db
-            .select({ containerId: documentContainerProjection.containerId })
-            .from(documentContainerProjection)
-            .where(eq(documentContainerProjection.documentId, target.id))),
-        ...(await db
-            .select({ containerId: pendingDocumentDiscoveries.containerId })
-            .from(pendingDocumentDiscoveries)
-            .where(eq(pendingDocumentDiscoveries.documentId, target.id))),
-        ...(await db
-            .select({ containerId: containers.id })
-            .from(containers)
-            .where(eq(containers.metadataDocumentId, target.id))),
-    ];
-    const containerIds = new Set();
-    for (const { containerId } of placements)
-        if (containerId)
-            for (const id of await containerLineage(db, containerId))
-                containerIds.add(id);
-    return [
-        { kind: "document", id: target.id },
-        ...[...containerIds].map((id) => ({ kind: "container", id })),
-    ];
-}
-/**
- * The one organization every local source places the read in. Verified
- * ownership (stored verified bundles of the target and of the containers on
- * its walk, and a document's verified discovery head) and local placement
- * (listed container rows reached through links, pending listings, metadata,
- * or parents) must all agree: any disagreement, or no source at all, yields
- * null, so the read is sent with no hints rather than another
- * organization's.
- */
-async function targetOrganization(db, target, objects) {
-    const containerIds = objects
-        .filter((object) => object.kind === "container")
-        .map((object) => object.id);
-    const listed = containerIds.length === 0
-        ? []
-        : await db
-            .select({ organizationId: containers.organizationId })
-            .from(containers)
-            .where(inArray(containers.id, containerIds));
-    const verifiedContainers = containerIds.length === 0
-        ? []
-        : await db
-            .select({ organizationId: bundles.organizationId })
-            .from(bundles)
-            .where(and(eq(bundles.objectKind, "container"), inArray(bundles.objectId, containerIds)));
-    const verifiedTarget = await db
-        .select({ organizationId: bundles.organizationId })
-        .from(bundles)
-        .where(and(eq(bundles.objectKind, target.kind), eq(bundles.objectId, target.id)));
-    const discovered = target.kind === "document"
-        ? await db
-            .select({ organizationId: documentDiscoveryHeads.organizationId })
-            .from(documentDiscoveryHeads)
-            .where(eq(documentDiscoveryHeads.documentId, target.id))
-        : [];
-    const sources = [listed, verifiedContainers, verifiedTarget, discovered];
-    const organizations = new Set(sources.flat().map((row) => row.organizationId));
-    const [organizationId] = organizations;
-    return organizations.size === 1 && organizationId ? organizationId : null;
-}
 const storedColumns = {
     bundleDigest: bundles.bundleDigest,
     bundleJson: bundles.bundleJson,
@@ -237,17 +180,36 @@ function recentRows(db, organizationId, limit) {
     return db
         .select(storedColumns)
         .from(bundles)
-        .where(eq(bundles.organizationId, organizationId))
+        .where(and(eq(bundles.organizationId, organizationId), ne(bundles.objectKind, KEK_LEVEL_OBJECT_KIND)))
         .orderBy(desc(bundles.verifiedAt), asc(bundles.manifestHash))
         .limit(limit);
 }
+/** The latest verified KEK level of each container, in lineage order. */
+async function lineageKekLevels(db, organizationId, objects) {
+    const containerIds = objects
+        .filter((object) => object.kind === "container")
+        .map((object) => object.id);
+    if (containerIds.length === 0)
+        return [];
+    const rows = await db
+        .select({ ...storedColumns, objectId: bundles.objectId })
+        .from(bundles)
+        .where(and(eq(bundles.organizationId, organizationId), eq(bundles.objectKind, KEK_LEVEL_OBJECT_KIND), inArray(bundles.objectId, containerIds)))
+        .orderBy(desc(bundles.epoch), desc(bundles.verifiedAt));
+    const latest = new Map();
+    for (const row of rows)
+        if (!latest.has(row.objectId))
+            latest.set(row.objectId, row);
+    return containerIds.flatMap((id) => latest.get(id) ?? []);
+}
 /**
- * Verified bundles of the target's object and of the containers its
- * projection walks, newest epochs first; then the most recently verified rows
- * of its organization, since a just-verified parent is the likeliest part of
- * a new child's projection. Citations never leave the target's organization:
- * an object whose organization the device cannot place cites nothing.
- * Damaged rows are dropped.
+ * The latest verified KEK level of each container the target's projection
+ * walks; then verified bundles of those objects, newest epochs first; then
+ * the most recently verified bundles of its organization, since a
+ * just-verified parent is the likeliest part of a new child's projection.
+ * Citations never leave the target's organization: an object whose
+ * organization the device cannot place cites nothing. Damaged rows are
+ * dropped.
  */
 export async function loadVerifiedManifestCitations(execSql, target, limit = KNOWN_MANIFEST_HINT_LIMIT) {
     await ensureSqlTables(execSql, [
@@ -273,6 +235,15 @@ export async function loadVerifiedManifestCitations(execSql, target, limit = KNO
     const organizationId = await targetOrganization(db, target, objects);
     if (organizationId === null)
         return [];
+    for (const row of await lineageKekLevels(db, organizationId, objects)) {
+        if (cited.size >= limit)
+            break;
+        const level = await readStoredKekLevel(row);
+        if (level)
+            cited.set(row.manifestHash, level);
+        else
+            damaged.push(row.manifestHash);
+    }
     for (const object of objects)
         if (cited.size < limit)
             await collect(await objectRows(db, organizationId, object, limit - cited.size));