diff --git a/scripts/proposals/catalog-retained-selection/README.md b/scripts/proposals/catalog-retained-selection/README.md new file mode 100644 index 000000000..b85119232 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/README.md @@ -0,0 +1,52 @@ +# Retained-field selection and inner consumer — inactive source proposal + +This implements the existing `catalog-field-consumer-2207.md` inner contract only. +It is outside app/lib and routes. Missing authority ports return unavailable. +No SQL wrapper, grant, source write, Context identity creation, environment flag, +UI schema-v1 extension or outer wire version is supplied. Frozen raw-report +API1290/Database142 are a different source path and are unchanged. + +`readRetainedFieldSelection` calls an injected current command reconciler with the +original authenticated actor, workspace, request, catalog and retention key. The +intended backing function is the private, source-only Database proposal +[`stream_binding_proposal.reconcile_retention`](https://github.com/recoupable/database/blob/1b892dd2671ba7e15e0c44b690fbfbe515b59fbd/proposals/stream-retention-writer-2207/writer.sql#L3), +which rechecks `read_binding`. It is not implemented or connected as a live API +transport here; the injected callback alone supplies no authentication proof. +The adapter validates the exact receipt/scope/key and projects its +genuine Context identities. Null, pending, malformed, mismatched or ambiguous +results cannot create a ready selection; operational errors are redacted errors. +No retain/expand/provider call, latest lookup, re-key or raw-report fallback exists. +This projection supplies a selection, not a currentness lease. + +`consumeRetainedField` accepts only the explicit retained_field request and server +actor/session/chat/assistant context. The injected transaction port must authorize +that complete scope, pre-lock the whole batch in a qualified stable order, read +each exact selection using the existing source family, and keep locks through +callback evaluation. No production port is implemented here. Passing mocked data +to that trusted port does not prove source authorization. The actor is never +substituted with owner/workspace. Maximum eight unique subjects; all-or-nothing +refusal, exact registered method/query, current_streams only, 32KiB output cap. +It calls the existing pinned evaluator, then strips raw observations and identifiers +outside the inner projection contract. Unknown has no amount key; zero stays zero. +Caller order is preserved; the port receives a separate subject-sorted lock list. + +The generated `fixtures/fieldContext.json` is the ready inner response without +`state`, as specified by the consumer contract. It is synthetic evidence for UI's +explicitly versioned offline envelope; no outer version is invented here. UI owns +projection/collection/text agreement and capability negotiation. This increment +returns typed values but does not implement a renderer or any disclosure path. + +Pure tests run the actual selection adapter and evaluator with synthetic authority +ports, including withheld values on stale/missing/withdrawn boundary simulations. +The Database companion extends the actual existing retained-field integration +harness with a deferred current reconcile/read consumer. Those PostgreSQL scenarios +are not run under the SQL hold. Simulated refusal labels do not prove actual +withdrawal, memberships, transaction liveness or concurrent batch correctness. + +Remaining runtime gates: real selection-source transport, actor/session/chat scope, +reserved-family writer enforcement, callable held-transaction evaluator transport, +qualified batch lock order, UI-owned envelope, and current authorization on initial +delivery/replay/persistence/history/reconnect/text/export/model reads. A successful +journaled preparation cannot authorize later disclosure; deny both typed values and +numeric/text projections together. No recomputation or new version under the same +saved source revision. The ordinary report stays separate and is never a fallback. diff --git a/scripts/proposals/catalog-retained-selection/classifyRetainedFieldRefusal.ts b/scripts/proposals/catalog-retained-selection/classifyRetainedFieldRefusal.ts new file mode 100644 index 000000000..e9f9bb0c4 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/classifyRetainedFieldRefusal.ts @@ -0,0 +1,8 @@ +/** Preserve contract failure classes while exposing no source details or values. */ +export function classifyRetainedFieldRefusal(reason: string): { + state: "invalid" | "error" | "unavailable"; +} { + if (reason === "size_limit") return { state: "invalid" }; + if (reason === "helper_changed" || reason === "source_error") return { state: "error" }; + return { state: "unavailable" }; +} diff --git a/scripts/proposals/catalog-retained-selection/consumeRetainedField.ts b/scripts/proposals/catalog-retained-selection/consumeRetainedField.ts new file mode 100644 index 000000000..5a76ea6e8 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/consumeRetainedField.ts @@ -0,0 +1,93 @@ +import { z } from "zod"; +import { evaluateRetainedStreamField } from "../catalog-stream-fields/evaluate"; +import { actorScopeSchema, requestSchema } from "./schemas"; +import type { Item, Ready, Result, LockedRead } from "./retainedFieldTypes"; +import { classifyRetainedFieldRefusal } from "./classifyRetainedFieldRefusal"; +/** Inactive source consumer; no report fallback, disclosure route, transport or UI schema change. */ +export async function consumeRetainedField( + actorInput: unknown, + input: unknown, + withLockedRead?: LockedRead, +): Promise { + const actor = actorScopeSchema.safeParse(actorInput); + const request = requestSchema.safeParse(input); + if (!actor.success || !request.success) return { state: "invalid" }; + if (!withLockedRead) return { state: "unavailable" }; + const q = request.data; + try { + return await withLockedRead( + { + ...actor.data, + workspaceId: q.workspaceId, + catalogId: q.catalogId, + selections: [...q.selections].sort((a, b) => a.subjectId.localeCompare(b.subjectId)), + }, + async tx => { + if ( + !z.iso.datetime({ offset: true }).safeParse(tx.asOf).success || + !Number.isFinite(Date.parse(tx.asOf)) + ) + return { state: "error" }; + const items: Item[] = []; + for (const selection of q.selections) { + const envelope = await tx.readBinding(selection); + if (envelope === null || envelope === undefined) return { state: "unavailable" }; + const result = evaluateRetainedStreamField({ + operation: "read_field", + recipe: q.method.recipe, + field: q.field, + selection: { ...selection, query: q.query }, + asOf: tx.asOf, + boundary: { state: "qualified", envelope }, + }); + if (result.state !== "ready") return classifyRetainedFieldRefusal(result.reason); + const comparisonState = result.coverage.comparisonState; + if (comparisonState !== "comparable" && comparisonState !== "incomplete") + return { state: "error" }; + const { authority, kind } = result.ref; + if (authority !== "context" || kind !== "recording") return { state: "error" }; + const amount = result.field.amount; + if (amount !== null && (!Number.isSafeInteger(amount) || amount < 0)) + return { state: "unavailable" }; + items.push({ + ref: { ...result.ref, authority, kind }, + binding: selection, + value: amount === null ? { state: "unknown" } : { state: "known", amount }, + periods: result.periods, + coverage: { + comparisonState, + absentDateCount: result.coverage.absentDates.length, + nullDateCount: result.coverage.nullDates.length, + missingDateCount: result.coverage.missingDays.length, + }, + source: { + provider: result.provenance.provider, + metric: result.provenance.metric, + platform: result.provenance.platform, + territory: result.provenance.territory, + timezone: result.provenance.timezone, + retrievalRange: result.provenance.retrievalRange, + }, + }); + } + const ready: Ready = { + state: "ready", + contract: "catalog-retained-field-projection/1", + workspaceId: q.workspaceId, + catalogId: q.catalogId, + field: q.field, + method: q.method, + query: q.query, + asOf: tx.asOf, + semantics: "historical_snapshot", + items, + }; + return Buffer.byteLength(JSON.stringify(ready), "utf8") > 32768 + ? { state: "invalid" } + : ready; + }, + ); + } catch { + return { state: "error" }; + } +} diff --git a/scripts/proposals/catalog-retained-selection/fixtures/fieldContext.json b/scripts/proposals/catalog-retained-selection/fixtures/fieldContext.json new file mode 100644 index 000000000..c53e71597 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/fixtures/fieldContext.json @@ -0,0 +1,77 @@ +{ + "contract": "catalog-retained-field-projection/1", + "workspaceId": "10000000-0000-4000-8000-000000000001", + "catalogId": "10000000-0000-4000-8000-000000000003", + "field": "current_streams", + "method": { + "recipe": "catalog-retained-stream-fields/1", + "recipeHash": "65a06a785aa496e1232fe3a9f1606595f19c1a152b710ca30c4c06612f01864a", + "evaluatorSha256": "163563e15dd92d473aa51899c54c96300f20d27072b83e39ffb01c84f3adc64e", + "helperSha256": "91dcca66c8dec0851c1f6e110257a63b730e9b7ae33a60bceb0e9ffcf318dd81" + }, + "query": { + "since": "2026-10-24", + "days": 1, + "timezone": "UTC" + }, + "asOf": "2026-10-27T00:00:00Z", + "semantics": "historical_snapshot", + "items": [ + { + "ref": { + "workspaceId": "10000000-0000-4000-8000-000000000001", + "authority": "context", + "kind": "recording", + "id": "10000000-0000-4000-8000-000000000004", + "sourceVersionIds": [ + "10000000-0000-4000-8000-000000000006" + ] + }, + "binding": { + "ownerId": "10000000-0000-4000-8000-000000000001", + "requestId": "10000000-0000-4000-8000-000000000002", + "subjectId": "10000000-0000-4000-8000-000000000004", + "catalogId": "10000000-0000-4000-8000-000000000003", + "resultId": "10000000-0000-4000-8000-000000000005", + "revision": 7, + "topic": "catalog_retained_streams", + "sourceVersionIds": [ + "10000000-0000-4000-8000-000000000006" + ] + }, + "value": { + "state": "known", + "amount": 100 + }, + "periods": { + "previous": { + "start": "2026-10-23", + "end_exclusive": "2026-10-24" + }, + "current": { + "start": "2026-10-24", + "end_exclusive": "2026-10-25" + }, + "days": 1, + "timezone": "UTC" + }, + "coverage": { + "comparisonState": "comparable", + "absentDateCount": 0, + "nullDateCount": 0, + "missingDateCount": 0 + }, + "source": { + "provider": "luminate", + "metric": "daily_streams", + "platform": "all_dsps", + "territory": "worldwide", + "timezone": "UTC", + "retrievalRange": { + "earliest": "2026-10-25T01:00:00Z", + "latest": "2026-10-25T01:00:00Z" + } + } + } + ] +} diff --git a/scripts/proposals/catalog-retained-selection/fixtures/synthetic-authority-input.json b/scripts/proposals/catalog-retained-selection/fixtures/synthetic-authority-input.json new file mode 100644 index 000000000..a9d4b6cf9 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/fixtures/synthetic-authority-input.json @@ -0,0 +1,99 @@ +{ + "scope": { + "actorId": "10000000-0000-4000-8000-000000000009", + "workspaceId": "10000000-0000-4000-8000-000000000001", + "requestId": "10000000-0000-4000-8000-000000000002", + "catalogId": "10000000-0000-4000-8000-000000000003", + "key": "original" + }, + "actor": { + "actorId": "10000000-0000-4000-8000-000000000009", + "sessionId": "session", + "chatId": "chat", + "messageId": "assistant" + }, + "receipt": { + "ownerId": "10000000-0000-4000-8000-000000000001", + "requestId": "10000000-0000-4000-8000-000000000002", + "subjectId": "10000000-0000-4000-8000-000000000004", + "catalogId": "10000000-0000-4000-8000-000000000003", + "key": "original", + "commandDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "resultId": "10000000-0000-4000-8000-000000000005", + "sourceVersionId": "10000000-0000-4000-8000-000000000006", + "revision": 7 + }, + "envelope": { + "ownerId": "10000000-0000-4000-8000-000000000001", + "requestId": "10000000-0000-4000-8000-000000000002", + "subjectId": "10000000-0000-4000-8000-000000000004", + "catalogId": "10000000-0000-4000-8000-000000000003", + "resultId": "10000000-0000-4000-8000-000000000005", + "revision": 7, + "topic": "catalog_retained_streams", + "sourceVersionIds": [ + "10000000-0000-4000-8000-000000000006" + ], + "evidence": { + "schemaVersion": 1, + "workspaceId": "10000000-0000-4000-8000-000000000001", + "catalogId": "10000000-0000-4000-8000-000000000003", + "subjectId": "10000000-0000-4000-8000-000000000004", + "isrc": "USAAA2600001", + "provider": "luminate", + "metric": "daily_streams", + "platform": "all_dsps", + "territory": "worldwide", + "timezone": "UTC", + "since": "2026-10-23", + "until": "2026-10-25", + "periods": { + "previous": { + "start": "2026-10-23", + "end_exclusive": "2026-10-24" + }, + "current": { + "start": "2026-10-24", + "end_exclusive": "2026-10-25" + }, + "days": 1, + "timezone": "UTC" + }, + "providerRecordingId": "provider-original", + "observations": [ + { + "catalog_id": "10000000-0000-4000-8000-000000000003", + "isrc": "USAAA2600001", + "date": "2026-10-23", + "run_id": "10000000-0000-4000-8000-000000000007", + "provider_recording_id": "provider-original", + "streams": 50, + "source_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "retrieved_at": "2026-10-25T01:00:00Z" + }, + { + "catalog_id": "10000000-0000-4000-8000-000000000003", + "isrc": "USAAA2600001", + "date": "2026-10-24", + "run_id": "10000000-0000-4000-8000-000000000007", + "provider_recording_id": "provider-original", + "streams": 100, + "source_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "retrieved_at": "2026-10-25T01:00:00Z" + } + ], + "absentDates": [], + "nullDates": [], + "retrievalRange": { + "earliest": "2026-10-25T01:00:00Z", + "latest": "2026-10-25T01:00:00Z" + } + } + }, + "query": { + "since": "2026-10-24", + "days": 1, + "timezone": "UTC" + }, + "asOf": "2026-10-27T00:00:00Z" +} diff --git a/scripts/proposals/catalog-retained-selection/readRetainedFieldSelection.ts b/scripts/proposals/catalog-retained-selection/readRetainedFieldSelection.ts new file mode 100644 index 000000000..211469d49 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/readRetainedFieldSelection.ts @@ -0,0 +1,39 @@ +import { commandScopeSchema, receiptSchema, type CommandScope, type Selection } from "./schemas"; +/** Proposal only. Reconcile is the existing current-authorized command read, not a client receipt. */ +export async function readRetainedFieldSelection( + input: unknown, + reconcile?: (scope: CommandScope) => Promise, +): Promise< + { state: "ready"; selection: Selection } | { state: "invalid" | "unavailable" | "error" } +> { + const scope = commandScopeSchema.safeParse(input); + if (!scope.success) return { state: "invalid" }; + if (!reconcile) return { state: "unavailable" }; + try { + const parsed = receiptSchema.safeParse(await reconcile(scope.data)); + if (!parsed.success) return { state: "unavailable" }; + const r = parsed.data; + if ( + r.ownerId !== scope.data.workspaceId || + r.requestId !== scope.data.requestId || + r.catalogId !== scope.data.catalogId || + r.key !== scope.data.key + ) + return { state: "unavailable" }; + return { + state: "ready", + selection: { + ownerId: r.ownerId, + requestId: r.requestId, + subjectId: r.subjectId, + catalogId: r.catalogId, + resultId: r.resultId, + revision: r.revision, + topic: "catalog_retained_streams", + sourceVersionIds: [r.sourceVersionId], + }, + }; + } catch { + return { state: "error" }; + } +} diff --git a/scripts/proposals/catalog-retained-selection/retainedFieldTypes.ts b/scripts/proposals/catalog-retained-selection/retainedFieldTypes.ts new file mode 100644 index 000000000..27db4775c --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/retainedFieldTypes.ts @@ -0,0 +1,44 @@ +import type { z } from "zod"; +import type { evaluateRetainedStreamField } from "../catalog-stream-fields/evaluate"; +import type { requestSchema, ActorScope, Selection } from "./schemas"; +type Evaluated = Extract, { state: "ready" }>; +export type Item = { + ref: Omit & { + authority: "context"; + kind: "recording"; + }; + binding: Selection; + value: { state: "known"; amount: number } | { state: "unknown" }; + periods: Evaluated["periods"]; + coverage: { + comparisonState: "comparable" | "incomplete"; + absentDateCount: number; + nullDateCount: number; + missingDateCount: number; + }; + source: { + provider: "luminate"; + metric: "daily_streams"; + platform: "all_dsps"; + territory: "worldwide"; + timezone: "UTC"; + retrievalRange: Evaluated["provenance"]["retrievalRange"]; + }; +}; +export type Ready = Omit, "mode" | "selections"> & { + state: "ready"; + contract: "catalog-retained-field-projection/1"; + asOf: string; + semantics: "historical_snapshot"; + items: Item[]; +}; +export type Result = Ready | { state: "unavailable" | "error" | "invalid" }; +/** Adapter MUST authenticate scope and pre-lock the complete sorted batch, keeping locks through callback evaluation. + * No implementation or grant is supplied. Injected test ports prove plumbing only. */ +export type LockedRead = ( + scope: ActorScope & { workspaceId: string; catalogId: string; selections: Selection[] }, + consume: (tx: { + asOf: string; + readBinding: (selection: Selection) => Promise; + }) => Promise, +) => Promise; diff --git a/scripts/proposals/catalog-retained-selection/schemas.ts b/scripts/proposals/catalog-retained-selection/schemas.ts new file mode 100644 index 000000000..ff178d475 --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/schemas.ts @@ -0,0 +1,70 @@ +import { z } from "zod"; +const uuid = z.uuid().refine(value => value === value.toLowerCase()); +const hash = z.string().regex(/^[a-f0-9]{64}$/); +export const method = { + recipe: "catalog-retained-stream-fields/1", + recipeHash: "65a06a785aa496e1232fe3a9f1606595f19c1a152b710ca30c4c06612f01864a", + evaluatorSha256: "163563e15dd92d473aa51899c54c96300f20d27072b83e39ffb01c84f3adc64e", + helperSha256: "91dcca66c8dec0851c1f6e110257a63b730e9b7ae33a60bceb0e9ffcf318dd81", +} as const; +export const selectionSchema = z.strictObject({ + ownerId: uuid, + requestId: uuid, + subjectId: uuid, + catalogId: uuid, + resultId: uuid, + revision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), + topic: z.literal("catalog_retained_streams"), + sourceVersionIds: z.tuple([uuid]), +}); +export const commandScopeSchema = z.strictObject({ + actorId: uuid, + workspaceId: uuid, + requestId: uuid, + catalogId: uuid, + key: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/), +}); +export const receiptSchema = z.strictObject({ + ownerId: uuid, + requestId: uuid, + subjectId: uuid, + catalogId: uuid, + resultId: uuid, + sourceVersionId: uuid, + revision: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), + key: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/), + commandDigest: hash, +}); +export const actorScopeSchema = z.strictObject({ + actorId: uuid, + sessionId: z.string().min(1).max(128), + chatId: z.string().min(1).max(128), + messageId: z.string().min(1).max(128), +}); +export const requestSchema = z + .strictObject({ + mode: z.literal("retained_field"), + workspaceId: uuid, + catalogId: uuid, + field: z.literal("current_streams"), + query: z.strictObject({ + since: z.iso.date(), + days: z.number().int().min(1).max(366), + timezone: z.literal("UTC"), + }), + method: z.strictObject({ + recipe: z.literal(method.recipe), + recipeHash: z.literal(method.recipeHash), + evaluatorSha256: z.literal(method.evaluatorSha256), + helperSha256: z.literal(method.helperSha256), + }), + selections: z.array(selectionSchema).min(1).max(8), + }) + .refine( + q => + q.selections.every(s => s.ownerId === q.workspaceId && s.catalogId === q.catalogId) && + new Set(q.selections.map(s => s.subjectId)).size === q.selections.length, + ); +export type Selection = z.infer; +export type CommandScope = z.infer; +export type ActorScope = z.infer; diff --git a/scripts/proposals/catalog-retained-selection/selection.test.ts b/scripts/proposals/catalog-retained-selection/selection.test.ts new file mode 100644 index 000000000..2ba2f597d --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/selection.test.ts @@ -0,0 +1,273 @@ +import { describe, expect, it, vi } from "vitest"; +import { readFileSync } from "node:fs"; +import { createHash } from "node:crypto"; +import { readRetainedFieldSelection } from "./readRetainedFieldSelection"; +import { consumeRetainedField } from "./consumeRetainedField"; +import { method } from "./schemas"; +import { classifyRetainedFieldRefusal } from "./classifyRetainedFieldRefusal"; +import { evaluateRetainedStreamField } from "../catalog-stream-fields/evaluate"; +const id = (n: number) => `10000000-0000-4000-8000-${String(n).padStart(12, "0")}`; +const scope = { + actorId: id(9), + workspaceId: id(1), + requestId: id(2), + catalogId: id(3), + key: "original", +}; +const receipt = { + ownerId: id(1), + requestId: id(2), + subjectId: id(4), + catalogId: id(3), + key: "original", + commandDigest: "a".repeat(64), + resultId: id(5), + sourceVersionId: id(6), + revision: 7, +}; +const selection = { + ownerId: id(1), + requestId: id(2), + subjectId: id(4), + catalogId: id(3), + resultId: id(5), + revision: 7, + topic: "catalog_retained_streams", + sourceVersionIds: [id(6)], +}; +const query = { since: "2026-10-24", days: 1, timezone: "UTC" }; +const request = { + mode: "retained_field", + workspaceId: id(1), + catalogId: id(3), + field: "current_streams", + query, + method, + selections: [selection], +}; +const actor = { actorId: id(9), sessionId: "session", chatId: "chat", messageId: "assistant" }; +const envelope = { + ...selection, + evidence: { + schemaVersion: 1, + workspaceId: id(1), + catalogId: id(3), + subjectId: id(4), + isrc: "USAAA2600001", + provider: "luminate", + metric: "daily_streams", + platform: "all_dsps", + territory: "worldwide", + timezone: "UTC", + since: "2026-10-23", + until: "2026-10-25", + periods: { + previous: { start: "2026-10-23", end_exclusive: "2026-10-24" }, + current: { start: "2026-10-24", end_exclusive: "2026-10-25" }, + days: 1, + timezone: "UTC", + }, + providerRecordingId: "provider-original", + observations: [23, 24].map((d, i) => ({ + catalog_id: id(3), + isrc: "USAAA2600001", + date: `2026-10-${d}`, + run_id: id(7), + provider_recording_id: "provider-original", + streams: i ? 100 : 50, + source_hash: "a".repeat(64), + retrieved_at: "2026-10-25T01:00:00Z", + })), + absentDates: [], + nullDates: [], + retrievalRange: { earliest: "2026-10-25T01:00:00Z", latest: "2026-10-25T01:00:00Z" }, + }, +}; +const asOf = "2026-10-27T00:00:00Z"; +describe("genuine retained selection proposal", () => { + it("round trips reconciled identities through the real evaluator while transaction is held", async () => { + await expect( + JSON.stringify({ scope, actor, receipt, envelope, query, asOf }, null, 2) + "\n", + ).toMatchFileSnapshot("./fixtures/synthetic-authority-input.json"); + const reconcile = vi.fn(async () => receipt); + const selected = await readRetainedFieldSelection(scope, reconcile); + expect(reconcile).toHaveBeenCalledWith(scope); + expect(selected).toEqual({ state: "ready", selection }); + let held = false; + const result = await consumeRetainedField( + actor, + { ...request, selections: selected.state === "ready" ? [selected.selection] : [] }, + async (context, consume) => { + expect(context.actorId).toBe(id(9)); + expect(context.selections).toEqual([selection]); + held = true; + const value = await consume({ + asOf, + readBinding: async () => { + expect(held).toBe(true); + return envelope; + }, + }); + held = false; + return value; + }, + ); + expect(held).toBe(false); + expect(result.state).toBe("ready"); + if (result.state !== "ready") throw new Error("expected ready"); + const { state: _state, ...fieldContext } = result; + await expect(JSON.stringify(fieldContext, null, 2) + "\n").toMatchFileSnapshot( + "./fixtures/fieldContext.json", + ); + expect(result.items[0].binding).toEqual(selection); + expect(result.items[0].value).toEqual({ state: "known", amount: 100 }); + expect(result.items[0].ref.id).toBe(id(4)); + expect(JSON.stringify(result)).not.toContain("provider-original"); + expect(JSON.stringify(result)).not.toContain("observations"); + }); + it.each([ + null, + undefined, + {}, + { state: "pending" }, + { ...receipt, ownerId: id(9) }, + { ...receipt, requestId: id(8) }, + { ...receipt, catalogId: id(8) }, + { ...receipt, key: "new-key" }, + { ...receipt, extra: true }, + ])("does not manufacture selection from unavailable or mismatched receipt %j", async value => { + expect(await readRetainedFieldSelection(scope, async () => value)).toEqual({ + state: "unavailable", + }); + }); + it("defaults to unavailable and does not retry ambiguous transport errors", async () => { + expect(await readRetainedFieldSelection(scope)).toEqual({ state: "unavailable" }); + const reconcile = vi.fn(async () => { + throw new Error("unknown commit"); + }); + expect(await readRetainedFieldSelection(scope, reconcile)).toEqual({ state: "error" }); + expect(reconcile).toHaveBeenCalledTimes(1); + expect(await consumeRetainedField(actor, request)).toEqual({ state: "unavailable" }); + }); + it("withholds all projections when the authority read returns unavailable", async () => { + const result = await consumeRetainedField(actor, request, async (_, consume) => + consume({ asOf, readBinding: async () => null }), + ); + expect(result).toEqual({ state: "unavailable" }); + }); + it.each([ + { ...envelope, revision: 8 }, + { ...envelope, resultId: id(8) }, + { ...envelope, sourceVersionIds: [id(8)] }, + ])("does not silently upgrade exact binding", async value => { + expect( + await consumeRetainedField(actor, request, async (_, consume) => + consume({ asOf, readBinding: async () => value }), + ), + ).toEqual({ state: "unavailable" }); + }); + it.each([ + { ...request, mode: "report" }, + { ...request, evidence: envelope }, + { ...request, selections: [selection, selection] }, + { ...request, selections: Array(9).fill(selection) }, + { ...request, method: { ...method, evaluatorSha256: "b".repeat(64) } }, + { ...request, selections: [{ ...selection, ownerId: id(9) }] }, + ])("rejects invalid branch before authority call", async input => { + const transaction = vi.fn(); + expect(await consumeRetainedField(actor, input, transaction)).toEqual({ state: "invalid" }); + expect(transaction).not.toHaveBeenCalled(); + }); + it("withholds the whole batch if a later selection is unavailable", async () => { + const second = { ...selection, subjectId: id(8), resultId: id(10) }; + const result = await consumeRetainedField( + actor, + { ...request, selections: [selection, second] }, + async (_, consume) => + consume({ asOf, readBinding: async s => (s.subjectId === id(4) ? envelope : null) }), + ); + expect(result).toEqual({ state: "unavailable" }); + }); + it("preserves observed zero and makes incomplete values unknown", async () => { + const zero = structuredClone(envelope); + zero.evidence.observations[1].streams = 0; + const result = await consumeRetainedField(actor, request, async (_, consume) => + consume({ asOf, readBinding: async () => zero }), + ); + expect(result.state === "ready" && result.items[0].value).toEqual({ + state: "known", + amount: 0, + }); + const absent = structuredClone(envelope); + absent.evidence.observations.pop(); + absent.evidence.absentDates = ["2026-10-24"] as never[]; + const unknown = await consumeRetainedField(actor, request, async (_, consume) => + consume({ asOf, readBinding: async () => absent }), + ); + expect(unknown.state === "ready" && unknown.items[0].value).toEqual({ state: "unknown" }); + }); +}); + +it("pins the actual evaluated code, recipe and helper", () => { + for (const [file, hash] of [ + ["../catalog-stream-fields/evaluate.ts", method.evaluatorSha256], + ["../catalog-stream-fields/recipe.json", method.recipeHash], + ["../../../lib/catalog/compareSpotifyDailyStreams.ts", method.helperSha256], + ]) { + expect( + createHash("sha256") + .update(readFileSync(new URL(file, import.meta.url))) + .digest("hex"), + ).toBe(hash); + } +}); +it("redacts later transport failure after a successful row and never retries", async () => { + const second = { ...selection, subjectId: id(8), resultId: id(10) }; + const readBinding = vi.fn(async s => { + if (s.subjectId === id(4)) return envelope; + throw new Error("transport uncertain"); + }); + expect( + await consumeRetainedField( + actor, + { ...request, selections: [selection, second] }, + async (_, consume) => consume({ asOf, readBinding }), + ), + ).toEqual({ state: "error" }); + expect(readBinding).toHaveBeenCalledTimes(2); +}); + +it.each([270000, 400000])( + "classifies actual oversized UTF-8 authority evidence as invalid (%i characters)", + async characters => { + const oversized = structuredClone(envelope); + oversized.evidence.providerRecordingId = "é".repeat(characters); + const evidenceBytes = Buffer.byteLength(JSON.stringify(oversized.evidence), "utf8"); + const envelopeBytes = Buffer.byteLength(JSON.stringify(oversized), "utf8"); + expect(evidenceBytes).toBeGreaterThan(512 * 1024); + if (characters === 270000) expect(envelopeBytes).toBeLessThan(768 * 1024); + else expect(envelopeBytes).toBeGreaterThan(768 * 1024); + expect( + evaluateRetainedStreamField({ + operation: "read_field", + recipe: method.recipe, + field: "current_streams", + selection: { ...selection, query }, + asOf, + boundary: { state: "qualified", envelope: oversized }, + }), + ).toEqual({ state: "refused", reason: "size_limit" }); + expect( + await consumeRetainedField(actor, request, async (_, consume) => + consume({ asOf, readBinding: async () => oversized }), + ), + ).toEqual({ state: "invalid" }); + }, +); + +it.each(["helper_changed", "source_error"])( + "classifies evaluator operational refusal %s without details", + reason => { + expect(classifyRetainedFieldRefusal(reason)).toEqual({ state: "error" }); + }, +); diff --git a/scripts/proposals/catalog-retained-selection/tsconfig.json b/scripts/proposals/catalog-retained-selection/tsconfig.json new file mode 100644 index 000000000..4899580ae --- /dev/null +++ b/scripts/proposals/catalog-retained-selection/tsconfig.json @@ -0,0 +1,6 @@ +{ + "extends": "../../../tsconfig.json", + "compilerOptions": { "incremental": false, "noEmit": true, "strict": true }, + "include": ["./*.ts", "../catalog-stream-fields/evaluate.ts", "../../../lib/catalog/compareSpotifyDailyStreams.ts"], + "exclude": ["node_modules"] +}