@peasant-labs/schema 0.23.0 → 0.25.0

package/dist/fixtures/session-graph-capability.d.ts

@@ -1,11 +1,27 @@
 export declare function sessionGraphCapabilityFixtures(): {
     readonly requiredNames: {
-        readonly derivation: readonly ["legacy-empty", "root-null", "usage-null", "model-only", "source-ref-only", "count-only-zero", "count-only-positive", "root-only", "purpose-only-interaction", "purpose-only-delegated", "purpose-only-helper", "purpose-only-unknown", "relationship-only", "main-deeper-provenance", "folded-call-provenance", "folded-result-provenance", "earlier-only", "earlier-nested-tool-native-usage-model", "navigation-only-read"];
-        readonly reader: readonly ["advertisement-omitted", "advertisement-empty", "advertisement-null", "advertisement-unknown-duplicate-unordered", "advertisement-future-suffix"];
-        readonly producer: readonly ["producer-canonical-four", "producer-unsorted-four", "producer-duplicate", "producer-unknown"];
+        readonly derivation: readonly ["legacy-empty", "root-null", "usage-null", "model-only", "source-ref-only", "count-only-zero", "count-only-positive", "root-only", "purpose-only-interaction", "purpose-only-delegated", "purpose-only-helper", "purpose-only-unknown", "relationship-only", "main-deeper-provenance", "folded-call-provenance", "folded-result-provenance", "earlier-only", "earlier-nested-tool-native-usage-model", "navigation-only-read", "retained-accumulates-all"];
+        readonly reader: readonly ["advertisement-omitted", "advertisement-empty", "advertisement-null", "advertisement-unknown-duplicate-unordered", "advertisement-future-suffix", "advertisement-retained-duplicate"];
+        readonly producer: readonly ["producer-canonical-four", "producer-unsorted-four", "producer-duplicate", "producer-unknown", "producer-canonical-retained", "producer-unsorted-retained", "producer-duplicate-retained"];
     };
     readonly derivation: {
         readonly cases: readonly [{
+            readonly name: "retained-accumulates-all";
+            readonly classification: "must-pass";
+            readonly provenance: {
+                readonly source: "requirement";
+                readonly ref: "content-capability-negotiation";
+            };
+            readonly mutation: {
+                readonly description: "Retained evidence accumulates every existing preservation requirement";
+            };
+            readonly input: {
+                readonly detailJSON: "{\"id\":\"fixture-session\",\"harness\":\"pi\",\"startTime\":\"2020-01-01T00:00:00Z\",\"endTime\":\"2020-01-01T00:00:00Z\",\"durationMins\":0,\"totalTokens\":0,\"tokensIn\":0,\"tokensOut\":0,\"turnCount\":1,\"toolCallCount\":1,\"purpose\":\"interaction\",\"turns\":[{\"index\":0,\"role\":\"assistant\",\"depth\":0,\"content\":\"\",\"timestamp\":\"2020-01-01T00:00:00Z\",\"sourceEntryRef\":\"e1\",\"observedModel\":\"provider/model\",\"usage\":{\"ownerId\":\"u1\",\"sourceEntryRef\":\"e1\",\"scope\":\"assistant\",\"completeness\":\"unknown\"},\"toolCalls\":[{\"id\":\"t1\",\"name\":\"tool\",\"namespace\":\"extension\",\"arguments\":\"\",\"result\":\"\"}]}],\"nativeMetadata\":[{\"id\":\"n1\",\"kind\":\"pi.custom.data\",\"source\":{\"entryRef\":\"custom1\",\"sourceType\":\"pi.custom\"},\"customType\":\"extension\",\"data\":{}}],\"diagnostics\":{\"partial\":true},\"retainedUnknown\":[{\"sourceRef\":\"source-0\",\"recordIndex\":2,\"position\":4,\"pointer\":\"\",\"namespace\":\"record\",\"kind\":\"future\",\"payload\":\"{\\\"type\\\":\\\"future\\\"}\"}]}";
+            };
+            readonly expected: {
+                readonly capabilities: readonly ["detailed_usage_v1", "native_metadata_v1", "observed_model_v1", "retained_unknown_v1", "session_graph_provenance_v1", "tool_namespace_v1"];
+            };
+        }, {
             readonly name: "legacy-empty";
             readonly classification: "must-pass";
             readonly provenance: {
@@ -303,6 +319,22 @@ export declare function sessionGraphCapabilityFixtures(): {
     };
     readonly reader: {
         readonly cases: readonly [{
+            readonly name: "advertisement-retained-duplicate";
+            readonly classification: "must-pass";
+            readonly provenance: {
+                readonly source: "requirement";
+                readonly ref: "content-capability-negotiation";
+            };
+            readonly mutation: {
+                readonly description: "Exact retained token survives forward-open discovery";
+            };
+            readonly input: {
+                readonly json: "{\"contentCapabilities\":[\"retained_unknown_v1\",\"retained_unknown_v2\",\"retained_unknown_v1\",\"session_graph_provenance_v1\"]}";
+            };
+            readonly expected: {
+                readonly known: readonly ["retained_unknown_v1", "session_graph_provenance_v1"];
+            };
+        }, {
             readonly name: "advertisement-omitted";
             readonly classification: "must-pass";
             readonly provenance: {
@@ -386,6 +418,54 @@ export declare function sessionGraphCapabilityFixtures(): {
     };
     readonly producer: {
         readonly cases: readonly [{
+            readonly name: "producer-canonical-retained";
+            readonly classification: "must-pass";
+            readonly provenance: {
+                readonly source: "requirement";
+                readonly ref: "content-capability-negotiation";
+            };
+            readonly mutation: {
+                readonly description: "Emits sorted accumulated inventory";
+            };
+            readonly input: {
+                readonly tokens: readonly ["detailed_usage_v1", "native_metadata_v1", "observed_model_v1", "retained_unknown_v1", "session_graph_provenance_v1", "tool_namespace_v1"];
+            };
+            readonly expected: {
+                readonly accepted: true;
+            };
+        }, {
+            readonly name: "producer-unsorted-retained";
+            readonly classification: "must-fail";
+            readonly provenance: {
+                readonly source: "boundary";
+                readonly ref: "content-capability-negotiation";
+            };
+            readonly mutation: {
+                readonly description: "Retained token out of canonical order refuses";
+            };
+            readonly input: {
+                readonly tokens: readonly ["retained_unknown_v1", "observed_model_v1"];
+            };
+            readonly expected: {
+                readonly errorContains: "canonical lexicographic order";
+            };
+        }, {
+            readonly name: "producer-duplicate-retained";
+            readonly classification: "must-fail";
+            readonly provenance: {
+                readonly source: "boundary";
+                readonly ref: "content-capability-negotiation";
+            };
+            readonly mutation: {
+                readonly description: "Duplicate retained token refuses";
+            };
+            readonly input: {
+                readonly tokens: readonly ["retained_unknown_v1", "retained_unknown_v1"];
+            };
+            readonly expected: {
+                readonly errorContains: "duplicated";
+            };
+        }, {
             readonly name: "producer-canonical-four";
             readonly classification: "must-pass";
             readonly provenance: {

package/dist/fixtures/session-graph.d.ts

@@ -5246,6 +5246,7 @@ export declare function sessionGraphFixtures(): {
                             readonly total_turns: 0;
                             readonly total_duration_ms: 0;
                             readonly total_tokens: 0;
+                            readonly pull_request_count: 0;
                         };
                         readonly models: readonly [];
                         readonly contributors: readonly [];
@@ -5291,6 +5292,7 @@ export declare function sessionGraphFixtures(): {
                             readonly total_turns: 0;
                             readonly total_duration_ms: 0;
                             readonly total_tokens: 0;
+                            readonly pull_request_count: 0;
                         };
                         readonly models: readonly [];
                         readonly contributors: readonly [];
@@ -5345,6 +5347,7 @@ export declare function sessionGraphFixtures(): {
                             readonly total_turns: 0;
                             readonly total_duration_ms: 0;
                             readonly total_tokens: 0;
+                            readonly pull_request_count: 0;
                         };
                         readonly models: readonly [];
                         readonly contributors: readonly [];
@@ -5392,6 +5395,7 @@ export declare function sessionGraphFixtures(): {
                             readonly total_turns: 0;
                             readonly total_duration_ms: 0;
                             readonly total_tokens: 0;
+                            readonly pull_request_count: 0;
                         };
                         readonly models: readonly [];
                         readonly contributors: readonly [];
@@ -6145,6 +6149,7 @@ export declare function sessionGraphFixtures(): {
                                     readonly inputSubmissionCount: 1;
                                     readonly model: "codex";
                                     readonly syncStatus: "synced";
+                                    readonly previouslyPushed: true;
                                 };
                             };
                             readonly helperGroups: readonly [{
@@ -6203,6 +6208,7 @@ export declare function sessionGraphFixtures(): {
                                     readonly inputSubmissionCount: 0;
                                     readonly model: "codex";
                                     readonly syncStatus: "synced";
+                                    readonly previouslyPushed: true;
                                 };
                             };
                             readonly helperGroups: readonly [{
@@ -6472,6 +6478,10 @@ export declare function sessionGraphFixtures(): {
                                     readonly owner_username: "owner";
                                     readonly owner_avatar_url: null;
                                     readonly owner_is_discoverable: true;
+                                    readonly pull_requests: {
+                                        readonly count: 0;
+                                        readonly recent: readonly [];
+                                    };
                                 };
                             };
                             readonly helperGroups: readonly [{
@@ -6641,6 +6651,10 @@ export declare function sessionGraphFixtures(): {
                                     readonly owner_username: "owner";
                                     readonly owner_avatar_url: null;
                                     readonly owner_is_discoverable: true;
+                                    readonly pull_requests: {
+                                        readonly count: 0;
+                                        readonly recent: readonly [];
+                                    };
                                     readonly input_submission_count: 0;
                                 };
                             };

package/dist/index.js

@@ -5,6 +5,7 @@ export * from "./internal/generated/versions.gen.js";
 import { requiredContentCapabilities, KnownContentCapability } from "./internal/generated/content-capabilities.gen.js";
 import { zNativeMetadataRecord, zTurnDetail, zProjectHash, zServerMessage, zSessionDetailPayload, zSessionDetailReadPayload, zTranscriptContent } from "./internal/generated/contract/zod.gen.js";
 import { maxNativeMetadataStringBytes } from "./internal/generated/metadata-limits.gen.js";
+import { wireAliasShapes } from "./internal/generated/wire-alias-shapes.gen.js";
 function assertProjectHash(value, operation) {
     if (!isProjectHash(value)) {
         const rendered = renderProjectHashInput(value);
@@ -49,6 +50,7 @@ function scanRawJson(text, policy) {
     return scanner;
 }
 export function parseSessionDetailPayloadValue(value) {
+    rejectWireAliases(value, "SessionDetailPayload");
     rejectExplicitNullEvidence(value);
     validateRawGraphValue(value);
     const normalized = structuredClone(value);
@@ -117,6 +119,7 @@ export function parseTranscriptContentText(text) {
     const raw = JSON.parse(text);
     if (!isRecord(raw))
         return zTranscriptContent.parse(raw);
+    rejectWireAliases(raw, "TranscriptContent");
     const normalizedEnvelope = { ...raw, sessionDetail: parseSessionDetailPayloadValue(raw.sessionDetail) };
     const content = zTranscriptContent.parse(normalizedEnvelope);
     if (content.sessionDetail === undefined || content.sessionDetail === null)
@@ -297,6 +300,7 @@ class RawJsonScanner {
 }
 function pointerMatches(pattern, path) { const expected = pattern.split("/"); const actual = path.split("/"); return expected.length === actual.length && expected.every((part, index) => part === "*" || part === actual[index]); }
 function validateSessionDetail(payload) {
+    validateRetainedUnknown(payload);
     validateRelationships(payload);
     const state = newDetailState(payload);
     const turns = validateTurnEvidence(payload.turns ?? [], state);
@@ -308,6 +312,77 @@ function validateSessionDetail(payload) {
     if (state.nativeCount > 0 && String(payload.harness) !== "pi")
         failSemantic("Pi native metadata requires harness pi across every history partition");
 }
+function validateRetainedUnknown(payload) {
+    if ((payload.retainedUnknown?.length ?? 0) > 0 && payload.diagnostics?.partial !== true)
+        failSemantic("retainedUnknown requires diagnostics.partial=true");
+    const sources = new Map();
+    for (const [index, record] of (payload.retainedUnknown ?? []).entries()) {
+        if (!Number.isSafeInteger(record.recordIndex) || !Number.isSafeInteger(record.position) || record.recordIndex < 0 || record.position < record.recordIndex)
+            failSemantic("retainedUnknown has invalid recordIndex or position");
+        // Scan strings as JSON as well: typed JS values can contain unpaired surrogates.
+        scanRawJsonText(JSON.stringify([record.sourceRef, record.namespace, record.kind, record.pointer]));
+        const previous = sources.get(record.sourceRef);
+        if (previous !== undefined && (record.position <= previous.position || record.recordIndex < previous.record))
+            failSemantic("retainedUnknown repeats or reverses a source position");
+        const pointers = previous?.record === record.recordIndex ? previous.pointers : new RetainedPointerNode();
+        if (!pointers.insert(record.pointer))
+            failSemantic("retainedUnknown duplicates or overlaps a source pointer");
+        try {
+            scanRawJsonText(record.payload, { maxDocumentBytes: 8 << 20, maxDocumentDepth: 64 });
+        }
+        catch {
+            // Native keys/paths are untrusted even when a producer claims redaction.
+            // Do not expose the scanner exception, its message, or a cause chain.
+            failSemantic(`retainedUnknown[${index}].payload failed JSON syntax or safety validation; provide one complete JSON value with valid Unicode, unique object keys, and the published byte/depth bounds`);
+        }
+        sources.set(record.sourceRef, { position: record.position, record: record.recordIndex, pointers });
+    }
+}
+class RetainedPointerNode {
+    terminal = false;
+    children = new Map();
+    insert(pointer) {
+        let node = this;
+        for (const component of pointer === "" ? [] : pointer.slice(1).split("/")) {
+            if (node.terminal)
+                return false;
+            let child = node.children.get(component);
+            if (child === undefined) {
+                child = new RetainedPointerNode();
+                node.children.set(component, child);
+            }
+            node = child;
+        }
+        if (node.terminal || node.children.size > 0)
+            return false;
+        node.terminal = true;
+        return true;
+    }
+}
+function rejectWireAliases(value, descriptor) {
+    const shape = typeof descriptor === "string" ? wireAliasShapes[descriptor] : descriptor;
+    if (shape === undefined)
+        return;
+    if (shape.items !== undefined && Array.isArray(value)) {
+        for (const item of value)
+            rejectWireAliases(item, shape.items);
+    }
+    if (shape.fields === undefined || !isRecord(value))
+        return;
+    const fields = shape.fields;
+    // All canonical contract keys are ASCII. Go's Unicode simple-fold aliases
+    // additionally include long s and Kelvin sign; lowercasing handles the latter.
+    const fold = (key) => key.replaceAll("ſ", "s").toLowerCase();
+    const canonical = new Map(Object.keys(fields).map(key => [fold(key), key]));
+    for (const key of Object.keys(value)) {
+        const name = canonical.get(fold(key));
+        if (name !== undefined && key !== name)
+            failSemantic(`key ${key} aliases canonical field ${name}; use only exact published field names`);
+        const child = fields[key];
+        if (child !== undefined)
+            rejectWireAliases(value[key], child);
+    }
+}
 function parseSessionDetailReadPayloadValue(value) {
     rejectExplicitNullEvidence(value);
     if (!isRecord(value))

package/dist/internal/generated/content-capabilities.gen.d.ts

@@ -12,6 +12,7 @@ export declare const KnownContentCapability: Readonly<{
     readonly DetailedUsageV1: "detailed_usage_v1";
     readonly NativeMetadataV1: "native_metadata_v1";
     readonly ObservedModelV1: "observed_model_v1";
+    readonly RetainedUnknownV1: "retained_unknown_v1";
     readonly SessionGraphProvenanceV1: "session_graph_provenance_v1";
     readonly ToolNamespaceV1: "tool_namespace_v1";
 }>;

package/dist/internal/generated/content-capabilities.gen.js

@@ -11,10 +11,11 @@ export const KnownContentCapability = Object.freeze({
     DetailedUsageV1: "detailed_usage_v1",
     NativeMetadataV1: "native_metadata_v1",
     ObservedModelV1: "observed_model_v1",
+    RetainedUnknownV1: "retained_unknown_v1",
     SessionGraphProvenanceV1: "session_graph_provenance_v1",
     ToolNamespaceV1: "tool_namespace_v1",
 });
-export const AllContentCapabilities = Object.freeze([KnownContentCapability.DetailedUsageV1, KnownContentCapability.NativeMetadataV1, KnownContentCapability.ObservedModelV1, KnownContentCapability.SessionGraphProvenanceV1, KnownContentCapability.ToolNamespaceV1]);
+export const AllContentCapabilities = Object.freeze([KnownContentCapability.DetailedUsageV1, KnownContentCapability.NativeMetadataV1, KnownContentCapability.ObservedModelV1, KnownContentCapability.RetainedUnknownV1, KnownContentCapability.SessionGraphProvenanceV1, KnownContentCapability.ToolNamespaceV1]);
 export function isContentCapability(value) {
     return typeof value === "string" && AllContentCapabilities.includes(value);
 }
@@ -55,6 +56,8 @@ export function requiredContentCapabilities(detail) {
         found.add(KnownContentCapability.SessionGraphProvenanceV1);
     if ((detail.nativeMetadata?.length ?? 0) > 0)
         found.add(KnownContentCapability.NativeMetadataV1);
+    if ((detail.retainedUnknown?.length ?? 0) > 0 || detail.diagnostics !== undefined)
+        found.add(KnownContentCapability.RetainedUnknownV1);
     visitTurns(detail.turns, found);
     for (const section of detail.earlierHistory ?? []) {
         if ((section.nativeMetadata?.length ?? 0) > 0)