@peasant-labs/schema 0.18.0 → 0.19.0

package/dist/fixtures/session-graph.js

@@ -0,0 +1,4 @@
+import { canonicalSessionGraphFixtures } from "../internal/generated/session-graph-fixtures.gen.js";
+export function sessionGraphFixtures() {
+    return structuredClone(canonicalSessionGraphFixtures);
+}

package/dist/fixtures.d.ts

@@ -1,2 +1,4 @@
 export * from "./fixtures/quality.js";
 export * from "./fixtures/timeline.js";
+export * from "./fixtures/session-graph.js";
+export * from "./fixtures/session-graph-capability.js";

package/dist/fixtures.js

@@ -1,2 +1,4 @@
 export * from "./fixtures/quality.js";
 export * from "./fixtures/timeline.js";
+export * from "./fixtures/session-graph.js";
+export * from "./fixtures/session-graph-capability.js";

package/dist/index.d.ts

@@ -15,6 +15,7 @@ export interface RawJsonPathPolicy {
 export declare function scanRawJsonText(text: string, policy?: RawJsonPathPolicy): void;
 export declare function parseSessionDetailPayloadValue(value: unknown): import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;
 export declare function parseSessionDetailPayloadText(text: string): import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;
+export declare function parseSchemaVersionAdvertisement(text: string): string[];
 export declare function parseTranscriptContentText(text: string): import("./internal/generated/contract/zod.gen.js").TranscriptContent;
 export declare function parseServerMessageRaw(text: string): import("./internal/generated/contract/zod.gen.js").ServerMessage;
 type Detail = import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;

package/dist/index.js

@@ -2,7 +2,8 @@ export * from "./internal/generated/public-contract.gen.js";
 export * from "./internal/generated/enums.gen.js";
 export * from "./internal/generated/content-capabilities.gen.js";
 export * from "./internal/generated/versions.gen.js";
-import { zNativeMetadataRecord, zTurnDetail, zProjectHash, zServerMessage, zSessionDetailPayload, zTranscriptContent } from "./internal/generated/contract/zod.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";
 function assertProjectHash(value, operation) {
     if (!isProjectHash(value)) {
@@ -49,20 +50,75 @@ function scanRawJson(text, policy) {
 }
 export function parseSessionDetailPayloadValue(value) {
     rejectExplicitNullEvidence(value);
-    const payload = zSessionDetailPayload.parse(value);
+    validateRawGraphValue(value);
+    const normalized = structuredClone(value);
+    normalizeEmptyOptionalPublicRefs(normalized);
+    const payload = zSessionDetailPayload.parse(normalized);
     validateSessionDetail(payload);
     return payload;
 }
+function normalizeEmptyOptionalPublicRefs(value) {
+    if (!isRecord(value))
+        return;
+    if (value.parentSessionId === null)
+        delete value.parentSessionId;
+    for (const relation of Array.isArray(value.relationships) ? value.relationships : []) {
+        if (isRecord(relation) && isRecord(relation.anchor)) {
+            if (relation.anchor.sourceEntryRef === "")
+                delete relation.anchor.sourceEntryRef;
+            if (relation.anchor.sourceRevisionRef === "")
+                delete relation.anchor.sourceRevisionRef;
+        }
+    }
+    const visitTurns = (turns) => {
+        if (!Array.isArray(turns))
+            return;
+        for (const turn of turns)
+            if (isRecord(turn)) {
+                if (turn.sourceEntryRef === "")
+                    delete turn.sourceEntryRef;
+                for (const tool of Array.isArray(turn.toolCalls) ? turn.toolCalls : [])
+                    if (isRecord(tool)) {
+                        if (tool.callEntryRef === "")
+                            delete tool.callEntryRef;
+                        if (tool.resultEntryRef === "")
+                            delete tool.resultEntryRef;
+                    }
+                for (const provenance of [turn.provenance, ...(Array.isArray(turn.toolCalls) ? turn.toolCalls.flatMap(tool => isRecord(tool) ? [tool.callProvenance, tool.resultProvenance] : []) : [])]) {
+                    if (isRecord(provenance) && provenance.submissionRef === "")
+                        delete provenance.submissionRef;
+                }
+            }
+    };
+    visitTurns(value.turns);
+    for (const section of Array.isArray(value.earlierHistory) ? value.earlierHistory : [])
+        if (isRecord(section))
+            visitTurns(section.turns);
+}
 export function parseSessionDetailPayloadText(text) {
     scanRawJsonText(text, { maxDocumentBytes: 8 << 20, maxDocumentDepth: 64, opaqueMetadataPointers: ["/nativeMetadata/*/data"] });
     return parseSessionDetailPayloadValue(JSON.parse(text));
 }
+export function parseSchemaVersionAdvertisement(text) {
+    scanRawJsonText(text, { maxDocumentBytes: 1 << 20, maxDocumentDepth: 16 });
+    const value = JSON.parse(text);
+    if (!isRecord(value))
+        throw new TypeError("Schema capability validation failed at @peasant-labs/schema parseSchemaVersionAdvertisement during discovery decoding: response is not an object; callers cannot negotiate preservation support; send a JSON object and retry.");
+    if (value.contentCapabilities === null)
+        throw new TypeError("Schema capability validation failed at @peasant-labs/schema parseSchemaVersionAdvertisement during discovery decoding: contentCapabilities is null; callers cannot distinguish omission from malformed support; omit it or send an array of strings.");
+    if (value.contentCapabilities === undefined)
+        return [];
+    if (!Array.isArray(value.contentCapabilities) || value.contentCapabilities.some((token) => typeof token !== "string"))
+        throw new TypeError("Schema capability validation failed at @peasant-labs/schema parseSchemaVersionAdvertisement during discovery decoding: contentCapabilities is not an array of strings; callers cannot negotiate support; send opaque string tokens and retry.");
+    return [...value.contentCapabilities];
+}
 export function parseTranscriptContentText(text) {
     scanRawJsonText(text, { maxDocumentBytes: 8 << 20, maxDocumentDepth: 64, opaqueMetadataPointers: ["/sessionDetail/nativeMetadata/*/data"] });
     const raw = JSON.parse(text);
-    if (isRecord(raw))
-        rejectExplicitNullEvidence(raw.sessionDetail);
-    const content = zTranscriptContent.parse(raw);
+    if (!isRecord(raw))
+        return zTranscriptContent.parse(raw);
+    const normalizedEnvelope = { ...raw, sessionDetail: parseSessionDetailPayloadValue(raw.sessionDetail) };
+    const content = zTranscriptContent.parse(normalizedEnvelope);
     if (content.sessionDetail === undefined || content.sessionDetail === null)
         failSemantic("sessionDetail is required");
     parseSessionDetailPayloadValue(content.sessionDetail);
@@ -76,13 +132,10 @@ export function parseServerMessageRaw(text) {
         scanRawJsonText(text, { maxDocumentBytes: 8 << 20, maxDocumentDepth: 64, opaqueMetadataPointers: ["/data/nativeMetadata/*/data"] });
     }
     const value = JSON.parse(text);
-    if (isRecord(value) && value.type === "session_detail")
-        rejectExplicitNullEvidence(value.data);
-    const message = zServerMessage.parse(value);
-    if (message.type === "session_detail") {
-        parseSessionDetailPayloadValue(message.data);
-    }
-    return message;
+    const normalized = isRecord(value) && value.type === "session_detail"
+        ? { ...value, data: parseSessionDetailReadPayloadValue(value.data) }
+        : value;
+    return zServerMessage.parse(normalized);
 }
 class RawJsonScanner {
     text;
@@ -244,29 +297,75 @@ 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) {
-    const turns = validateTurnEvidence(payload.turns ?? []);
-    if ((payload.nativeMetadata?.length ?? 0) > 0 && String(payload.harness) !== "pi")
-        failSemantic("Pi native metadata requires harness pi");
-    validateMetadataRecords(payload.nativeMetadata ?? [], turns);
+    validateRelationships(payload);
+    const state = newDetailState(payload);
+    const turns = validateTurnEvidence(payload.turns ?? [], state);
+    validateMetadataRecords(payload.nativeMetadata ?? [], turns, state);
+    for (const section of payload.earlierHistory ?? []) {
+        const earlierTurns = validateTurnEvidence(section.turns ?? [], state);
+        validateMetadataRecords(section.nativeMetadata ?? [], earlierTurns, state);
+    }
+    if (state.nativeCount > 0 && String(payload.harness) !== "pi")
+        failSemantic("Pi native metadata requires harness pi across every history partition");
 }
+function parseSessionDetailReadPayloadValue(value) {
+    rejectExplicitNullEvidence(value);
+    if (!isRecord(value))
+        failSemantic("session detail read payload is not an object");
+    const durable = { ...value };
+    delete durable.relationshipNavigation;
+    const normalized = parseSessionDetailPayloadValue(durable);
+    return zSessionDetailReadPayload.parse(Object.hasOwn(value, "relationshipNavigation")
+        ? { ...normalized, relationshipNavigation: value.relationshipNavigation }
+        : normalized);
+}
+function validateRelationships(payload) {
+    const seen = new Set();
+    let startedBy;
+    for (const relationship of payload.relationships ?? []) {
+        if (seen.has(relationship.kind))
+            failSemantic("relationship kind occurs more than once");
+        seen.add(relationship.kind);
+        const known = relationship.targetState === "target_known" || relationship.targetState === "target_known_retained";
+        if (known !== (relationship.targetLocalId != null))
+            failSemantic("relationship target state and targetLocalId presence disagree");
+        if (relationship.targetLocalId != null && !validSessionId(relationship.targetLocalId))
+            failSemantic("relationship targetLocalId is malformed");
+        if (relationship.anchor != null) {
+            if (relationship.kind !== "context_from" || !known)
+                failSemantic("anchor is allowed only on a known context_from relationship");
+            const exact = relationship.anchor.kind !== "general_source_session";
+            const hasEntry = relationship.anchor.sourceEntryRef !== undefined, hasRevision = relationship.anchor.sourceRevisionRef !== undefined;
+            if ((!exact && (hasEntry || hasRevision)) || (exact && (!hasEntry || !hasRevision)))
+                failSemantic("anchor references disagree with anchor kind");
+            if (exact && (!validRef(relationship.anchor.sourceEntryRef) || !validRef(relationship.anchor.sourceRevisionRef)))
+                failSemantic("anchor reference is invalid");
+        }
+        if (relationship.kind === "started_by" && known)
+            startedBy = relationship.targetLocalId ?? undefined;
+    }
+    if ((payload.relationships?.length ?? 0) > 0 && payload.parentSessionId != null && payload.parentSessionId !== startedBy)
+        failSemantic("parentSessionId disagrees with durable started_by relationship");
+}
+function validSessionId(value) { return !value.includes("/") && !value.includes("\\") && !value.includes("..") && /^(?:[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}|agent-[a-f0-9]+|ses_[a-zA-Z0-9]+|sess_[a-zA-Z0-9]+|msg_[a-zA-Z0-9]+|[A-Z2-7]{26}|[0-9]{8}T[0-9]{6}\.[0-9]{9}Z-[A-Z2-7]{26})$/.test(value); }
+function newDetailState(payload) { return { strictBlockIdentity: requiredContentCapabilities(payload).includes(KnownContentCapability.SessionGraphProvenanceV1), blockRefs: new Set(), owners: new Set(), sources: new Set(), toolIds: new Set(), nativeIds: new Set(), nativeSources: new Set(), nativeCount: 0, nativeBytes: 0 }; }
 // Producers can validate metadata before attaching it to a harness envelope.
 // The full detail parsers reuse this same record and target validation.
 export function parseNativeMetadataRecordsValue(value, targets = []) {
     rejectExplicitNullEvidence({ nativeMetadata: value, turns: targets });
     const turns = zTurnDetail.array().parse(targets);
     const records = zNativeMetadataRecord.array().parse(value);
-    validateMetadataRecords(records, validateTurnEvidence(turns));
+    const state = newDetailState({ turns });
+    validateMetadataRecords(records, validateTurnEvidence(turns, state), state);
     return records;
 }
 export function parseNativeMetadataRecordsText(text, targets = []) {
     scanRawJsonText(text, { maxDocumentBytes: 8 << 20, maxDocumentDepth: 64, opaqueMetadataPointers: ["/*/data"] });
     return parseNativeMetadataRecordsValue(JSON.parse(text), targets);
 }
-function validateTurnEvidence(targets) {
-    const owners = new Set();
-    const sources = new Set();
+function validateTurnEvidence(targets, state = newDetailState({ turns: targets })) {
+    const blockRefs = state.blockRefs, owners = state.owners, sources = state.sources, toolIds = state.toolIds;
     const turnIndexes = new Set();
-    const toolIds = new Set();
     const turns = new Map();
     for (const turn of targets) {
         if (turn.observedModel !== undefined && (turn.role !== "assistant" || !validUnicode(turn.observedModel)))
@@ -275,8 +374,15 @@ function validateTurnEvidence(targets) {
             failSemantic("duplicate turn index makes metadata attachment ambiguous");
         turnIndexes.add(turn.index);
         turns.set(turn.index, turn);
-        if (turn.sourceEntryRef !== undefined && !validOptionalRef(turn.sourceEntryRef))
-            failSemantic("turn source reference is invalid or exceeds 96 bytes");
+        if (turn.sourceEntryRef !== undefined && (!validOptionalRef(turn.sourceEntryRef) || (state.strictBlockIdentity && blockRefs.has(turn.sourceEntryRef))))
+            failSemantic("turn source reference is invalid, duplicated, or exceeds 96 bytes");
+        if (turn.sourceEntryRef !== undefined)
+            blockRefs.add(turn.sourceEntryRef);
+        if (turn.provenance != null)
+            validateProvenance(turn.provenance);
+        const projected = turn.sourceEntryRef !== undefined || turn.provenance !== undefined || (turn.toolCalls ?? []).some((tool) => tool.callEntryRef !== undefined || tool.resultEntryRef !== undefined || tool.callProvenance !== undefined || tool.resultProvenance !== undefined);
+        if (projected && (((turn.depth ?? 0) === 0) !== (turn.parentIndex == null)))
+            failSemantic("turn depth and parentIndex disagree");
         if (turn.usage != null) {
             if (!((turn.role === "assistant" && turn.usage.scope === "assistant") || (turn.role === "system" && turn.usage.scope === "summary")))
                 failSemantic("turn role and usage scope disagree");
@@ -287,16 +393,22 @@ function validateTurnEvidence(targets) {
         for (const tool of turn.toolCalls ?? []) {
             if (tool.namespace !== undefined && !validUnicode(tool.namespace))
                 failSemantic("tool namespace contains invalid Unicode; provide a valid string or omit unrecorded namespace");
+            if (tool.callProvenance != null)
+                validateProvenance(tool.callProvenance);
+            if (tool.resultProvenance != null)
+                validateProvenance(tool.resultProvenance);
             if (!validOptionalRef(tool.id))
                 failSemantic("tool id reference is invalid or exceeds 96 bytes");
             if (tool.id && toolIds.has(tool.id))
                 failSemantic("duplicate tool call id makes metadata attachment ambiguous");
             if (tool.id)
                 toolIds.add(tool.id);
-            if (tool.callEntryRef !== undefined && !validOptionalRef(tool.callEntryRef))
-                failSemantic("tool call reference is invalid or exceeds 96 bytes");
-            if (tool.resultEntryRef !== undefined && !validOptionalRef(tool.resultEntryRef))
-                failSemantic("tool result reference is invalid or exceeds 96 bytes");
+            for (const ref of [tool.callEntryRef, tool.resultEntryRef]) {
+                if (ref !== undefined && (!validOptionalRef(ref) || (state.strictBlockIdentity && blockRefs.has(ref))))
+                    failSemantic("tool reference is invalid, duplicated, or exceeds 96 bytes");
+                if (ref !== undefined)
+                    blockRefs.add(ref);
+            }
             if (tool.usage != null) {
                 if (tool.usage.scope !== "tool" || !tool.resultEntryRef || tool.usage.sourceEntryRef !== tool.resultEntryRef)
                     failSemantic("tool usage attribution disagrees");
@@ -304,23 +416,29 @@ function validateTurnEvidence(targets) {
             }
         }
     }
+    for (const turn of targets)
+        if (turn.parentIndex != null && !turns.has(turn.parentIndex))
+            failSemantic("parentIndex does not target a turn in the same partition");
     return turns;
 }
-function validateMetadataRecords(records, turns) {
-    const ids = new Set();
-    let metadataBytes = 0;
-    if (records.length > 256)
+function validateMetadataRecords(records, turns, state) {
+    const blockRefs = state.blockRefs;
+    if (state.nativeCount + records.length > 256)
         failSemantic("native metadata record count exceeds 256");
+    state.nativeCount += records.length;
     for (const metadata of records) {
-        if (!validRef(metadata.id) || !validRef(metadata.source.entryRef) || ids.has(metadata.id))
+        if (!validRef(metadata.id) || !validRef(metadata.source.entryRef) || state.nativeIds.has(metadata.id) || state.nativeSources.has(metadata.source.entryRef) || (state.strictBlockIdentity && metadata.attachment === undefined && blockRefs.has(metadata.source.entryRef)))
             failSemantic("metadata reference is invalid or duplicated");
-        ids.add(metadata.id);
+        state.nativeIds.add(metadata.id);
+        state.nativeSources.add(metadata.source.entryRef);
+        if (metadata.attachment === undefined)
+            blockRefs.add(metadata.source.entryRef);
         if (metadata.customType !== undefined && (!validUnicode(metadata.customType) || new TextEncoder().encode(metadata.customType).length > 128))
             failSemantic("customType is invalid Unicode or exceeds 128 bytes");
         validateMetadataValue(metadata.data, 1);
         const encoded = new TextEncoder().encode(JSON.stringify(metadata.data)).length;
-        metadataBytes += encoded;
-        if (encoded > 65536 || metadataBytes > 1048576)
+        state.nativeBytes += encoded;
+        if (encoded > 65536 || state.nativeBytes > 1048576)
             failSemantic("metadata data exceeds its byte budget");
         const attachment = metadata.attachment;
         const target = attachment?.turnIndex == null ? undefined : turns.get(attachment.turnIndex);
@@ -353,6 +471,13 @@ function validateMetadataRecords(records, turns) {
         }
     }
 }
+function validateProvenance(value) {
+    const sets = [[value.origin, ["submitted_input", "harness_context", "agent_output", "agent_communication", "tool_activity", "system_control", "generated_summary", "unknown"]], [value.actor, ["operator", "agent_delegate", "harness", "unknown"]], [value.delivery, ["session_admission", "guardian_review", "subagent_delivery", "inherited_context", "tool_delivery", "system_lifecycle", "unknown"]], [value.ownership, ["local", "inherited", "uncertain"]], [value.evidence, ["native_typed", "lifecycle_typed", "existing_adapter", "retained_last_good", "unknown", "conflict"]], [value.inputModality, ["none", "text", "media", "user_action", "mixed", "unknown"]]];
+    if (sets.some(([v, allowed]) => !allowed.includes(v)))
+        failSemantic("provenance dimension is missing or outside its closed set");
+    if (value.submissionRef !== undefined && value.submissionRef !== "" && !validRef(value.submissionRef))
+        failSemantic("submissionRef is invalid");
+}
 function validateUsage(usage, owners, sources) {
     if (!validRef(usage.ownerId) || !validRef(usage.sourceEntryRef) || owners.has(usage.ownerId) || sources.has(usage.sourceEntryRef))
         failSemantic("usage owner/source reference is invalid or duplicated");
@@ -428,10 +553,19 @@ function isRecord(value) { return typeof value === "object" && value !== null &&
 function rejectExplicitNullEvidence(value) {
     if (!isRecord(value))
         return;
+    if (value.inputSubmissionCount === null)
+        failSemantic("inputSubmissionCount is explicitly null");
+    if (value.inputSubmissionCount !== undefined && (typeof value.inputSubmissionCount !== "number" || !Number.isSafeInteger(value.inputSubmissionCount) || value.inputSubmissionCount < 0))
+        failSemantic("inputSubmissionCount is outside 0..9007199254740991");
     for (const turn of Array.isArray(value.turns) ? value.turns : []) {
         if (!isRecord(turn))
             continue;
+        if (turn.provenance === null)
+            failSemantic("turn provenance is explicitly null");
         const tools = Array.isArray(turn.toolCalls) ? turn.toolCalls : [];
+        for (const tool of tools)
+            if (isRecord(tool) && (tool.callProvenance === null || tool.resultProvenance === null))
+                failSemantic("folded provenance is explicitly null");
         for (const usage of [turn.usage, ...tools.map(tool => isRecord(tool) ? tool.usage : undefined)]) {
             if (!isRecord(usage) || !isRecord(usage.tokens))
                 continue;
@@ -440,6 +574,9 @@ function rejectExplicitNullEvidence(value) {
                     failSemantic(`token ${name} is explicitly null`);
         }
     }
+    for (const section of Array.isArray(value.earlierHistory) ? value.earlierHistory : [])
+        if (isRecord(section))
+            rejectExplicitNullEvidence({ turns: section.turns, nativeMetadata: section.nativeMetadata });
     for (const record of Array.isArray(value.nativeMetadata) ? value.nativeMetadata : []) {
         if (!isRecord(record))
             continue;
@@ -458,4 +595,52 @@ function rejectExplicitNullEvidence(value) {
             failSemantic("metadata source.messageRole is forbidden for this kind");
     }
 }
+const rootForbiddenGraphFields = new Set(["relationshipNavigation", "label", "explanation", "cooked", "collapsed", "url", "resolved", "detail"]);
+const forbiddenGraphFields = new Set(["relationshipNavigation", "status", "transcriptId", "label", "explanation", "cooked", "collapsed", "url", "resolved", "detail"]);
+function validateRawGraphValue(value) {
+    if (!isRecord(value))
+        return;
+    for (const key of Object.keys(value))
+        if (rootForbiddenGraphFields.has(key))
+            failSemantic(`durable payload contains forbidden read-only or cooked field ${key}`);
+    for (const relationship of Array.isArray(value.relationships) ? value.relationships : [])
+        if (isRecord(relationship)) {
+            for (const key of Object.keys(relationship))
+                if (!["kind", "targetState", "targetLocalId", "evidence", "anchor"].includes(key))
+                    failSemantic(`relationship contains forbidden field ${key}`);
+            if (isRecord(relationship.anchor))
+                for (const key of Object.keys(relationship.anchor))
+                    if (!["kind", "sourceEntryRef", "sourceRevisionRef"].includes(key))
+                        failSemantic(`anchor contains forbidden field ${key}`);
+        }
+    const visitTurns = (turns) => {
+        if (!Array.isArray(turns))
+            return;
+        for (const turn of turns) {
+            if (!isRecord(turn))
+                continue;
+            for (const key of Object.keys(turn))
+                if (forbiddenGraphFields.has(key))
+                    failSemantic(`turn contains forbidden read-only or cooked field ${key}`);
+            for (const tool of Array.isArray(turn.toolCalls) ? turn.toolCalls : [])
+                if (isRecord(tool))
+                    for (const key of Object.keys(tool))
+                        if (forbiddenGraphFields.has(key))
+                            failSemantic(`tool contains forbidden read-only or cooked field ${key}`);
+            for (const provenance of [turn.provenance, ...(Array.isArray(turn.toolCalls) ? turn.toolCalls.flatMap((tool) => isRecord(tool) ? [tool.callProvenance, tool.resultProvenance] : []) : [])])
+                if (isRecord(provenance))
+                    for (const key of Object.keys(provenance))
+                        if (!["origin", "actor", "delivery", "ownership", "evidence", "inputModality", "submissionRef"].includes(key))
+                            failSemantic(`provenance contains forbidden field ${key}`);
+        }
+    };
+    visitTurns(value.turns);
+    for (const section of Array.isArray(value.earlierHistory) ? value.earlierHistory : [])
+        if (isRecord(section)) {
+            for (const key of Object.keys(section))
+                if (!["state", "turns", "nativeMetadata"].includes(key))
+                    failSemantic(`earlier history contains forbidden field ${key}`);
+            visitTurns(section.turns);
+        }
+}
 function failSemantic(reason) { throw new TypeError(`Session detail validation failed at @peasant-labs/schema public parser during semantic validation: ${reason}; consumers cannot safely attribute transcript evidence; correct the payload and retry.`); }

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

@@ -1,3 +1,4 @@
+import type { SessionDetailPayload } from "./contract/zod.gen.js";
 /**
  * KnownContentCapability is the closed inventory of content-capability tokens known to this
  * pinned schema release. It is intentionally distinct from the OPEN discovery
@@ -11,8 +12,13 @@ export declare const KnownContentCapability: Readonly<{
     readonly DetailedUsageV1: "detailed_usage_v1";
     readonly NativeMetadataV1: "native_metadata_v1";
     readonly ObservedModelV1: "observed_model_v1";
+    readonly SessionGraphProvenanceV1: "session_graph_provenance_v1";
     readonly ToolNamespaceV1: "tool_namespace_v1";
 }>;
 export type KnownContentCapability = (typeof KnownContentCapability)[keyof typeof KnownContentCapability];
 export declare const AllContentCapabilities: readonly KnownContentCapability[];
 export declare function isContentCapability(value: unknown): value is KnownContentCapability;
+export declare function knownContentCapabilities(values: readonly string[]): KnownContentCapability[];
+export declare function missingContentCapabilities(advertised: readonly string[], required: readonly KnownContentCapability[]): KnownContentCapability[];
+export declare function validateContentCapabilityAdvertisements(values: readonly string[]): void;
+export declare function requiredContentCapabilities(detail: SessionDetailPayload): KnownContentCapability[];

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

@@ -1,4 +1,3 @@
-// Code generated from the canonical Go/OpenAPI contract. DO NOT EDIT.
 /**
  * KnownContentCapability is the closed inventory of content-capability tokens known to this
  * pinned schema release. It is intentionally distinct from the OPEN discovery
@@ -12,9 +11,55 @@ export const KnownContentCapability = Object.freeze({
     DetailedUsageV1: "detailed_usage_v1",
     NativeMetadataV1: "native_metadata_v1",
     ObservedModelV1: "observed_model_v1",
+    SessionGraphProvenanceV1: "session_graph_provenance_v1",
     ToolNamespaceV1: "tool_namespace_v1",
 });
-export const AllContentCapabilities = Object.freeze([KnownContentCapability.DetailedUsageV1, KnownContentCapability.NativeMetadataV1, KnownContentCapability.ObservedModelV1, KnownContentCapability.ToolNamespaceV1]);
+export const AllContentCapabilities = Object.freeze([KnownContentCapability.DetailedUsageV1, KnownContentCapability.NativeMetadataV1, KnownContentCapability.ObservedModelV1, KnownContentCapability.SessionGraphProvenanceV1, KnownContentCapability.ToolNamespaceV1]);
 export function isContentCapability(value) {
     return typeof value === "string" && AllContentCapabilities.includes(value);
 }
+export function knownContentCapabilities(values) {
+    return [...new Set(values.filter(isContentCapability))].sort();
+}
+export function missingContentCapabilities(advertised, required) {
+    const present = new Set(knownContentCapabilities(advertised));
+    return [...new Set(required)].filter((token) => !present.has(token)).sort();
+}
+export function validateContentCapabilityAdvertisements(values) {
+    for (let index = 0; index < values.length; index++) {
+        const token = values[index];
+        if (token === undefined || !isContentCapability(token))
+            throw new TypeError(`content capability producer validation failed at @peasant-labs/schema validateContentCapabilityAdvertisements: unknown token ${JSON.stringify(token)}; callers cannot advertise unimplemented preservation; emit only AllContentCapabilities after deployment support is proven`);
+        const previous = values[index - 1];
+        if (previous !== undefined && previous === token)
+            throw new TypeError("content capability producer validation failed at @peasant-labs/schema validateContentCapabilityAdvertisements: token is duplicated; callers cannot emit a canonical advertisement; deduplicate and sort the known inventory");
+        if (previous !== undefined && previous > token)
+            throw new TypeError("content capability producer validation failed at @peasant-labs/schema validateContentCapabilityAdvertisements: tokens are not in canonical lexicographic order; callers cannot emit a canonical advertisement; sort the unique known inventory");
+    }
+}
+function visitTurns(turns, found) {
+    for (const turn of turns ?? []) {
+        if ((turn.observedModel ?? "") !== "")
+            found.add(KnownContentCapability.ObservedModelV1);
+        if (turn.toolCalls?.some((tool) => tool.namespace !== undefined))
+            found.add(KnownContentCapability.ToolNamespaceV1);
+        if (turn.usage != null || turn.toolCalls?.some((tool) => tool.usage != null))
+            found.add(KnownContentCapability.DetailedUsageV1);
+        if (turn.provenance != null || turn.toolCalls?.some((tool) => tool.callProvenance != null || tool.resultProvenance != null))
+            found.add(KnownContentCapability.SessionGraphProvenanceV1);
+    }
+}
+export function requiredContentCapabilities(detail) {
+    const found = new Set();
+    if (detail.inputSubmissionCount !== undefined || detail.rootSessionId != null || (detail.purpose ?? "") !== "" || (detail.relationships?.length ?? 0) > 0 || (detail.earlierHistory?.length ?? 0) > 0)
+        found.add(KnownContentCapability.SessionGraphProvenanceV1);
+    if ((detail.nativeMetadata?.length ?? 0) > 0)
+        found.add(KnownContentCapability.NativeMetadataV1);
+    visitTurns(detail.turns, found);
+    for (const section of detail.earlierHistory ?? []) {
+        if ((section.nativeMetadata?.length ?? 0) > 0)
+            found.add(KnownContentCapability.NativeMetadataV1);
+        visitTurns(section.turns, found);
+    }
+    return [...found].sort();
+}