@aiwg/cli 2026.10.3 → 2026.10.5

package/dist/src/sessions/adapters/openclaw.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { streamBoundedJsonLines, } from '../readers.js';
 export const OPENCLAW_ADAPTER_VERSION = '1.0.0';
 export const OPENCLAW_SOURCE_SCHEMA_VERSION = '1.0.0';
 export const OPENCLAW_NATIVE_SCHEMA_VERSION = '16.0.0';
@@ -80,6 +80,13 @@ export class OpenClawSessionAdapter {
         // Gateway and consistent snapshots require explicit operator selection.
     }
     async inspect(source) {
+        if (SOURCE_CLASSES.has(source.locatorClass)) {
+            const records = this.readLocalSource(source, true);
+            let result = await records.next();
+            while (!result.done)
+                result = await records.next();
+            return result.value;
+        }
         const parsed = await this.readSource(source, true);
         return {
             sourceSchemaVersion: parsed.schemaVersion,
@@ -89,57 +96,7 @@ export class OpenClawSessionAdapter {
     }
     async *stream(source, cursor) {
         if (SOURCE_CLASSES.has(source.locatorClass)) {
-            const input = await streamBoundedJsonLines({
-                selectedPath: source.locator,
-                allowedRoots: source.authorizedScope.allowedRoots,
-            }, {
-                consistency: source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
-                    ? 'complete' : 'provisional',
-                limits: this.limits,
-            });
-            const start = parseCursor(cursor?.value);
-            let outputIndex = 0;
-            let nativeSchema = null;
-            let eventSchema = null;
-            let sawRecord = false;
-            for await (const line of input) {
-                sawRecord = true;
-                const parsed = SnapshotSchema.safeParse(line.value);
-                if (!parsed.success) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw snapshot is malformed');
-                }
-                const snapshot = parsed.data;
-                const currentNative = nativeVersion(snapshot.schemaVersion);
-                const currentEvent = nativeVersion(snapshot.eventVersion);
-                if ((nativeSchema && nativeSchema !== currentNative)
-                    || (eventSchema && eventSchema !== currentEvent)) {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenClaw snapshot schemas');
-                }
-                nativeSchema = currentNative;
-                eventSchema = currentEvent;
-                assertSupportedSchemaMajor(nativeSchema, 16);
-                assertSupportedSchemaMajor(eventSchema, 3);
-                if (source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
-                    && snapshot.snapshotConsistency !== 'sqlite-backup') {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'OpenClaw snapshot lacks sqlite3.backup() consistency evidence');
-                }
-                if (snapshot.incognito) {
-                    throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'OpenClaw incognito session capture is unavailable by provider policy');
-                }
-                if (snapshot.gateway?.mode === 'remote'
-                    && snapshot.gateway.hostId !== snapshot.gateway.expectedHostId) {
-                    throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'OpenClaw remote Gateway identity does not match the authorized host');
-                }
-                for (const record of normalizeSnapshot(snapshot, line, source.locatorClass)) {
-                    if (outputIndex++ >= start)
-                        yield record;
-                }
-            }
-            if (!sawRecord)
-                throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw source is empty');
-            if (input.incompleteTail && source.locatorClass === 'openclaw-consistent-snapshot-jsonl') {
-                throw new SessionContractError('TRUNCATED_SOURCE', 'OpenClaw consistent snapshot is truncated');
-            }
+            yield* this.readLocalSource(source, false, cursor);
             return;
         }
         const parsed = await this.readSource(source, false);
@@ -147,6 +104,79 @@ export class OpenClawSessionAdapter {
         for (const record of parsed.records.slice(start))
             yield record;
     }
+    async *readLocalSource(source, inspection, cursor) {
+        const input = await streamBoundedJsonLines({
+            selectedPath: source.locator,
+            allowedRoots: source.authorizedScope.allowedRoots,
+        }, {
+            consistency: source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
+                ? 'complete' : 'provisional',
+            limits: this.limits,
+        });
+        const start = parseCursor(cursor?.value);
+        let outputIndex = 0;
+        let nativeSchema = null;
+        let eventSchema = null;
+        let sawRecord = false;
+        let complete = true;
+        let incognito = false;
+        let remoteMismatch = false;
+        let projectionIncomplete = false;
+        for await (const line of input) {
+            sawRecord = true;
+            const parsed = SnapshotSchema.safeParse(line.value);
+            if (!parsed.success) {
+                throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw snapshot is malformed', schemaRejectionDetail(parsed.error));
+            }
+            const snapshot = parsed.data;
+            const currentNative = nativeVersion(snapshot.schemaVersion);
+            const currentEvent = nativeVersion(snapshot.eventVersion);
+            if ((nativeSchema && nativeSchema !== currentNative)
+                || (eventSchema && eventSchema !== currentEvent)) {
+                throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenClaw snapshot schemas', { issues: [{ path: nativeSchema && nativeSchema !== currentNative ? 'schemaVersion' : 'eventVersion', code: 'custom' }] });
+            }
+            nativeSchema = currentNative;
+            eventSchema = currentEvent;
+            assertSupportedSchemaMajor(nativeSchema, 16);
+            assertSupportedSchemaMajor(eventSchema, 3);
+            if (source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
+                && snapshot.snapshotConsistency !== 'sqlite-backup') {
+                throw new SessionContractError('SCHEMA_DRIFT', 'OpenClaw snapshot lacks sqlite3.backup() consistency evidence', schemaIssueDetail('snapshotConsistency'));
+            }
+            incognito ||= snapshot.incognito === true;
+            const mismatched = snapshot.gateway?.mode === 'remote'
+                && snapshot.gateway.hostId !== snapshot.gateway.expectedHostId;
+            remoteMismatch ||= mismatched;
+            projectionIncomplete ||= Boolean(snapshot.projection
+                && (snapshot.projection.kind !== 'canonical' || !snapshot.projection.complete));
+            complete &&= snapshot.sessions.every(sessionComplete);
+            if (!inspection && snapshot.incognito) {
+                throw new SessionContractError('OPERATION_NOT_AUTHORIZED', 'OpenClaw incognito session capture is unavailable by provider policy');
+            }
+            if (!inspection && mismatched) {
+                throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'OpenClaw remote Gateway identity does not match the authorized host');
+            }
+            if (snapshot.incognito || mismatched)
+                continue;
+            for (const record of normalizeSnapshot(snapshot, line, source.locatorClass)) {
+                if (outputIndex++ >= start)
+                    yield record;
+            }
+        }
+        if (!sawRecord)
+            throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw source is empty', schemaIssueDetail('<root>'));
+        if (input.incompleteTail && source.locatorClass === 'openclaw-consistent-snapshot-jsonl') {
+            throw new SessionContractError('TRUNCATED_SOURCE', 'OpenClaw consistent snapshot is truncated');
+        }
+        return {
+            sourceSchemaVersion: OPENCLAW_SOURCE_SCHEMA_VERSION,
+            consistency: source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
+                ? 'consistent-snapshot'
+                : complete && !projectionIncomplete ? 'complete' : 'provisional',
+            operationalState: incognito ? 'inaccessible'
+                : remoteMismatch || projectionIncomplete ? 'degraded' : 'available',
+        };
+    }
     async readSource(source, inspection) {
         if (source.locatorClass === 'openclaw-state-db') {
             throw new SessionContractError('UNSUPPORTED_OPERATION', 'raw OpenClaw SQLite access is unsafe; use Gateway acquisition or a verified sqlite3.backup() projection');
@@ -161,42 +191,24 @@ export class OpenClawSessionAdapter {
             }
             input = (await this.gateway.snapshot(source)).map(toRecord);
         }
-        else if (SOURCE_CLASSES.has(source.locatorClass)) {
-            const result = await readBoundedJsonLines({
-                selectedPath: source.locator,
-                allowedRoots: source.authorizedScope.allowedRoots,
-            }, {
-                consistency: source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
-                    ? 'complete' : 'provisional',
-                limits: this.limits,
-            });
-            if (result.incompleteTail && source.locatorClass === 'openclaw-consistent-snapshot-jsonl') {
-                throw new SessionContractError('TRUNCATED_SOURCE', 'OpenClaw consistent snapshot is truncated');
-            }
-            input = result.records;
-        }
         else {
             throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported OpenClaw source class');
         }
         if (input.length === 0)
-            throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw source is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw source is empty', schemaIssueDetail('<root>'));
         const parsed = input.map(({ value, ...line }) => {
             const result = SnapshotSchema.safeParse(value);
             if (!result.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw snapshot is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'OpenClaw snapshot is malformed', schemaRejectionDetail(result.error));
             return { value: result.data, ...line };
         });
         const nativeSchemas = new Set(parsed.map(({ value }) => nativeVersion(value.schemaVersion)));
         const eventSchemas = new Set(parsed.map(({ value }) => nativeVersion(value.eventVersion)));
         if (nativeSchemas.size !== 1 || eventSchemas.size !== 1) {
-            throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenClaw snapshot schemas');
+            throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenClaw snapshot schemas', { issues: [{ path: nativeSchemas.size !== 1 ? 'schemaVersion' : 'eventVersion', code: 'custom' }] });
         }
         assertSupportedSchemaMajor([...nativeSchemas][0], 16);
         assertSupportedSchemaMajor([...eventSchemas][0], 3);
-        if (source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
-            && parsed.some(({ value }) => value.snapshotConsistency !== 'sqlite-backup')) {
-            throw new SessionContractError('SCHEMA_DRIFT', 'OpenClaw snapshot lacks sqlite3.backup() consistency evidence');
-        }
         const incognito = parsed.some(({ value }) => value.incognito);
         const remoteMismatch = parsed.some(({ value }) => value.gateway?.mode === 'remote'
             && value.gateway.hostId !== value.gateway.expectedHostId);
@@ -209,10 +221,8 @@ export class OpenClawSessionAdapter {
         const projectionIncomplete = parsed.some(({ value }) => value.projection && (value.projection.kind !== 'canonical' || !value.projection.complete));
         return {
             schemaVersion: OPENCLAW_SOURCE_SCHEMA_VERSION,
-            consistency: source.locatorClass === 'openclaw-consistent-snapshot-jsonl'
-                ? 'consistent-snapshot'
-                : parsed.every(({ value }) => value.sessions.every(sessionComplete)) && !projectionIncomplete
-                    ? 'complete' : 'provisional',
+            consistency: parsed.every(({ value }) => value.sessions.every(sessionComplete)) && !projectionIncomplete
+                ? 'complete' : 'provisional',
             operationalState: incognito ? 'inaccessible' : remoteMismatch || projectionIncomplete ? 'degraded' : 'available',
             records: incognito || remoteMismatch
                 ? []
@@ -354,7 +364,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid OpenClaw cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid OpenClaw cursor', schemaIssueDetail('cursor'));
     return Number(value);
 }
 function toRecord(value, sequence) {

package/dist/src/sessions/adapters/opencode.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJson, readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { readBoundedJson, streamBoundedJsonLines, } from '../readers.js';
 export const OPENCODE_ADAPTER_VERSION = '1.0.0';
 export const OPENCODE_EXPORT_SCHEMA_VERSION = '1.0.0';
 const SessionInfoSchema = z.object({
@@ -82,6 +82,14 @@ export class OpenCodeSessionAdapter {
         // Exports and loopback API/SSE endpoints require explicit selection.
     }
     async inspect(source) {
+        if (source.locatorClass === 'opencode-sse-jsonl') {
+            const records = this.stream(source);
+            let result = await records.next();
+            while (!result.done)
+                result = await records.next();
+            if (result.value)
+                return result.value;
+        }
         const parsed = await this.readSource(source);
         return {
             sourceSchemaVersion: parsed.schemaVersion,
@@ -105,12 +113,12 @@ export class OpenCodeSessionAdapter {
             for await (const line of input) {
                 const parsed = EventSchema.safeParse(line.value);
                 if (!parsed.success) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE event is malformed');
+                    throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE event is malformed', schemaRejectionDetail(parsed.error));
                 }
                 const event = parsed.data;
                 const currentSchema = event.schemaVersion ?? OPENCODE_EXPORT_SCHEMA_VERSION;
                 if (schemaVersion && schemaVersion !== currentSchema) {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenCode event schemas');
+                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenCode event schemas', schemaIssueDetail('schemaVersion'));
                 }
                 schemaVersion = currentSchema;
                 assertSupportedSchemaMajor(schemaVersion);
@@ -135,7 +143,7 @@ export class OpenCodeSessionAdapter {
                         messages.set(candidate.data.id, candidate.data);
                         const session = sessions.get(candidate.data.sessionID);
                         if (!session) {
-                            throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode message event precedes its session identity');
+                            throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode message event precedes its session identity', schemaIssueDetail('properties.info.sessionID'));
                         }
                         const common = sessionExtensions({
                             info: session, messages: [], sanitized: event.sanitized !== false,
@@ -150,7 +158,7 @@ export class OpenCodeSessionAdapter {
                         const message = messages.get(candidate.data.messageID);
                         const session = sessions.get(candidate.data.sessionID);
                         if (!message || !session) {
-                            throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode part event precedes its message or session identity');
+                            throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode part event precedes its message or session identity', schemaIssueDetail(!message ? 'properties.part.messageID' : 'properties.part.sessionID'));
                         }
                         const common = sessionExtensions({
                             info: session, messages: [], sanitized: event.sanitized !== false,
@@ -161,7 +169,7 @@ export class OpenCodeSessionAdapter {
                     }
                 }
                 if (sessions.size + messages.size > maxJoinStates) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'OpenCode SSE join state exceeds the bounded streaming limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'OpenCode SSE join state exceeds the bounded streaming limit', { limit: 'maxJoinStates', configured: maxJoinStates, observed: sessions.size + messages.size });
                 }
                 for (const record of emitted) {
                     if (outputIndex++ >= start)
@@ -169,14 +177,19 @@ export class OpenCodeSessionAdapter {
                 }
             }
             if (!sawSession) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE stream lacks a session identity');
+                throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE stream lacks a session identity', schemaIssueDetail('properties.info.id'));
             }
-            return;
+            return {
+                sourceSchemaVersion: schemaVersion ?? OPENCODE_EXPORT_SCHEMA_VERSION,
+                consistency: 'provisional',
+                operationalState: 'available',
+            };
         }
         const parsed = await this.readSource(source);
         const start = parseCursor(cursor?.value);
         for (const record of parsed.records.slice(start))
             yield record;
+        return undefined;
     }
     async readSource(source) {
         if (source.locatorClass === 'opencode-sqlite') {
@@ -189,16 +202,6 @@ export class OpenCodeSessionAdapter {
             }, this.limits);
             return normalizeExport(value, source.locatorClass);
         }
-        if (source.locatorClass === 'opencode-sse-jsonl') {
-            const result = await readBoundedJsonLines({
-                selectedPath: source.locator,
-                allowedRoots: source.authorizedScope.allowedRoots,
-            }, { consistency: 'provisional', limits: this.limits });
-            if (result.records.length === 0) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE source is empty');
-            }
-            return normalizeEvents(result.records, source.locatorClass);
-        }
         const kind = source.locatorClass === 'opencode-local-api'
             ? 'api'
             : source.locatorClass === 'opencode-live-sse' ? 'sse' : undefined;
@@ -222,7 +225,7 @@ export class OpenCodeSessionAdapter {
 function normalizeExport(input, locatorClass, provisional = false) {
     const parsed = ExportSchema.safeParse(input);
     if (!parsed.success)
-        throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode export is malformed');
+        throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode export is malformed', schemaRejectionDetail(parsed.error));
     const value = parsed.data;
     const schema = value.schemaVersion ?? OPENCODE_EXPORT_SCHEMA_VERSION;
     assertSupportedSchemaMajor(schema);
@@ -251,12 +254,12 @@ function normalizeEvents(input, locatorClass) {
     const parsed = input.map(({ value, ...line }) => {
         const result = EventSchema.safeParse(value);
         if (!result.success)
-            throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE event is malformed', schemaRejectionDetail(result.error));
         return { value: result.data, ...line };
     });
     const versions = new Set(parsed.map((item) => item.value.schemaVersion ?? OPENCODE_EXPORT_SCHEMA_VERSION));
     if (versions.size !== 1)
-        throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenCode event schemas');
+        throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenCode event schemas', schemaIssueDetail('schemaVersion'));
     assertSupportedSchemaMajor([...versions][0]);
     const sessions = new Map();
     const messages = new Map();
@@ -280,7 +283,7 @@ function normalizeEvents(input, locatorClass) {
         }
     }
     if (sessions.size === 0) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE stream lacks a session identity');
+        throw new SessionContractError('MALFORMED_SOURCE', 'OpenCode SSE stream lacks a session identity', schemaIssueDetail('properties.info.id'));
     }
     const records = [];
     for (const session of sessions.values()) {
@@ -444,7 +447,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid OpenCode cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid OpenCode cursor', schemaIssueDetail('cursor'));
     return Number(value);
 }
 const SESSION_INFO_KEYS = new Set([

package/dist/src/sessions/adapters/openhuman.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { streamBoundedJsonLines, } from '../readers.js';
 export const OPENHUMAN_ADAPTER_VERSION = '1.0.0';
 export const OPENHUMAN_SOURCE_SCHEMA_VERSION = '1.0.0';
 const MetadataSchema = z.object({
@@ -76,12 +76,11 @@ export class OpenHumanSessionAdapter {
         // session_raw and enrichment bundles require explicit selection.
     }
     async inspect(source) {
-        const parsed = await this.readSource(source);
-        return {
-            sourceSchemaVersion: parsed.schemaVersion,
-            consistency: parsed.consistency,
-            operationalState: 'available',
-        };
+        const records = this.stream(source);
+        let result = await records.next();
+        while (!result.done)
+            result = await records.next();
+        return result.value;
     }
     async *stream(source, cursor) {
         if (source.locatorClass !== 'openhuman-session-raw-jsonl'
@@ -95,6 +94,7 @@ export class OpenHumanSessionAdapter {
         }, { consistency: 'provisional', limits: this.limits });
         const threads = new Map();
         const turns = new Map();
+        const sessions = new Map();
         const maxJoinStates = Math.min(this.limits?.maxRecords ?? 1_000_000, 10_000);
         let schemaVersion = null;
         let outputIndex = 0;
@@ -102,12 +102,12 @@ export class OpenHumanSessionAdapter {
         for await (const line of input) {
             const parsed = RecordSchema.safeParse(line.value);
             if (!parsed.success) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman transcript record is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman transcript record is malformed', schemaRejectionDetail(parsed.error));
             }
             const value = parsed.data;
             const currentVersion = version(value.schemaVersion);
             if (schemaVersion && schemaVersion !== currentVersion) {
-                throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenHuman schema versions');
+                throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenHuman schema versions', schemaIssueDetail('schemaVersion'));
             }
             schemaVersion = currentVersion;
             assertSupportedSchemaMajor(schemaVersion);
@@ -119,64 +119,22 @@ export class OpenHumanSessionAdapter {
             }
             else {
                 sawRaw = true;
+                sessions.set(value.session_id, value.active === false || value.type === 'session_end');
                 const record = normalize(value, line, source.locatorClass, threads.get(value.thread_id), value.request_id ? turns.get(`${value.thread_id}\0${value.request_id}`) : undefined);
                 if (outputIndex++ >= start)
                     yield record;
             }
-            if (threads.size + turns.size > maxJoinStates) {
-                throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'OpenHuman enrichment join state exceeds the bounded streaming limit');
+            if (threads.size + turns.size + sessions.size > maxJoinStates) {
+                throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'OpenHuman enrichment join state exceeds the bounded streaming limit', { limit: 'maxJoinStates', configured: maxJoinStates, observed: threads.size + turns.size + sessions.size });
             }
         }
         if (!sawRaw) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman source contains no session_raw records');
-        }
-    }
-    async readSource(source) {
-        if (source.locatorClass !== 'openhuman-session-raw-jsonl'
-            && source.locatorClass !== 'openhuman-enriched-jsonl') {
-            throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported OpenHuman source class');
-        }
-        const result = await readBoundedJsonLines({
-            selectedPath: source.locator,
-            allowedRoots: source.authorizedScope.allowedRoots,
-        }, { consistency: 'provisional', limits: this.limits });
-        if (result.records.length === 0) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman transcript source is empty');
-        }
-        const parsed = result.records.map(({ value, ...line }) => {
-            const record = RecordSchema.safeParse(value);
-            if (!record.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman transcript record is malformed');
-            return { value: record.data, ...line };
-        });
-        const versions = new Set(parsed.map(({ value }) => version(value.schemaVersion)));
-        if (versions.size !== 1)
-            throw new SessionContractError('SCHEMA_DRIFT', 'mixed OpenHuman schema versions');
-        assertSupportedSchemaMajor([...versions][0]);
-        const raw = parsed.filter((item) => item.value.recordType === 'session_raw');
-        if (raw.length === 0) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman source contains no session_raw records');
-        }
-        const threads = new Map();
-        const turns = new Map();
-        for (const item of parsed) {
-            if (item.value.recordType === 'thread_state')
-                threads.set(item.value.thread_id, item.value);
-            if (item.value.recordType === 'turn_state') {
-                turns.set(`${item.value.thread_id}\0${item.value.request_id}`, item.value);
-            }
-        }
-        const sessions = new Map();
-        for (const item of raw) {
-            const values = sessions.get(item.value.session_id) ?? [];
-            values.push(item.value);
-            sessions.set(item.value.session_id, values);
+            throw new SessionContractError('MALFORMED_SOURCE', 'OpenHuman source contains no session_raw records', schemaIssueDetail('<root>'));
         }
         return {
-            schemaVersion: OPENHUMAN_SOURCE_SCHEMA_VERSION,
-            consistency: result.incompleteTail || [...sessions.values()].some((events) => events.at(-1)?.active !== false && events.at(-1)?.type !== 'session_end')
-                ? 'provisional' : 'complete',
-            records: raw.map(({ value, ...line }) => normalize(value, line, source.locatorClass, threads.get(value.thread_id), value.request_id ? turns.get(`${value.thread_id}\0${value.request_id}`) : undefined)),
+            sourceSchemaVersion: OPENHUMAN_SOURCE_SCHEMA_VERSION,
+            consistency: !input.incompleteTail && [...sessions.values()].every(Boolean) ? 'complete' : 'provisional',
+            operationalState: 'available',
         };
     }
 }
@@ -296,7 +254,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid OpenHuman cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid OpenHuman cursor', schemaIssueDetail('cursor'));
     return Number(value);
 }
 const RAW_KEYS = new Set([

package/dist/src/sessions/adapters/pi.js

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
-import { basename, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, } from '../contracts.js';
-import { readBoundedJsonLines, streamBoundedJsonLines } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, } from '../contracts.js';
+import { streamBoundedJsonLines } from '../readers.js';
 export const PI_ADAPTER_VERSION = '1.0.0';
 export const PI_SOURCE_SCHEMA_VERSION = '3.0.0';
 const Header = z.object({ type: z.literal('session'), version: z.number().int(), id: z.string().min(1),
@@ -29,7 +29,7 @@ export class PiSessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of jsonlFiles(resolve(root))) {
                 if (++count > this.maxFiles)
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Pi discovery file limit exceeded');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Pi discovery file limit exceeded', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
                 yield { provider: 'pi', locator, locatorClass: 'pi-session-v3-jsonl' };
             }
         }
@@ -37,13 +37,16 @@ export class PiSessionAdapter {
     async inspect(source) {
         let input;
         try {
-            input = await readBoundedJsonLines({ selectedPath: source.locator,
+            input = await streamBoundedJsonLines({ selectedPath: source.locator,
                 allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
         }
         catch (error) {
             throw normalizeAuthorizationError(error);
         }
-        const header = parseHeader(input.records[0]?.value);
+        let header;
+        for await (const line of input)
+            header ??= parseHeader(line.value);
+        header ??= parseHeader(undefined);
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'Pi session has a truncated JSONL tail');
         return { sourceSchemaVersion: `${header.version}.0.0`, consistency: 'complete', operationalState: 'available' };
@@ -52,28 +55,38 @@ export class PiSessionAdapter {
         let input;
         try {
             input = await streamBoundedJsonLines({ selectedPath: source.locator,
-                allowedRoots: source.authorizedScope.allowedRoots }, { cursor: cursor?.value, consistency: 'provisional', limits: this.limits });
+                allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
         }
         catch (error) {
             throw normalizeAuthorizationError(error);
         }
         let sessionId = '';
-        let index = 0;
+        const value = cursor?.value || '0';
+        const byteCursor = value.startsWith('byte:');
+        const position = value.replace(/^byte:/, '');
+        if (!/^\d+$/.test(position))
+            throw new SessionContractError('SCHEMA_DRIFT', 'invalid Pi cursor', schemaIssueDetail('cursor'));
+        const start = Number(position);
+        let end = 0;
         const ids = new Set();
         for await (const line of input) {
-            if (index++ === 0 && !cursor) {
+            end = line.byteOffset + line.byteLength;
+            if (byteCursor && start > line.byteOffset && start < end) {
+                throw new SessionContractError('SCHEMA_DRIFT', 'Pi cursor is not a record boundary', schemaIssueDetail('cursor'));
+            }
+            if (line.sequence === 0) {
                 sessionId = parseHeader(line.value).id;
                 continue;
             }
-            if (!sessionId)
-                sessionId = basename(source.locator, '.jsonl');
             const parsed = Entry.safeParse(line.value);
             if (!parsed.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'Pi session entry is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'Pi session entry is malformed', schemaRejectionDetail(parsed.error));
             const entry = parsed.data;
             if (ids.has(entry.id))
                 throw new SessionContractError('DUPLICATE_NATIVE_ID', 'Pi session contains a duplicate entry id');
             ids.add(entry.id);
+            if (byteCursor ? end <= start : line.sequence <= start)
+                continue;
             const message = object(entry.message);
             const role = string(message.role) ?? roleFor(entry.type);
             const sensitive = role === 'toolResult' || entry.type === 'custom';
@@ -81,7 +94,7 @@ export class PiSessionAdapter {
             yield { nativeSessionId: sessionId, nativeEventId: entry.id, sequence: line.sequence,
                 kind: kindFor(entry.type, role), role, toolName: sensitive ? string(message.toolName) : undefined,
                 toolCallId: sensitive ? string(message.toolCallId) : undefined,
-                occurredAt: entry.timestamp, text, sourceCursor: String(line.byteOffset + line.byteLength),
+                occurredAt: entry.timestamp, text, sourceCursor: `byte:${end}`,
                 sourceBytes: line.byteLength, rawReference: { locatorClass: 'pi-session-v3-jsonl', offset: line.byteOffset },
                 activityBoundary: entry.type === 'compaction' ? 'continuation' : undefined,
                 activityBoundaryBasis: entry.type === 'compaction' ? 'pi-session:compaction' : undefined,
@@ -90,6 +103,8 @@ export class PiSessionAdapter {
                     opaque: !KNOWN.has(entry.type), redacted: sensitive,
                     nativeType: entry.type, parentId: entry.parentId } };
         }
+        if (byteCursor && start > end)
+            throw new SessionContractError('SCHEMA_DRIFT', 'Pi cursor exceeds source size', schemaIssueDetail('cursor'));
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'Pi session has a truncated JSONL tail');
     }
@@ -99,7 +114,7 @@ const KNOWN = new Set(['message', 'thinking_level_change', 'model_change', 'comp
 function parseHeader(value) {
     const parsed = Header.safeParse(value);
     if (!parsed.success)
-        throw new SessionContractError('MALFORMED_SOURCE', 'Pi session header is malformed');
+        throw new SessionContractError('MALFORMED_SOURCE', 'Pi session header is malformed', schemaRejectionDetail(parsed.error));
     if (parsed.data.version !== 3)
         throw new SessionContractError('UNKNOWN_SCHEMA_MAJOR', `unsupported Pi session version: ${parsed.data.version}`);
     return parsed.data;

package/dist/src/sessions/adapters/warp.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { basename } from 'node:path';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { SessionContractError, schemaIssueDetail, assertSupportedSchemaMajor, } from '../contracts.js';
 import { readBoundedText } from '../readers.js';
 export const WARP_ADAPTER_VERSION = '1.0.0';
 export const WARP_MARKDOWN_SCHEMA_VERSION = '1.0.0';
@@ -48,7 +48,7 @@ export class WarpSessionAdapter {
         assertSupportedSchemaMajor(schemaVersion);
         const blocks = parseBlocks(value);
         if (blocks.length === 0) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Warp Markdown export contains no recognized user or assistant conversation blocks');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Warp Markdown export contains no recognized user or assistant conversation blocks', schemaIssueDetail('headings'));
         }
         const stableSessionId = `manual:${createHash('sha256').update(value).digest('hex').slice(0, 32)}`;
         const lifecycleEvidence = /<!--\s*warp-lifecycle:\s*complete\s*-->/i.test(value)
@@ -154,7 +154,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Warp cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Warp cursor', schemaIssueDetail('cursor'));
     return Number(value);
 }
 //# sourceMappingURL=warp.js.map