niceeval 0.12.2-canary.31 → 0.13.0

package/dist/record/family/observability.js

@@ -0,0 +1,30 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./observability.cjs");
+const __niceevalExport0 = __niceevalCanonical["AttemptCommandsCollectionSchema"];
+export { __niceevalExport0 as AttemptCommandsCollectionSchema };
+const __niceevalExport1 = __niceevalCanonical["AttemptConversationCollectionSchema"];
+export { __niceevalExport1 as AttemptConversationCollectionSchema };
+const __niceevalExport2 = __niceevalCanonical["AttemptDiagnosticsCollectionSchema"];
+export { __niceevalExport2 as AttemptDiagnosticsCollectionSchema };
+const __niceevalExport3 = __niceevalCanonical["AttemptObservabilityAttachmentSchema"];
+export { __niceevalExport3 as AttemptObservabilityAttachmentSchema };
+const __niceevalExport4 = __niceevalCanonical["AttemptTimingCollectionSchema"];
+export { __niceevalExport4 as AttemptTimingCollectionSchema };
+const __niceevalExport5 = __niceevalCanonical["AttemptUsageCollectionSchema"];
+export { __niceevalExport5 as AttemptUsageCollectionSchema };
+const __niceevalExport6 = __niceevalCanonical["RunDiagnosticsCollectionSchema"];
+export { __niceevalExport6 as RunDiagnosticsCollectionSchema };
+const __niceevalExport7 = __niceevalCanonical["RunObservabilityAttachmentSchema"];
+export { __niceevalExport7 as RunObservabilityAttachmentSchema };
+const __niceevalExport8 = __niceevalCanonical["RunTimingCollectionSchema"];
+export { __niceevalExport8 as RunTimingCollectionSchema };
+const __niceevalExport9 = __niceevalCanonical["observabilityAttachmentIntegrityIssues"];
+export { __niceevalExport9 as observabilityAttachmentIntegrityIssues };
+const __niceevalExport10 = __niceevalCanonical["observabilityBlobRefs"];
+export { __niceevalExport10 as observabilityBlobRefs };
+const __niceevalExport11 = __niceevalCanonical["observabilityRecordAttachment"];
+export { __niceevalExport11 as observabilityRecordAttachment };
+const __niceevalExport12 = __niceevalCanonical["observabilitySourceFrameIntegrityIssues"];
+export { __niceevalExport12 as observabilitySourceFrameIntegrityIssues };
+//# sourceMappingURL=observability.js.map

package/dist/record/family/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sources":[],"names":[],"mappings":""}

package/dist/record/family/source-navigation.cjs

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sourceNavigationRecordAttachment = exports.SourceNavigationAttachmentSchema = exports.SourceNavigationCollectionSchema = exports.SourceNavigationCollectionLimitationSchema = exports.SourceNavigationRowSchema = exports.SourceNavigationTimingSchema = exports.SourceNavigationSourceFrameSchema = exports.SourceNavigationLimits = void 0;
+exports.createSourceNavigationAttachmentWrite = createSourceNavigationAttachmentWrite;
+exports.sourceNavigationIntegrityIssues = sourceNavigationIntegrityIssues;
+const effect_1 = require("effect");
+const index_ts_1 = require("../attachment/index.cjs");
+const errors_ts_1 = require("../attachment/errors.cjs");
+const core_ts_1 = require("../codec/core.cjs");
+const identifiers_ts_1 = require("../codec/identifiers.cjs");
+const index_ts_2 = require("../definition/index.cjs");
+const codec_ts_1 = require("../../o11y/record/codec.cjs");
+const common_ts_1 = require("./common.cjs");
+/** One Attempt can retain at most this many physical send navigation rows. */
+exports.SourceNavigationLimits = Object.freeze({ maximumRows: 256 });
+const SourceNavigationPositionSchema = effect_1.Schema.Struct({
+    line: common_ts_1.PositiveSafeIntegerSchema,
+    column: common_ts_1.PositiveSafeIntegerSchema,
+});
+exports.SourceNavigationSourceFrameSchema = effect_1.Schema.Union(effect_1.Schema.Struct({
+    state: effect_1.Schema.Literal("mapped"),
+    sourceItemId: identifiers_ts_1.SourceItemIdSchema,
+    sha256: identifiers_ts_1.Sha256DigestSchema,
+    start: SourceNavigationPositionSchema,
+    end: SourceNavigationPositionSchema,
+}), effect_1.Schema.Struct({
+    state: effect_1.Schema.Literal("unmapped"),
+    reason: effect_1.Schema.Literal("location-not-captured", "source-snapshot-not-recorded", "position-unrepresentable"),
+}));
+exports.SourceNavigationTimingSchema = effect_1.Schema.Union(effect_1.Schema.Struct({ state: effect_1.Schema.Literal("linked"), intervalId: codec_ts_1.IntervalIdSchema }), effect_1.Schema.Struct({
+    state: effect_1.Schema.Literal("unavailable"),
+    reason: effect_1.Schema.Literal("timing-not-recorded"),
+}));
+/** Exactly one row for each retained physical ConversationTurn. */
+exports.SourceNavigationRowSchema = effect_1.Schema.Struct({
+    turnId: codec_ts_1.TurnIdSchema,
+    sourceOrder: effect_1.Schema.NullOr(common_ts_1.PositiveSafeIntegerSchema),
+    source: exports.SourceNavigationSourceFrameSchema,
+    timing: exports.SourceNavigationTimingSchema,
+});
+exports.SourceNavigationCollectionLimitationSchema = effect_1.Schema.Union(effect_1.Schema.Struct({
+    code: effect_1.Schema.Literal("collection-cap-reached"),
+    target: effect_1.Schema.Literal("navigation-row"),
+    omittedAtLeast: common_ts_1.PositiveSafeIntegerSchema,
+}), effect_1.Schema.Struct({
+    code: effect_1.Schema.Literal("capture-unrecoverable"),
+    target: effect_1.Schema.Literal("timing-link"),
+    omittedAtLeast: common_ts_1.PositiveSafeIntegerSchema,
+}));
+function sourceNavigationLimitationKey(value) {
+    return `${value.code}\u0000${value.target}\u0000${value.omittedAtLeast}`;
+}
+function hasCanonicalLimitations(values) {
+    let previous;
+    const seen = new Set();
+    for (const value of values) {
+        const key = sourceNavigationLimitationKey(value);
+        if (seen.has(key) || (previous !== undefined && previous >= key))
+            return false;
+        seen.add(key);
+        previous = key;
+    }
+    return true;
+}
+exports.SourceNavigationCollectionSchema = effect_1.Schema.Union(effect_1.Schema.Struct({
+    state: effect_1.Schema.Literal("complete"),
+    limitations: common_ts_1.EmptyArraySchema,
+}), effect_1.Schema.Struct({
+    state: effect_1.Schema.Literal("partial"),
+    limitations: effect_1.Schema.NonEmptyArray(exports.SourceNavigationCollectionLimitationSchema).pipe(effect_1.Schema.filter(hasCanonicalLimitations, {
+        identifier: "SourceNavigationPartialLimitations",
+        description: "a deterministic deduplicated source navigation limitation sequence",
+    })),
+}));
+function sourceFrameIsOrdered(frame) {
+    return frame.state !== "mapped" || frame.start.line < frame.end.line ||
+        (frame.start.line === frame.end.line && frame.start.column <= frame.end.column);
+}
+function hasCanonicalRows(payload) {
+    if (payload.rows.length > exports.SourceNavigationLimits.maximumRows)
+        return false;
+    const turnIds = new Set();
+    const sourceOrders = new Set();
+    const timingIntervals = new Set();
+    for (const row of payload.rows) {
+        if (turnIds.has(row.turnId))
+            return false;
+        turnIds.add(row.turnId);
+        if (!sourceFrameIsOrdered(row.source))
+            return false;
+        if (row.source.state === "mapped" && row.sourceOrder === null)
+            return false;
+        if (row.sourceOrder !== null) {
+            if (sourceOrders.has(row.sourceOrder))
+                return false;
+            sourceOrders.add(row.sourceOrder);
+        }
+        if (row.timing.state === "linked") {
+            if (timingIntervals.has(row.timing.intervalId))
+                return false;
+            timingIntervals.add(row.timing.intervalId);
+        }
+    }
+    return true;
+}
+/**
+ * Package-private, Attempt-owned navigation facts.  This family has no blob
+ * closure: a mapped frame is only an exact semantic join to origin Sources.
+ */
+exports.SourceNavigationAttachmentSchema = effect_1.Schema.Struct({
+    collection: effect_1.Schema.propertySignature(exports.SourceNavigationCollectionSchema).pipe(effect_1.Schema.fromKey("collection-data")),
+    rows: effect_1.Schema.propertySignature(effect_1.Schema.Array(exports.SourceNavigationRowSchema)).pipe(effect_1.Schema.fromKey("rows-data")),
+}).pipe(effect_1.Schema.filter(hasCanonicalRows, {
+    identifier: "SourceNavigationAttachment",
+    description: "a bounded canonical physical-send navigation collection",
+}));
+const SourceNavigationBlobBudget = Object.freeze({
+    // The shared declaration validator requires a positive bounded policy.
+    // This family remains no-blob: refs() is permanently empty and its writer
+    // always emits an empty blob list, so none of these capacity units is usable.
+    maximumBlobs: 1,
+    maximumBlobBytes: 1,
+    maximumTotalBytes: 1,
+});
+/** The sole current declaration for Attempt-owned source navigation. */
+exports.sourceNavigationRecordAttachment = (0, index_ts_2.defineRecordAttachment)({
+    family: "niceeval.source-navigation",
+    current: {
+        schemaVersion: 1,
+        owners: {
+            attempt: {
+                schema: exports.SourceNavigationAttachmentSchema,
+                limits: common_ts_1.FixedAttachmentValueLimits,
+                blobs: {
+                    refs: () => Object.freeze([]),
+                    budget: SourceNavigationBlobBudget,
+                    verify: () => Object.freeze([]),
+                },
+            },
+        },
+    },
+});
+/** Builds the no-blob fixed writer and rejects a non-exact v1 candidate. */
+function createSourceNavigationAttachmentWrite(input, writeSpec) {
+    const decoded = effect_1.Schema.validateEither(exports.SourceNavigationAttachmentSchema, core_ts_1.RecordExactParseOptions)(input);
+    if (effect_1.Either.isLeft(decoded)) {
+        return effect_1.Either.left(Object.freeze({ code: "source-navigation-attachment-input-invalid" }));
+    }
+    const write = (0, index_ts_1.makeFixedRecordAttachmentWrite)(writeSpec, () => Object.freeze({ payload: decoded.right, blobs: Object.freeze([]) }));
+    const closure = (0, index_ts_1.validateRecordAttachmentWrite)(write);
+    if (effect_1.Either.isLeft(closure)) {
+        throw new Error("Fixed source navigation write closure was invalid");
+    }
+    return effect_1.Either.right(write);
+}
+/**
+ * Host-only semantic join. It compares explicit identities only: no source
+ * bytes are scanned and no relationship is inferred from array position.
+ */
+function sourceNavigationIntegrityIssues(input) {
+    const issues = [];
+    const rowsByTurn = new Map(input.payload.rows.map((row) => [row.turnId, row]));
+    const turns = [...input.observability.conversation.turns].sort((left, right) => left.sequence - right.sequence);
+    const turnsById = new Map(turns.map((turn) => [turn.turnId, turn]));
+    if (rowsByTurn.size !== input.payload.rows.length || turnsById.size !== input.observability.conversation.turns.length) {
+        issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["rows"]));
+    }
+    for (const [turnId] of turnsById) {
+        if (!rowsByTurn.has(turnId)) {
+            issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["rows", turnId]));
+        }
+    }
+    for (const [turnId] of rowsByTurn) {
+        if (!turnsById.has(turnId)) {
+            issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["rows", turnId]));
+        }
+    }
+    for (const [index, turn] of turns.entries()) {
+        if (input.payload.rows[index]?.turnId !== turn.turnId) {
+            issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["rows", String(index), "turnId"]));
+        }
+    }
+    const navigationCap = input.payload.collection.limitations.find((limitation) => limitation.code === "collection-cap-reached" && limitation.target === "navigation-row");
+    const conversationCap = input.observability.conversation.collection.limitations.find((limitation) => limitation.code === "collection-cap-reached" && limitation.target === "conversation");
+    if (navigationCap !== undefined &&
+        (conversationCap === undefined ||
+            !("omittedAtLeast" in conversationCap) ||
+            conversationCap.omittedAtLeast !== navigationCap.omittedAtLeast)) {
+        issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["collection"]));
+    }
+    if (input.payload.collection.state === "partial" &&
+        input.observability.conversation.collection.state !== "partial") {
+        issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["collection"]));
+    }
+    const intervals = new Map(input.observability.timing.intervals.map((interval) => [interval.intervalId, interval]));
+    const sources = input.sources === undefined
+        ? undefined
+        : new Map(input.sources.items.map((item) => [item.sourceItemId, item]));
+    for (const [index, row] of input.payload.rows.entries()) {
+        if (row.timing.state === "linked") {
+            const interval = intervals.get(row.timing.intervalId);
+            if (interval === undefined || interval.phase !== "agent.send") {
+                issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["rows", String(index), "timing"]));
+            }
+        }
+        if (row.source.state === "mapped") {
+            const source = sources?.get(row.source.sourceItemId);
+            if (source === undefined || source.sha256 !== row.source.sha256 || !sourceFrameIsOrdered(row.source)) {
+                issues.push((0, errors_ts_1.recordAttachmentIssue)("record-attachment-materialized-invalid", ["rows", String(index), "source"]));
+            }
+        }
+    }
+    return Object.freeze(issues);
+}
+//# sourceMappingURL=source-navigation.cjs.map

package/dist/record/family/source-navigation.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-navigation.js","sourceRoot":"","sources":["source-navigation.ts"],"names":[],"mappings":"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","sourcesContent":["import { Either, Schema } from \"effect\";\nimport { makeFixedRecordAttachmentWrite, validateRecordAttachmentWrite, type FixedAttachmentWriteSpec, type RecordAttachmentWrite, } from \"../attachment/index.ts\";\nimport { recordAttachmentIssue, type RecordAttachmentIssue } from \"../attachment/errors.ts\";\nimport { RecordExactParseOptions } from \"../codec/core.ts\";\nimport { Sha256DigestSchema, SourceItemIdSchema, } from \"../codec/identifiers.ts\";\nimport { defineRecordAttachment } from \"../definition/index.ts\";\nimport { IntervalIdSchema, TurnIdSchema, } from \"../../o11y/record/codec.ts\";\nimport type { AttemptObservabilityAttachment } from \"./observability.ts\";\nimport type { SourcesAttachment } from \"./sources.ts\";\nimport { EmptyArraySchema, FixedAttachmentValueLimits, PositiveSafeIntegerSchema, } from \"./common.ts\";\n/** One Attempt can retain at most this many physical send navigation rows. */\nexport const SourceNavigationLimits = Object.freeze({ maximumRows: 256 });\nconst SourceNavigationPositionSchema = Schema.Struct({\n    line: PositiveSafeIntegerSchema,\n    column: PositiveSafeIntegerSchema,\n});\nexport const SourceNavigationSourceFrameSchema = Schema.Union(Schema.Struct({\n    state: Schema.Literal(\"mapped\"),\n    sourceItemId: SourceItemIdSchema,\n    sha256: Sha256DigestSchema,\n    start: SourceNavigationPositionSchema,\n    end: SourceNavigationPositionSchema,\n}), Schema.Struct({\n    state: Schema.Literal(\"unmapped\"),\n    reason: Schema.Literal(\"location-not-captured\", \"source-snapshot-not-recorded\", \"position-unrepresentable\"),\n}));\nexport type SourceNavigationSourceFrame = Schema.Schema.Type<typeof SourceNavigationSourceFrameSchema>;\nexport const SourceNavigationTimingSchema = Schema.Union(Schema.Struct({ state: Schema.Literal(\"linked\"), intervalId: IntervalIdSchema }), Schema.Struct({\n    state: Schema.Literal(\"unavailable\"),\n    reason: Schema.Literal(\"timing-not-recorded\"),\n}));\nexport type SourceNavigationTiming = Schema.Schema.Type<typeof SourceNavigationTimingSchema>;\n/** Exactly one row for each retained physical ConversationTurn. */\nexport const SourceNavigationRowSchema = Schema.Struct({\n    turnId: TurnIdSchema,\n    sourceOrder: Schema.NullOr(PositiveSafeIntegerSchema),\n    source: SourceNavigationSourceFrameSchema,\n    timing: SourceNavigationTimingSchema,\n});\nexport type SourceNavigationRow = Schema.Schema.Type<typeof SourceNavigationRowSchema>;\nexport const SourceNavigationCollectionLimitationSchema = Schema.Union(Schema.Struct({\n    code: Schema.Literal(\"collection-cap-reached\"),\n    target: Schema.Literal(\"navigation-row\"),\n    omittedAtLeast: PositiveSafeIntegerSchema,\n}), Schema.Struct({\n    code: Schema.Literal(\"capture-unrecoverable\"),\n    target: Schema.Literal(\"timing-link\"),\n    omittedAtLeast: PositiveSafeIntegerSchema,\n}));\nexport type SourceNavigationCollectionLimitation = Schema.Schema.Type<typeof SourceNavigationCollectionLimitationSchema>;\nfunction sourceNavigationLimitationKey(value: SourceNavigationCollectionLimitation): string {\n    return `${value.code}\\u0000${value.target}\\u0000${value.omittedAtLeast}`;\n}\nfunction hasCanonicalLimitations(values: readonly SourceNavigationCollectionLimitation[]): boolean {\n    let previous: string | undefined;\n    const seen = new Set<string>();\n    for (const value of values) {\n        const key = sourceNavigationLimitationKey(value);\n        if (seen.has(key) || (previous !== undefined && previous >= key))\n            return false;\n        seen.add(key);\n        previous = key;\n    }\n    return true;\n}\nexport const SourceNavigationCollectionSchema = Schema.Union(Schema.Struct({\n    state: Schema.Literal(\"complete\"),\n    limitations: EmptyArraySchema,\n}), Schema.Struct({\n    state: Schema.Literal(\"partial\"),\n    limitations: Schema.NonEmptyArray(SourceNavigationCollectionLimitationSchema).pipe(Schema.filter(hasCanonicalLimitations, {\n        identifier: \"SourceNavigationPartialLimitations\",\n        description: \"a deterministic deduplicated source navigation limitation sequence\",\n    })),\n}));\nexport type SourceNavigationCollection = Schema.Schema.Type<typeof SourceNavigationCollectionSchema>;\nfunction sourceFrameIsOrdered(frame: SourceNavigationSourceFrame): boolean {\n    return frame.state !== \"mapped\" || frame.start.line < frame.end.line ||\n        (frame.start.line === frame.end.line && frame.start.column <= frame.end.column);\n}\nfunction hasCanonicalRows(payload: {\n    readonly collection: SourceNavigationCollection;\n    readonly rows: readonly SourceNavigationRow[];\n}): boolean {\n    if (payload.rows.length > SourceNavigationLimits.maximumRows)\n        return false;\n    const turnIds = new Set<string>();\n    const sourceOrders = new Set<number>();\n    const timingIntervals = new Set<string>();\n    for (const row of payload.rows) {\n        if (turnIds.has(row.turnId))\n            return false;\n        turnIds.add(row.turnId);\n        if (!sourceFrameIsOrdered(row.source))\n            return false;\n        if (row.source.state === \"mapped\" && row.sourceOrder === null)\n            return false;\n        if (row.sourceOrder !== null) {\n            if (sourceOrders.has(row.sourceOrder))\n                return false;\n            sourceOrders.add(row.sourceOrder);\n        }\n        if (row.timing.state === \"linked\") {\n            if (timingIntervals.has(row.timing.intervalId))\n                return false;\n            timingIntervals.add(row.timing.intervalId);\n        }\n    }\n    return true;\n}\n/**\n * Package-private, Attempt-owned navigation facts.  This family has no blob\n * closure: a mapped frame is only an exact semantic join to origin Sources.\n */\nexport const SourceNavigationAttachmentSchema = Schema.Struct({\n    collection: Schema.propertySignature(SourceNavigationCollectionSchema).pipe(Schema.fromKey(\"collection-data\")),\n    rows: Schema.propertySignature(Schema.Array(SourceNavigationRowSchema)).pipe(Schema.fromKey(\"rows-data\")),\n}).pipe(Schema.filter(hasCanonicalRows, {\n    identifier: \"SourceNavigationAttachment\",\n    description: \"a bounded canonical physical-send navigation collection\",\n}));\nexport type SourceNavigationAttachment = Schema.Schema.Type<typeof SourceNavigationAttachmentSchema>;\nconst SourceNavigationBlobBudget = Object.freeze({\n    // The shared declaration validator requires a positive bounded policy.\n    // This family remains no-blob: refs() is permanently empty and its writer\n    // always emits an empty blob list, so none of these capacity units is usable.\n    maximumBlobs: 1,\n    maximumBlobBytes: 1,\n    maximumTotalBytes: 1,\n});\n/** The sole current declaration for Attempt-owned source navigation. */\nexport const sourceNavigationRecordAttachment = defineRecordAttachment({\n    family: \"niceeval.source-navigation\",\n    current: {\n        schemaVersion: 1,\n        owners: {\n            attempt: {\n                schema: SourceNavigationAttachmentSchema,\n                limits: FixedAttachmentValueLimits,\n                blobs: {\n                    refs: () => Object.freeze([]),\n                    budget: SourceNavigationBlobBudget,\n                    verify: () => Object.freeze([]),\n                },\n            },\n        },\n    },\n});\n/** Builds the no-blob fixed writer and rejects a non-exact v1 candidate. */\nexport function createSourceNavigationAttachmentWrite(input: unknown, writeSpec: FixedAttachmentWriteSpec<\"attempt\", SourceNavigationAttachment>): Either.Either<RecordAttachmentWrite<\"attempt\", never, never>, {\n    readonly code: \"source-navigation-attachment-input-invalid\";\n}> {\n    const decoded = Schema.validateEither(SourceNavigationAttachmentSchema, RecordExactParseOptions)(input);\n    if (Either.isLeft(decoded)) {\n        return Either.left(Object.freeze({ code: \"source-navigation-attachment-input-invalid\" as const }));\n    }\n    const write = makeFixedRecordAttachmentWrite(writeSpec, () => Object.freeze({ payload: decoded.right, blobs: Object.freeze([]) }));\n    const closure = validateRecordAttachmentWrite(write);\n    if (Either.isLeft(closure)) {\n        throw new Error(\"Fixed source navigation write closure was invalid\");\n    }\n    return Either.right(write);\n}\n/**\n * Host-only semantic join. It compares explicit identities only: no source\n * bytes are scanned and no relationship is inferred from array position.\n */\nexport function sourceNavigationIntegrityIssues(input: {\n    readonly payload: SourceNavigationAttachment;\n    readonly observability: AttemptObservabilityAttachment;\n    readonly sources: SourcesAttachment | undefined;\n}): readonly RecordAttachmentIssue[] {\n    const issues: RecordAttachmentIssue[] = [];\n    const rowsByTurn = new Map<string, SourceNavigationRow>(input.payload.rows.map((row) => [row.turnId, row] as const));\n    const turns = [...input.observability.conversation.turns].sort((left, right) => left.sequence - right.sequence);\n    const turnsById = new Map<string, AttemptObservabilityAttachment[\"conversation\"][\"turns\"][number]>(turns.map((turn) => [turn.turnId, turn] as const));\n    if (rowsByTurn.size !== input.payload.rows.length || turnsById.size !== input.observability.conversation.turns.length) {\n        issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"rows\"]));\n    }\n    for (const [turnId] of turnsById) {\n        if (!rowsByTurn.has(turnId)) {\n            issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"rows\", turnId]));\n        }\n    }\n    for (const [turnId] of rowsByTurn) {\n        if (!turnsById.has(turnId)) {\n            issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"rows\", turnId]));\n        }\n    }\n    for (const [index, turn] of turns.entries()) {\n        if (input.payload.rows[index]?.turnId !== turn.turnId) {\n            issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"rows\", String(index), \"turnId\"]));\n        }\n    }\n    const navigationCap = input.payload.collection.limitations.find((limitation) => limitation.code === \"collection-cap-reached\" && limitation.target === \"navigation-row\");\n    const conversationCap = input.observability.conversation.collection.limitations.find((limitation) => limitation.code === \"collection-cap-reached\" && limitation.target === \"conversation\");\n    if (navigationCap !== undefined &&\n        (conversationCap === undefined ||\n            !(\"omittedAtLeast\" in conversationCap) ||\n            conversationCap.omittedAtLeast !== navigationCap.omittedAtLeast)) {\n        issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"collection\"]));\n    }\n    if (input.payload.collection.state === \"partial\" &&\n        input.observability.conversation.collection.state !== \"partial\") {\n        issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"collection\"]));\n    }\n    const intervals = new Map(input.observability.timing.intervals.map((interval) => [interval.intervalId, interval] as const));\n    const sources = input.sources === undefined\n        ? undefined\n        : new Map(input.sources.items.map((item) => [item.sourceItemId, item] as const));\n    for (const [index, row] of input.payload.rows.entries()) {\n        if (row.timing.state === \"linked\") {\n            const interval = intervals.get(row.timing.intervalId);\n            if (interval === undefined || interval.phase !== \"agent.send\") {\n                issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"rows\", String(index), \"timing\"]));\n            }\n        }\n        if (row.source.state === \"mapped\") {\n            const source = sources?.get(row.source.sourceItemId);\n            if (source === undefined || source.sha256 !== row.source.sha256 || !sourceFrameIsOrdered(row.source)) {\n                issues.push(recordAttachmentIssue(\"record-attachment-materialized-invalid\", [\"rows\", String(index), \"source\"]));\n            }\n        }\n    }\n    return Object.freeze(issues);\n}\n"]}

package/dist/record/family/source-navigation.d.cts

@@ -0,0 +1,330 @@
+import { Either, Schema } from "effect";
+import { type FixedAttachmentWriteSpec, type RecordAttachmentWrite } from "../attachment/index.cjs";
+import { type RecordAttachmentIssue } from "../attachment/errors.cjs";
+import type { AttemptObservabilityAttachment } from "./observability.cjs";
+import type { SourcesAttachment } from "./sources.cjs";
+/** One Attempt can retain at most this many physical send navigation rows. */
+export declare const SourceNavigationLimits: Readonly<{
+    maximumRows: 256;
+}>;
+export declare const SourceNavigationSourceFrameSchema: Schema.Union<[Schema.Struct<{
+    state: Schema.Literal<["mapped"]>;
+    sourceItemId: Schema.Schema<import("../model/identifiers.cjs").SourceItemId, string, never>;
+    sha256: Schema.Schema<import("../model/identifiers.cjs").Sha256Digest, string, never>;
+    start: Schema.Struct<{
+        line: Schema.filter<typeof Schema.JsonNumber>;
+        column: Schema.filter<typeof Schema.JsonNumber>;
+    }>;
+    end: Schema.Struct<{
+        line: Schema.filter<typeof Schema.JsonNumber>;
+        column: Schema.filter<typeof Schema.JsonNumber>;
+    }>;
+}>, Schema.Struct<{
+    state: Schema.Literal<["unmapped"]>;
+    reason: Schema.Literal<["location-not-captured", "source-snapshot-not-recorded", "position-unrepresentable"]>;
+}>]>;
+export type SourceNavigationSourceFrame = Schema.Schema.Type<typeof SourceNavigationSourceFrameSchema>;
+export declare const SourceNavigationTimingSchema: Schema.Union<[Schema.Struct<{
+    state: Schema.Literal<["linked"]>;
+    intervalId: Schema.Schema<import("../../o11y/record/model.cjs").IntervalId, string, never>;
+}>, Schema.Struct<{
+    state: Schema.Literal<["unavailable"]>;
+    reason: Schema.Literal<["timing-not-recorded"]>;
+}>]>;
+export type SourceNavigationTiming = Schema.Schema.Type<typeof SourceNavigationTimingSchema>;
+/** Exactly one row for each retained physical ConversationTurn. */
+export declare const SourceNavigationRowSchema: Schema.Struct<{
+    turnId: Schema.Schema<import("../../o11y/record/model.cjs").TurnId, string, never>;
+    sourceOrder: Schema.NullOr<Schema.filter<typeof Schema.JsonNumber>>;
+    source: Schema.Union<[Schema.Struct<{
+        state: Schema.Literal<["mapped"]>;
+        sourceItemId: Schema.Schema<import("../model/identifiers.cjs").SourceItemId, string, never>;
+        sha256: Schema.Schema<import("../model/identifiers.cjs").Sha256Digest, string, never>;
+        start: Schema.Struct<{
+            line: Schema.filter<typeof Schema.JsonNumber>;
+            column: Schema.filter<typeof Schema.JsonNumber>;
+        }>;
+        end: Schema.Struct<{
+            line: Schema.filter<typeof Schema.JsonNumber>;
+            column: Schema.filter<typeof Schema.JsonNumber>;
+        }>;
+    }>, Schema.Struct<{
+        state: Schema.Literal<["unmapped"]>;
+        reason: Schema.Literal<["location-not-captured", "source-snapshot-not-recorded", "position-unrepresentable"]>;
+    }>]>;
+    timing: Schema.Union<[Schema.Struct<{
+        state: Schema.Literal<["linked"]>;
+        intervalId: Schema.Schema<import("../../o11y/record/model.cjs").IntervalId, string, never>;
+    }>, Schema.Struct<{
+        state: Schema.Literal<["unavailable"]>;
+        reason: Schema.Literal<["timing-not-recorded"]>;
+    }>]>;
+}>;
+export type SourceNavigationRow = Schema.Schema.Type<typeof SourceNavigationRowSchema>;
+export declare const SourceNavigationCollectionLimitationSchema: Schema.Union<[Schema.Struct<{
+    code: Schema.Literal<["collection-cap-reached"]>;
+    target: Schema.Literal<["navigation-row"]>;
+    omittedAtLeast: Schema.filter<typeof Schema.JsonNumber>;
+}>, Schema.Struct<{
+    code: Schema.Literal<["capture-unrecoverable"]>;
+    target: Schema.Literal<["timing-link"]>;
+    omittedAtLeast: Schema.filter<typeof Schema.JsonNumber>;
+}>]>;
+export type SourceNavigationCollectionLimitation = Schema.Schema.Type<typeof SourceNavigationCollectionLimitationSchema>;
+export declare const SourceNavigationCollectionSchema: Schema.Union<[Schema.Struct<{
+    state: Schema.Literal<["complete"]>;
+    limitations: Schema.refine<readonly [], Schema.Schema<readonly [], readonly [], never>>;
+}>, Schema.Struct<{
+    state: Schema.Literal<["partial"]>;
+    limitations: Schema.filter<Schema.NonEmptyArray<Schema.Union<[Schema.Struct<{
+        code: Schema.Literal<["collection-cap-reached"]>;
+        target: Schema.Literal<["navigation-row"]>;
+        omittedAtLeast: Schema.filter<typeof Schema.JsonNumber>;
+    }>, Schema.Struct<{
+        code: Schema.Literal<["capture-unrecoverable"]>;
+        target: Schema.Literal<["timing-link"]>;
+        omittedAtLeast: Schema.filter<typeof Schema.JsonNumber>;
+    }>]>>>;
+}>]>;
+export type SourceNavigationCollection = Schema.Schema.Type<typeof SourceNavigationCollectionSchema>;
+/**
+ * Package-private, Attempt-owned navigation facts.  This family has no blob
+ * closure: a mapped frame is only an exact semantic join to origin Sources.
+ */
+export declare const SourceNavigationAttachmentSchema: Schema.filter<Schema.Struct<{
+    collection: Schema.PropertySignature<":", {
+        readonly state: "complete";
+        readonly limitations: readonly [];
+    } | {
+        readonly state: "partial";
+        readonly limitations: readonly [{
+            readonly code: "collection-cap-reached";
+            readonly target: "navigation-row";
+            readonly omittedAtLeast: number;
+        } | {
+            readonly code: "capture-unrecoverable";
+            readonly target: "timing-link";
+            readonly omittedAtLeast: number;
+        }, ...({
+            readonly code: "collection-cap-reached";
+            readonly target: "navigation-row";
+            readonly omittedAtLeast: number;
+        } | {
+            readonly code: "capture-unrecoverable";
+            readonly target: "timing-link";
+            readonly omittedAtLeast: number;
+        })[]];
+    }, "collection-data", ":", {
+        readonly state: "complete";
+        readonly limitations: readonly [];
+    } | {
+        readonly state: "partial";
+        readonly limitations: readonly [{
+            readonly code: "collection-cap-reached";
+            readonly target: "navigation-row";
+            readonly omittedAtLeast: number;
+        } | {
+            readonly code: "capture-unrecoverable";
+            readonly target: "timing-link";
+            readonly omittedAtLeast: number;
+        }, ...({
+            readonly code: "collection-cap-reached";
+            readonly target: "navigation-row";
+            readonly omittedAtLeast: number;
+        } | {
+            readonly code: "capture-unrecoverable";
+            readonly target: "timing-link";
+            readonly omittedAtLeast: number;
+        })[]];
+    }, false, never>;
+    rows: Schema.PropertySignature<":", readonly {
+        readonly source: {
+            readonly state: "mapped";
+            readonly sha256: import("../model/identifiers.cjs").Sha256Digest;
+            readonly start: {
+                readonly line: number;
+                readonly column: number;
+            };
+            readonly end: {
+                readonly line: number;
+                readonly column: number;
+            };
+            readonly sourceItemId: import("../model/identifiers.cjs").SourceItemId;
+        } | {
+            readonly reason: "location-not-captured" | "source-snapshot-not-recorded" | "position-unrepresentable";
+            readonly state: "unmapped";
+        };
+        readonly turnId: import("../../o11y/record/model.cjs").TurnId;
+        readonly timing: {
+            readonly state: "linked";
+            readonly intervalId: import("../../o11y/record/model.cjs").IntervalId;
+        } | {
+            readonly reason: "timing-not-recorded";
+            readonly state: "unavailable";
+        };
+        readonly sourceOrder: number | null;
+    }[], "rows-data", ":", readonly {
+        readonly source: {
+            readonly state: "mapped";
+            readonly sha256: string;
+            readonly start: {
+                readonly line: number;
+                readonly column: number;
+            };
+            readonly end: {
+                readonly line: number;
+                readonly column: number;
+            };
+            readonly sourceItemId: string;
+        } | {
+            readonly reason: "location-not-captured" | "source-snapshot-not-recorded" | "position-unrepresentable";
+            readonly state: "unmapped";
+        };
+        readonly turnId: string;
+        readonly timing: {
+            readonly state: "linked";
+            readonly intervalId: string;
+        } | {
+            readonly reason: "timing-not-recorded";
+            readonly state: "unavailable";
+        };
+        readonly sourceOrder: number | null;
+    }[], false, never>;
+}>>;
+export type SourceNavigationAttachment = Schema.Schema.Type<typeof SourceNavigationAttachmentSchema>;
+/** The sole current declaration for Attempt-owned source navigation. */
+export declare const sourceNavigationRecordAttachment: import("../definition/attachment.cjs").RecordAttachmentDefinition<"niceeval.source-navigation", {
+    readonly attempt: {
+        readonly schema: Schema.filter<Schema.Struct<{
+            collection: Schema.PropertySignature<":", {
+                readonly state: "complete";
+                readonly limitations: readonly [];
+            } | {
+                readonly state: "partial";
+                readonly limitations: readonly [{
+                    readonly code: "collection-cap-reached";
+                    readonly target: "navigation-row";
+                    readonly omittedAtLeast: number;
+                } | {
+                    readonly code: "capture-unrecoverable";
+                    readonly target: "timing-link";
+                    readonly omittedAtLeast: number;
+                }, ...({
+                    readonly code: "collection-cap-reached";
+                    readonly target: "navigation-row";
+                    readonly omittedAtLeast: number;
+                } | {
+                    readonly code: "capture-unrecoverable";
+                    readonly target: "timing-link";
+                    readonly omittedAtLeast: number;
+                })[]];
+            }, "collection-data", ":", {
+                readonly state: "complete";
+                readonly limitations: readonly [];
+            } | {
+                readonly state: "partial";
+                readonly limitations: readonly [{
+                    readonly code: "collection-cap-reached";
+                    readonly target: "navigation-row";
+                    readonly omittedAtLeast: number;
+                } | {
+                    readonly code: "capture-unrecoverable";
+                    readonly target: "timing-link";
+                    readonly omittedAtLeast: number;
+                }, ...({
+                    readonly code: "collection-cap-reached";
+                    readonly target: "navigation-row";
+                    readonly omittedAtLeast: number;
+                } | {
+                    readonly code: "capture-unrecoverable";
+                    readonly target: "timing-link";
+                    readonly omittedAtLeast: number;
+                })[]];
+            }, false, never>;
+            rows: Schema.PropertySignature<":", readonly {
+                readonly source: {
+                    readonly state: "mapped";
+                    readonly sha256: import("../model/identifiers.cjs").Sha256Digest;
+                    readonly start: {
+                        readonly line: number;
+                        readonly column: number;
+                    };
+                    readonly end: {
+                        readonly line: number;
+                        readonly column: number;
+                    };
+                    readonly sourceItemId: import("../model/identifiers.cjs").SourceItemId;
+                } | {
+                    readonly reason: "location-not-captured" | "source-snapshot-not-recorded" | "position-unrepresentable";
+                    readonly state: "unmapped";
+                };
+                readonly turnId: import("../../o11y/record/model.cjs").TurnId;
+                readonly timing: {
+                    readonly state: "linked";
+                    readonly intervalId: import("../../o11y/record/model.cjs").IntervalId;
+                } | {
+                    readonly reason: "timing-not-recorded";
+                    readonly state: "unavailable";
+                };
+                readonly sourceOrder: number | null;
+            }[], "rows-data", ":", readonly {
+                readonly source: {
+                    readonly state: "mapped";
+                    readonly sha256: string;
+                    readonly start: {
+                        readonly line: number;
+                        readonly column: number;
+                    };
+                    readonly end: {
+                        readonly line: number;
+                        readonly column: number;
+                    };
+                    readonly sourceItemId: string;
+                } | {
+                    readonly reason: "location-not-captured" | "source-snapshot-not-recorded" | "position-unrepresentable";
+                    readonly state: "unmapped";
+                };
+                readonly turnId: string;
+                readonly timing: {
+                    readonly state: "linked";
+                    readonly intervalId: string;
+                } | {
+                    readonly reason: "timing-not-recorded";
+                    readonly state: "unavailable";
+                };
+                readonly sourceOrder: number | null;
+            }[], false, never>;
+        }>>;
+        readonly limits: Readonly<{
+            maximumJsonBytes: number;
+            maximumDepth: 32;
+            maximumNodes: 200000;
+            maximumObjectKeys: 50000;
+            maximumArrayItems: 100000;
+            maximumKeyUtf8Bytes: 256;
+            maximumStringUtf8Bytes: number;
+        }>;
+        readonly blobs: {
+            readonly refs: () => readonly never[];
+            readonly budget: Readonly<{
+                maximumBlobs: 1;
+                maximumBlobBytes: 1;
+                maximumTotalBytes: 1;
+            }>;
+            readonly verify: () => readonly never[];
+        };
+    };
+}>;
+/** Builds the no-blob fixed writer and rejects a non-exact v1 candidate. */
+export declare function createSourceNavigationAttachmentWrite(input: unknown, writeSpec: FixedAttachmentWriteSpec<"attempt", SourceNavigationAttachment>): Either.Either<RecordAttachmentWrite<"attempt", never, never>, {
+    readonly code: "source-navigation-attachment-input-invalid";
+}>;
+/**
+ * Host-only semantic join. It compares explicit identities only: no source
+ * bytes are scanned and no relationship is inferred from array position.
+ */
+export declare function sourceNavigationIntegrityIssues(input: {
+    readonly payload: SourceNavigationAttachment;
+    readonly observability: AttemptObservabilityAttachment;
+    readonly sources: SourcesAttachment | undefined;
+}): readonly RecordAttachmentIssue[];