@peasant-labs/schema 0.53.0 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2146,6 +2146,10 @@ export declare function sessionGraphFixtures(): {
2146
2146
  }, {
2147
2147
  readonly component: "SessionDetailReadPayload";
2148
2148
  readonly field: "inputSubmissionCount";
2149
+ }, {
2150
+ readonly component: "TranscriptSessionHeader";
2151
+ readonly field: "inputSubmissionCount";
2152
+ readonly domain: "served_int64";
2149
2153
  }, {
2150
2154
  readonly component: "AuthoritativeSessionStats";
2151
2155
  readonly field: "conversationTurnCount";
@@ -2170,6 +2174,10 @@ export declare function sessionGraphFixtures(): {
2170
2174
  }, {
2171
2175
  readonly component: "SessionDetailReadPayload";
2172
2176
  readonly field: "conversationTurnCount";
2177
+ }, {
2178
+ readonly component: "TranscriptSessionHeader";
2179
+ readonly field: "conversationTurnCount";
2180
+ readonly domain: "served_int64";
2173
2181
  }, {
2174
2182
  readonly component: "QualitySession";
2175
2183
  readonly field: "conversationTurnCount";
package/dist/index.d.ts CHANGED
@@ -9,6 +9,8 @@ export { reconcileVillageContributionAttempt, villageContributionAttemptActor, t
9
9
  export { normalizeCollectiveObservationScope, encodeContributionTraversalRevision, parseContributionTraversalRevision, validateContributionHistoryQuery, type ContributionTraversalIdentity, type LocalContributionHistoryQuery } from "./collective-validation.js";
10
10
  export { collectiveFetchHTTPStatus } from "./collective-status.js";
11
11
  export { isConversationTurn } from "./conversation-turn.js";
12
+ export { isTranscriptDirectoryPositionsValid, isPositionedDirectoryPositionsValid } from "./transcript-directory-positions.js";
13
+ export { readTranscriptServedTurn, type TranscriptServedTurn } from "./transcript-served-turn.js";
12
14
  import { type ProjectHash } from "./internal/generated/contract/zod.gen.js";
13
15
  export declare function isProjectHash(value: unknown): value is ProjectHash;
14
16
  export declare function validateProjectHash(value: unknown): asserts value is ProjectHash;
@@ -19,11 +21,41 @@ export interface RawJsonPathPolicy {
19
21
  maxDocumentDepth?: number;
20
22
  opaqueMetadataPointers?: readonly string[];
21
23
  }
24
+ export type TranscriptContentReadPolicy = RawJsonPathPolicy;
25
+ /** The existing envelope source scan; its bounds and selected paths stay unchanged. */
26
+ export declare const TranscriptSourceReadPolicy: TranscriptContentReadPolicy;
27
+ /** The existing bare-detail source scan; its selected path stays unchanged. */
28
+ export declare const TranscriptSourceDetailReadPolicy: TranscriptContentReadPolicy;
29
+ /** Download scan with no additional outer byte limit and both root shapes. */
30
+ export declare const TranscriptDownloadPolicy: TranscriptContentReadPolicy;
22
31
  export declare function scanRawJsonText(text: string, policy?: RawJsonPathPolicy): void;
23
32
  export declare function parseSessionDetailPayloadValue(value: unknown): import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;
24
33
  export declare function parseSessionDetailPayloadText(text: string): import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;
34
+ export declare function parseSessionDetailPayloadTextWithPolicy(text: string, policy: TranscriptContentReadPolicy): import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;
25
35
  export declare function parseSchemaVersionAdvertisement(text: string): string[];
36
+ /** The host's served window, with both members treated as opaque exact tokens. */
37
+ export interface SegmentedReadVersionWindow {
38
+ readonly current: string;
39
+ readonly min: string;
40
+ }
41
+ /**
42
+ * Parse the segmented read window independently of content capabilities.
43
+ * Both members absent or empty mean an older, 0.1.0-only host. An incomplete
44
+ * or malformed pair is refused rather than authorizing a newer generation.
45
+ */
46
+ export declare function parseSegmentedReadVersionAdvertisement(text: string): SegmentedReadVersionWindow | null;
26
47
  export declare function parseTranscriptContentText(text: string): import("./internal/generated/contract/zod.gen.js").TranscriptContent;
48
+ export declare function parseTranscriptContentTextWithPolicy(text: string, policy: TranscriptContentReadPolicy): import("./internal/generated/contract/zod.gen.js").TranscriptContent;
49
+ export interface TranscriptDownloadRead {
50
+ readonly kind: "strict" | "legacy" | "records";
51
+ readonly detail?: unknown;
52
+ readonly records?: readonly unknown[];
53
+ }
54
+ export type TranscriptDownloadTextFailure = "syntax" | "depth" | "duplicate-key" | "unicode" | "retained-unknown" | "semantic-limit" | "shape" | "outer-size" | "embedded-public-root";
55
+ /** The in-band strict core of the served content boundary. */
56
+ export declare function transcriptContentIsStrict(detail: unknown): boolean;
57
+ /** Parse one authorized body for export, preserving the served detail value. */
58
+ export declare function parseTranscriptDownloadText(text: string): TranscriptDownloadRead;
27
59
  export declare function parseServerMessageRaw(text: string): import("./internal/generated/contract/zod.gen.js").ServerMessage;
28
60
  type Detail = import("./internal/generated/contract/zod.gen.js").SessionDetailPayload;
29
61
  export declare function parseNativeMetadataRecordsValue(value: unknown, targets?: unknown): NonNullable<Detail["nativeMetadata"]>;
package/dist/index.js CHANGED
@@ -9,8 +9,10 @@ export { reconcileVillageContributionAttempt, villageContributionAttemptActor }
9
9
  export { normalizeCollectiveObservationScope, encodeContributionTraversalRevision, parseContributionTraversalRevision, validateContributionHistoryQuery } from "./collective-validation.js";
10
10
  export { collectiveFetchHTTPStatus } from "./collective-status.js";
11
11
  export { isConversationTurn } from "./conversation-turn.js";
12
+ export { isTranscriptDirectoryPositionsValid, isPositionedDirectoryPositionsValid } from "./transcript-directory-positions.js";
13
+ export { readTranscriptServedTurn } from "./transcript-served-turn.js";
12
14
  import { requiredContentCapabilities, KnownContentCapability } from "./internal/generated/content-capabilities.gen.js";
13
- import { zNativeMetadataRecord, zTurnDetail, zProjectHash, zServerMessage, zSessionDetailPayload, zSessionDetailReadPayload, zTranscriptContent } from "./internal/generated/contract/zod.gen.js";
15
+ import { zHarness, zObservedModelID, zNativeMetadataRecord, zTurnDetail, zProjectHash, zServerMessage, zSessionDetailPayload, zSessionDetailReadPayload, zTranscriptContent } from "./internal/generated/contract/zod.gen.js";
14
16
  import { maxNativeMetadataStringBytes } from "./internal/generated/metadata-limits.gen.js";
15
17
  import { wireAliasShapes } from "./internal/generated/wire-alias-shapes.gen.js";
16
18
  function assertProjectHash(value, operation) {
@@ -45,6 +47,26 @@ export function newProjectHash(raw) {
45
47
  assertProjectHash(raw, "newProjectHash");
46
48
  return raw;
47
49
  }
50
+ /** The existing envelope source scan; its bounds and selected paths stay unchanged. */
51
+ export const TranscriptSourceReadPolicy = {
52
+ maxDocumentBytes: 128 << 20, maxDocumentDepth: 64,
53
+ opaqueMetadataPointers: ["/sessionDetail/nativeMetadata/*/data"],
54
+ };
55
+ /** The existing bare-detail source scan; its selected path stays unchanged. */
56
+ export const TranscriptSourceDetailReadPolicy = {
57
+ maxDocumentBytes: 128 << 20, maxDocumentDepth: 64,
58
+ opaqueMetadataPointers: ["/nativeMetadata/*/data"],
59
+ };
60
+ /** Download scan with no additional outer byte limit and both root shapes. */
61
+ export const TranscriptDownloadPolicy = {
62
+ maxDocumentDepth: 64,
63
+ opaqueMetadataPointers: [
64
+ "/sessionDetail/nativeMetadata/*/data",
65
+ "/sessionDetail/earlierHistory/*/nativeMetadata/*/data",
66
+ "/nativeMetadata/*/data",
67
+ "/earlierHistory/*/nativeMetadata/*/data",
68
+ ],
69
+ };
48
70
  export function scanRawJsonText(text, policy = {}) {
49
71
  scanRawJson(text, policy);
50
72
  }
@@ -111,7 +133,10 @@ function normalizeEmptyOptionalPublicRefs(value) {
111
133
  visitTurns(section.turns);
112
134
  }
113
135
  export function parseSessionDetailPayloadText(text) {
114
- scanRawJsonText(text, { maxDocumentBytes: 128 << 20, maxDocumentDepth: 64, opaqueMetadataPointers: ["/nativeMetadata/*/data"] });
136
+ return parseSessionDetailPayloadTextWithPolicy(text, TranscriptSourceDetailReadPolicy);
137
+ }
138
+ export function parseSessionDetailPayloadTextWithPolicy(text, policy) {
139
+ scanRawJsonText(text, policy);
115
140
  return parseSessionDetailPayloadValue(JSON.parse(text));
116
141
  }
117
142
  export function parseSchemaVersionAdvertisement(text) {
@@ -127,8 +152,41 @@ export function parseSchemaVersionAdvertisement(text) {
127
152
  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.");
128
153
  return [...value.contentCapabilities];
129
154
  }
155
+ /**
156
+ * Parse the segmented read window independently of content capabilities.
157
+ * Both members absent or empty mean an older, 0.1.0-only host. An incomplete
158
+ * or malformed pair is refused rather than authorizing a newer generation.
159
+ */
160
+ export function parseSegmentedReadVersionAdvertisement(text) {
161
+ scanRawJsonText(text, { maxDocumentBytes: 1 << 20, maxDocumentDepth: 16 });
162
+ const value = JSON.parse(text);
163
+ const where = "Segmented read version validation failed at @peasant-labs/schema parseSegmentedReadVersionAdvertisement during discovery decoding: ";
164
+ if (!isRecord(value))
165
+ throw new TypeError(where + "the response is not an object; the served window cannot be established and the reader cannot choose a generation safely; stay on 0.1.0 and ask the host to emit an object.");
166
+ const current = value.segmentedReadVersion;
167
+ const min = value.minSegmentedReadVersion;
168
+ if (current !== undefined && typeof current !== "string")
169
+ throw new TypeError(where + "segmentedReadVersion is not a string; both members must be emitted together and the served window cannot be established; the reader cannot choose a generation safely, so stay on 0.1.0 and ask the host to emit both strings.");
170
+ if (min !== undefined && typeof min !== "string")
171
+ throw new TypeError(where + "minSegmentedReadVersion is not a string; both members must be emitted together and the served window cannot be established; the reader cannot choose a generation safely, so stay on 0.1.0 and ask the host to emit both strings.");
172
+ const hasCurrent = current !== undefined && current !== "";
173
+ const hasMin = min !== undefined && min !== "";
174
+ if (!hasCurrent && !hasMin)
175
+ return null;
176
+ if (!hasCurrent || !hasMin) {
177
+ const missing = hasCurrent ? "minSegmentedReadVersion" : "segmentedReadVersion";
178
+ throw new TypeError(where + missing + " is absent; the pair must be emitted together and the served window cannot be established; the reader cannot choose a generation safely, so stay on 0.1.0 and ask the host to emit both members.");
179
+ }
180
+ return { current, min };
181
+ }
130
182
  export function parseTranscriptContentText(text) {
131
- scanRawJsonText(text, { maxDocumentBytes: 128 << 20, maxDocumentDepth: 64, opaqueMetadataPointers: ["/sessionDetail/nativeMetadata/*/data"] });
183
+ return parseTranscriptContentTextWithPolicy(text, TranscriptSourceReadPolicy);
184
+ }
185
+ export function parseTranscriptContentTextWithPolicy(text, policy) {
186
+ scanRawJsonText(text, policy);
187
+ return decodeTranscriptContentValue(text);
188
+ }
189
+ function decodeTranscriptContentValue(text) {
132
190
  const raw = JSON.parse(text);
133
191
  if (!isRecord(raw))
134
192
  return zTranscriptContent.parse(raw);
@@ -143,6 +201,157 @@ export function parseTranscriptContentText(text) {
143
201
  parsePublishedSessionDetailPayloadValue(content.sessionDetail);
144
202
  return content;
145
203
  }
204
+ /** The in-band strict core of the served content boundary. */
205
+ export function transcriptContentIsStrict(detail) {
206
+ if (!isRecord(detail))
207
+ return false;
208
+ if ([detail.harness, detail.provider, detail.modelHarness].includes("pi"))
209
+ return true;
210
+ if (zHarness.safeParse(detail.harness).success)
211
+ return true;
212
+ const fold = (key) => key.replaceAll("ſ", "s").toLowerCase();
213
+ const isThinking = (key) => ["thinkinglevel", "thinkinglevelraw", "thinkinglevelhistory"].includes(fold(key));
214
+ if (Object.keys(detail).some((key) => ["retainedunknown", "diagnostics", "nativemetadata"].includes(fold(key)) || isThinking(key)))
215
+ return true;
216
+ if (!Array.isArray(detail.turns))
217
+ return false;
218
+ for (const turn of detail.turns) {
219
+ if (!isRecord(turn))
220
+ continue;
221
+ if (Object.keys(turn).some(isThinking) || Object.hasOwn(turn, "usage") || Object.hasOwn(turn, "sourceEntryRef"))
222
+ return true;
223
+ if (!Array.isArray(turn.toolCalls))
224
+ continue;
225
+ for (const tool of turn.toolCalls) {
226
+ if (isRecord(tool) && ["usage", "callEntryRef", "resultEntryRef", "namespace"].some((key) => Object.hasOwn(tool, key)))
227
+ return true;
228
+ }
229
+ }
230
+ return false;
231
+ }
232
+ function downloadFailure(kind, message, cause) {
233
+ throw new TypeError(`${kind}: transcript download failed at @peasant-labs/schema parseTranscriptDownloadText: ${message}; no export was produced; repair the served content and retry.`, { cause });
234
+ }
235
+ function scanDownloadText(text) {
236
+ try {
237
+ scanRawJsonText(text, TranscriptDownloadPolicy);
238
+ }
239
+ catch (error) {
240
+ const message = error instanceof Error ? error.message : String(error);
241
+ const kind = message.includes("duplicate object key") ? "duplicate-key"
242
+ : message.toLowerCase().includes("depth") ? "depth"
243
+ : /unicode|surrogate/i.test(message) ? "unicode"
244
+ : "syntax";
245
+ downloadFailure(kind, "raw content validation failed", error);
246
+ }
247
+ }
248
+ /** Parse one authorized body for export, preserving the served detail value. */
249
+ export function parseTranscriptDownloadText(text) {
250
+ let value;
251
+ try {
252
+ scanDownloadText(text);
253
+ }
254
+ catch (scanError) {
255
+ // Only multiple JSON documents can select JSONL; a syntactically valid
256
+ // single document never falls back after a scanner rejection.
257
+ try {
258
+ JSON.parse(text);
259
+ }
260
+ catch {
261
+ const lines = text.split("\n").filter((line) => line.trim() !== "");
262
+ if (lines.length === 0)
263
+ throw scanError;
264
+ const records = lines.map((line) => {
265
+ scanDownloadText(line);
266
+ const record = JSON.parse(line);
267
+ if (downloadEmbeddedPublicRoot(record, false))
268
+ downloadFailure("embedded-public-root", "a JSONL record embeds a public transcript root");
269
+ return record;
270
+ });
271
+ return { kind: "records", records };
272
+ }
273
+ throw scanError;
274
+ }
275
+ value = JSON.parse(text);
276
+ const envelope = isRecord(value) && (Object.hasOwn(value, "sessionDetail") || Object.hasOwn(value, "contractVersion"));
277
+ const detail = envelope && isRecord(value) ? value.sessionDetail : value;
278
+ if (envelope && !isRecord(detail))
279
+ downloadFailure("shape", "the envelope has no object sessionDetail");
280
+ if (transcriptContentIsStrict(detail)) {
281
+ if (isRecord(detail) && [detail.harness, detail.provider, detail.modelHarness].includes("pi") && detail.harness !== "pi") {
282
+ downloadFailure("shape", "Pi identity conflicts with the session harness");
283
+ }
284
+ try {
285
+ if (envelope)
286
+ parseTranscriptContentTextWithPolicy(text, TranscriptDownloadPolicy);
287
+ else
288
+ parseSessionDetailPayloadTextWithPolicy(text, TranscriptDownloadPolicy);
289
+ }
290
+ catch (error) {
291
+ const message = error instanceof Error ? error.message : String(error);
292
+ const kind = message.includes("retainedUnknown") ? "retained-unknown"
293
+ : message.startsWith("Session detail validation failed") ? "semantic-limit" : "shape";
294
+ downloadFailure(kind, "the typed content gate refused the body", error);
295
+ }
296
+ return { kind: "strict", detail };
297
+ }
298
+ if (downloadEmbeddedPublicRoot(value, isRecord(value)))
299
+ downloadFailure("embedded-public-root", "the legacy body embeds a public transcript root");
300
+ if (envelope && isRecord(value) && value.kind !== "session_detail")
301
+ downloadFailure("shape", "the legacy envelope has an unsupported kind");
302
+ if (isRecord(detail) && Array.isArray(detail.turns)) {
303
+ for (const turn of detail.turns) {
304
+ if (isRecord(turn) && Object.hasOwn(turn, "observedModel")
305
+ && turn.observedModel !== null && turn.observedModel !== ""
306
+ && !zObservedModelID.safeParse(turn.observedModel).success) {
307
+ downloadFailure("shape", "a legacy observedModel is not a valid model identifier");
308
+ }
309
+ }
310
+ }
311
+ return { kind: "legacy", detail };
312
+ }
313
+ function downloadEmbeddedPublicRoot(value, allowRoot) {
314
+ if (isRecord(value)) {
315
+ if (!allowRoot && downloadPublicRootShape(value))
316
+ return true;
317
+ return Object.entries(value).some(([key, child]) => !downloadOpaqueProviderChild(value, key, child) &&
318
+ downloadEmbeddedPublicRoot(child, allowRoot && key === "sessionDetail"));
319
+ }
320
+ return Array.isArray(value) && value.some((child) => downloadEmbeddedPublicRoot(child, false));
321
+ }
322
+ function downloadPublicRootShape(node) {
323
+ const fold = (key) => key.replaceAll("ſ", "s").toLowerCase();
324
+ for (const [key, value] of Object.entries(node)) {
325
+ if (["retainedunknown", "diagnostics"].includes(fold(key)))
326
+ return true;
327
+ if (fold(key) === "sessiondetail") {
328
+ if (key !== "sessionDetail")
329
+ return true;
330
+ if (isRecord(value) && downloadPublicRootShape(value))
331
+ return true;
332
+ }
333
+ if (fold(key) === "kind" && value === "session_detail")
334
+ return true;
335
+ }
336
+ if (Object.hasOwn(node, "turns") && (node.turns === null || Array.isArray(node.turns)))
337
+ return true;
338
+ if (node.harness === "pi" || node.kind === "session_detail")
339
+ return true;
340
+ if (isRecord(node.sessionDetail)) {
341
+ return typeof node.contractVersion === "string" || Object.hasOwn(node.sessionDetail, "nativeMetadata") || downloadPublicRootShape(node.sessionDetail);
342
+ }
343
+ return false;
344
+ }
345
+ function downloadOpaqueProviderChild(node, key, child) {
346
+ const legacyMessage = (v) => typeof v.role === "string" && (Object.hasOwn(v, "content") || Object.hasOwn(v, "parts"));
347
+ if (legacyMessage(node) && ["content", "parts", "toolCalls", "tool_calls"].includes(key))
348
+ return true;
349
+ if (key === "message" && isRecord(child) && legacyMessage(child))
350
+ return true;
351
+ return typeof node.type === "string" &&
352
+ ["tool_use", "tool_result", "toolCall", "function_call", "function_call_output"].includes(node.type) &&
353
+ ["input", "arguments", "result", "output", "content"].includes(key);
354
+ }
146
355
  export function parseServerMessageRaw(text) {
147
356
  // Dispatch from the syntax scan, not a lossy full-document JSON.parse. The
148
357
  // type member may follow data, so a second selected scan precedes decoding.