@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
 import { basename, dirname, extname, resolve, } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
-import { readBoundedJsonLines, readBoundedText, streamBoundedJsonLines, } from '../readers.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { readBoundedText, streamBoundedJsonLines, } from '../readers.js';
 export const CURSOR_ADAPTER_VERSION = '1.0.0';
 export const CURSOR_SOURCE_SCHEMA_VERSION = '1.0.0';
 const CliEventSchema = z.object({
@@ -82,7 +82,7 @@ export class CursorSessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of discoverJsonl(resolve(root), this.discoveryLimits.maxDepth)) {
                 if (++emitted > this.discoveryLimits.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Cursor source discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Cursor source discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.discoveryLimits.maxFiles, observed: emitted });
                 }
                 yield {
                     provider: 'cursor',
@@ -93,6 +93,16 @@ export class CursorSessionAdapter {
         }
     }
     async inspect(source) {
+        if (source.locatorClass === 'cursor-cli-stream-json'
+            || source.locatorClass === 'cursor-cloud-events-jsonl'
+            || source.locatorClass === 'cursor-agent-transcript-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,
@@ -102,7 +112,8 @@ export class CursorSessionAdapter {
     }
     async *stream(source, cursor) {
         if (source.locatorClass === 'cursor-cli-stream-json'
-            || source.locatorClass === 'cursor-cloud-events-jsonl') {
+            || source.locatorClass === 'cursor-cloud-events-jsonl'
+            || source.locatorClass === 'cursor-agent-transcript-jsonl') {
             const input = await streamBoundedJsonLines({
                 selectedPath: source.locator,
                 allowedRoots: source.authorizedScope.allowedRoots,
@@ -114,13 +125,14 @@ export class CursorSessionAdapter {
             let agentId;
             let runId;
             let sawRecord = false;
+            let complete = false;
             for await (const line of input) {
                 sawRecord = true;
                 const raw = asObject(line.value);
                 const currentSchema = typeof raw.schemaVersion === 'string'
                     ? raw.schemaVersion : CURSOR_SOURCE_SCHEMA_VERSION;
                 if (schemaVersion && schemaVersion !== currentSchema) {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'Cursor source declares mixed schema versions');
+                    throw new SessionContractError('SCHEMA_DRIFT', 'Cursor source declares mixed schema versions', schemaIssueDetail('schemaVersion'));
                 }
                 schemaVersion = currentSchema;
                 assertSupportedSchemaMajor(schemaVersion);
@@ -128,7 +140,7 @@ export class CursorSessionAdapter {
                 if (source.locatorClass === 'cursor-cli-stream-json') {
                     const parsed = CliEventSchema.safeParse(line.value);
                     if (!parsed.success) {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed');
+                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed', schemaRejectionDetail(parsed.error));
                     }
                     const event = parsed.data;
                     if (cliSessionId && cliSessionId !== event.session_id) {
@@ -137,10 +149,10 @@ export class CursorSessionAdapter {
                     cliSessionId = event.session_id;
                     record = normalizeCli([line]).records[0];
                 }
-                else {
+                else if (source.locatorClass === 'cursor-cloud-events-jsonl') {
                     const parsed = CloudEventSchema.safeParse(line.value);
                     if (!parsed.success) {
-                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed');
+                        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed', schemaRejectionDetail(parsed.error));
                     }
                     const event = parsed.data;
                     const nextAgentId = event.agent?.id ?? agentId;
@@ -153,27 +165,38 @@ export class CursorSessionAdapter {
                     }
                     agentId = nextAgentId;
                     runId = nextRunId;
-                    record = normalizeCloud([{
+                    const normalized = normalizeCloud([{
                             ...line,
                             value: {
                                 ...event,
                                 agent: event.agent ?? (agentId ? { id: agentId } : undefined),
                                 run: event.run ?? (runId ? { id: runId } : undefined),
                             },
-                        }]).records[0];
+                        }]);
+                    complete ||= normalized.complete;
+                    record = normalized.records[0];
+                }
+                else {
+                    record = normalizeAgentTranscript([line], source.locator).records[0];
                 }
+                complete ||= record.extensions?.lifecycle === 'complete';
                 if (outputIndex++ >= start)
                     yield record;
             }
             if (!sawRecord && !input.incompleteTail) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'Cursor structured source is empty');
+                throw new SessionContractError('MALFORMED_SOURCE', 'Cursor structured source is empty', schemaIssueDetail('<root>'));
             }
-            return;
+            return {
+                sourceSchemaVersion: schemaVersion ?? CURSOR_SOURCE_SCHEMA_VERSION,
+                consistency: complete && !input.incompleteTail ? 'complete' : '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) {
         const authorization = {
@@ -191,36 +214,6 @@ export class CursorSessionAdapter {
                 records: normalizeMarkdown(input.value, source.locator),
             };
         }
-        const input = await readBoundedJsonLines(authorization, { consistency: 'provisional', limits: this.limits });
-        if (input.records.length === 0 && !input.incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor structured source is empty');
-        }
-        const schemaVersion = declaredVersion(input.records);
-        assertSupportedSchemaMajor(schemaVersion);
-        if (source.locatorClass === 'cursor-cli-stream-json') {
-            const normalized = normalizeCli(input.records);
-            return {
-                schemaVersion,
-                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
-                records: normalized.records,
-            };
-        }
-        if (source.locatorClass === 'cursor-cloud-events-jsonl') {
-            const normalized = normalizeCloud(input.records);
-            return {
-                schemaVersion,
-                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
-                records: normalized.records,
-            };
-        }
-        if (source.locatorClass === 'cursor-agent-transcript-jsonl') {
-            const normalized = normalizeAgentTranscript(input.records, source.locator);
-            return {
-                schemaVersion,
-                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
-                records: normalized.records,
-            };
-        }
         throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported Cursor source class');
     }
 }
@@ -257,7 +250,7 @@ function normalizeCli(input) {
     for (const line of input) {
         const parsed = CliEventSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor CLI event is malformed', schemaRejectionDetail(parsed.error));
         }
         const event = parsed.data;
         if (sessionId && sessionId !== event.session_id) {
@@ -307,7 +300,7 @@ function normalizeCloud(input) {
     for (const line of input) {
         const parsed = CloudEventSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Cloud Agent event is malformed', schemaRejectionDetail(parsed.error));
         }
         const event = parsed.data;
         const nextAgentId = event.agent?.id ?? agentId;
@@ -371,7 +364,7 @@ function normalizeAgentTranscript(input, locator) {
     for (const line of input) {
         const parsed = AgentTranscriptEventSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor agent transcript event is malformed');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor agent transcript event is malformed', schemaRejectionDetail(parsed.error));
         }
         const event = parsed.data;
         const terminal = event.type === 'turn_ended' && event.status === 'success';
@@ -411,7 +404,7 @@ function normalizeMarkdown(value, locator) {
     const heading = /^#{1,3}\s+(User|Assistant|Cursor)\s*$/gim;
     const matches = [...value.matchAll(heading)];
     if (matches.length === 0) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Markdown export has no role headings');
+        throw new SessionContractError('MALFORMED_SOURCE', 'Cursor Markdown export has no role headings', schemaIssueDetail('headings'));
     }
     const nativeSessionId = basename(locator, extname(locator));
     return matches.map((match, index) => {
@@ -462,16 +455,6 @@ function messageText(value) {
         return '';
     }).filter(Boolean).join('\n');
 }
-function declaredVersion(records) {
-    const versions = new Set(records.map((line) => {
-        const value = asObject(line.value);
-        return typeof value.schemaVersion === 'string' ? value.schemaVersion : CURSOR_SOURCE_SCHEMA_VERSION;
-    }));
-    if (versions.size !== 1) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'Cursor source declares mixed schema versions');
-    }
-    return [...versions][0];
-}
 function declaredEventVersion(event) {
     return event.schemaVersion ?? CURSOR_SOURCE_SCHEMA_VERSION;
 }
@@ -511,7 +494,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value)) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Cursor record cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Cursor record cursor', schemaIssueDetail('cursor'));
     }
     return Number(value);
 }

package/dist/src/sessions/adapters/deepseek-harness.js

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
 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 DEEPSEEK_HARNESS_ADAPTER_VERSION = '1.0.0';
 export const DEEPSEEK_HARNESS_SOURCE_SCHEMA_VERSION = '2.0.0';
 const Header = z.object({
@@ -39,7 +39,7 @@ export class DeepSeekHarnessSessionAdapter {
         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', 'DeepSeek Harness discovery file limit exceeded');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'DeepSeek Harness discovery file limit exceeded', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
                 yield { provider: this.provider, locator, locatorClass: 'deepseek-harness-session-v2-jsonl' };
             }
         }
@@ -47,12 +47,15 @@ export class DeepSeekHarnessSessionAdapter {
     async inspect(source) {
         let input;
         try {
-            input = await readBoundedJsonLines({ selectedPath: source.locator, allowedRoots: source.authorizedScope.allowedRoots }, { consistency: 'provisional', limits: this.limits });
+            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', 'DeepSeek Harness session has a truncated JSONL tail');
         return { sourceSchemaVersion: `${header.version}.0.0`, consistency: 'complete', operationalState: 'available' };
@@ -67,24 +70,24 @@ export class DeepSeekHarnessSessionAdapter {
         }
         const start = cursor?.value.replace(/^byte:/, '') ?? '0';
         if (!/^\d+$/.test(start))
-            throw new SessionContractError('SCHEMA_DRIFT', 'invalid DeepSeek Harness cursor');
+            throw new SessionContractError('SCHEMA_DRIFT', 'invalid DeepSeek Harness cursor', schemaIssueDetail('cursor'));
         let header;
         let expectedSeq = 0;
         let end = 0;
         for await (const line of input) {
             end = line.byteOffset + line.byteLength;
             if (Number(start) > line.byteOffset && Number(start) < end)
-                throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor is not a record boundary');
+                throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor is not a record boundary', schemaIssueDetail('cursor'));
             if (!header) {
                 header = parseHeader(line.value);
                 continue;
             }
             const parsed = Event.safeParse(line.value);
             if (!parsed.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session event is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session event is malformed', schemaRejectionDetail(parsed.error));
             const event = parsed.data;
             if (event.seq !== expectedSeq)
-                throw new SessionContractError(event.seq < expectedSeq ? 'DUPLICATE_NATIVE_ID' : 'SCHEMA_DRIFT', `DeepSeek Harness sequence expected ${expectedSeq}, received ${event.seq}`);
+                throw new SessionContractError(event.seq < expectedSeq ? 'DUPLICATE_NATIVE_ID' : 'SCHEMA_DRIFT', `DeepSeek Harness sequence expected ${expectedSeq}, received ${event.seq}`, schemaIssueDetail('seq'));
             expectedSeq++;
             if (end <= Number(start))
                 continue;
@@ -121,9 +124,9 @@ export class DeepSeekHarnessSessionAdapter {
             };
         }
         if (!header)
-            throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is missing');
+            throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is missing', schemaIssueDetail('header'));
         if (Number(start) > end)
-            throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor exceeds source size');
+            throw new SessionContractError('SCHEMA_DRIFT', 'DeepSeek Harness cursor exceeds source size', schemaIssueDetail('cursor'));
         if (input.incompleteTail)
             throw new SessionContractError('TRUNCATED_SOURCE', 'DeepSeek Harness session has a truncated JSONL tail');
     }
@@ -131,7 +134,7 @@ export class DeepSeekHarnessSessionAdapter {
 function parseHeader(value) {
     const parsed = Header.safeParse(value);
     if (!parsed.success)
-        throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is malformed');
+        throw new SessionContractError('MALFORMED_SOURCE', 'DeepSeek Harness session header is malformed', schemaRejectionDetail(parsed.error));
     if (parsed.data.version !== 2)
         throw new SessionContractError('UNKNOWN_SCHEMA_MAJOR', `unsupported DeepSeek Harness session version: ${parsed.data.version}`);
     return parsed.data;

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

@@ -1,8 +1,8 @@
 import { opendir } from 'node:fs/promises';
 import { basename, extname, resolve } from 'node:path';
 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 FACTORY_ADAPTER_VERSION = '1.0.0';
 export const FACTORY_SOURCE_SCHEMA_VERSION = '1.0.0';
 const FactoryRecordSchema = z.object({
@@ -51,13 +51,21 @@ export class FactorySessionAdapter {
         for (const root of [...scope.allowedRoots].sort()) {
             for await (const locator of discoverJsonl(resolve(root), this.discoveryLimits.maxDepth)) {
                 if (++emitted > this.discoveryLimits.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Factory source discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Factory source discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.discoveryLimits.maxFiles, observed: emitted });
                 }
                 yield { provider: 'factory', locator, locatorClass: 'factory-droid-jsonl' };
             }
         }
     }
     async inspect(source) {
+        if (source.locatorClass === 'factory-droid-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,
@@ -76,6 +84,7 @@ export class FactorySessionAdapter {
             let establishedId;
             let schemaVersion = null;
             let sawRecord = false;
+            let complete = false;
             for await (const line of input) {
                 sawRecord = true;
                 const parsed = FactoryRecordSchema.safeParse(line.value);
@@ -85,7 +94,7 @@ export class FactorySessionAdapter {
                 const value = parsed.data;
                 const currentSchema = value.schemaVersion ?? FACTORY_SOURCE_SCHEMA_VERSION;
                 if (schemaVersion && schemaVersion !== currentSchema) {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed Factory source schemas');
+                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed Factory source schemas', schemaIssueDetail('schemaVersion'));
                 }
                 schemaVersion = currentSchema;
                 assertSupportedSchemaMajor(schemaVersion);
@@ -95,44 +104,39 @@ export class FactorySessionAdapter {
                     throw new SessionContractError('DUPLICATE_NATIVE_ID', 'Factory source changes session identity');
                 }
                 establishedId = currentId;
-                for (const record of normalize([line], source, establishedId).records) {
+                const normalized = normalize([line], source, establishedId);
+                complete ||= normalized.complete;
+                for (const record of normalized.records) {
                     if (outputIndex++ >= start)
                         yield record;
                 }
             }
             if (!sawRecord && !input.incompleteTail) {
-                throw new SessionContractError('MALFORMED_SOURCE', 'Factory session source is empty');
+                throw new SessionContractError('MALFORMED_SOURCE', 'Factory session source is empty', schemaIssueDetail('<root>'));
             }
-            return;
+            return {
+                sourceSchemaVersion: schemaVersion ?? FACTORY_SOURCE_SCHEMA_VERSION,
+                consistency: complete && !input.incompleteTail ? 'complete' : '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) {
-        let input;
-        let incompleteTail = false;
-        if (source.locatorClass === 'factory-droid-jsonl') {
-            const result = await readBoundedJsonLines({
-                selectedPath: source.locator,
-                allowedRoots: source.authorizedScope.allowedRoots,
-            }, { consistency: 'provisional', limits: this.limits });
-            input = result.records;
-            incompleteTail = result.incompleteTail;
-        }
-        else {
-            input = await this.remoteRecords(source);
-        }
-        if (input.length === 0 && !incompleteTail) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Factory session source is empty');
+        const input = await this.remoteRecords(source);
+        if (input.length === 0) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Factory session source is empty', schemaIssueDetail('<root>'));
         }
         const schemaVersion = declaredVersion(input);
         assertSupportedSchemaMajor(schemaVersion);
         const normalized = normalize(input, source);
         return {
             schemaVersion,
-            consistency: normalized.complete && !incompleteTail ? 'complete' : 'provisional',
+            consistency: normalized.complete ? 'complete' : 'provisional',
             records: normalized.records,
         };
     }
@@ -155,7 +159,7 @@ export class FactorySessionAdapter {
         }
         const values = await transport.snapshot(source);
         if (values.length > (this.limits?.maxRecords ?? 1_000_000)) {
-            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Factory remote record limit exceeded');
+            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Factory remote record limit exceeded', { limit: 'maxRecords', configured: this.limits?.maxRecords ?? 1_000_000, observed: values.length });
         }
         return values.map((value, sequence) => ({
             value, sequence, byteOffset: sequence, byteLength: Buffer.byteLength(JSON.stringify(value)),
@@ -330,7 +334,7 @@ function factoryMalformedRecord(source, record, error) {
         ? issue.path.map(String).join('.')
         : 'record';
     return new SessionContractError('MALFORMED_SOURCE', `Factory source ${basename(source.locator)} record ${record.sequence + 1} `
-        + `type ${type} failed requirement ${requirement} (${issue?.code ?? 'invalid_type'})`);
+        + `type ${type} failed requirement ${requirement} (${issue?.code ?? 'invalid_type'})`, schemaRejectionDetail(error));
 }
 function declaredVersion(records) {
     const versions = new Set(records.flatMap((record) => {
@@ -338,7 +342,7 @@ function declaredVersion(records) {
         return typeof value.schemaVersion === 'string' ? [value.schemaVersion] : [];
     }));
     if (versions.size > 1)
-        throw new SessionContractError('SCHEMA_DRIFT', 'mixed Factory schema versions');
+        throw new SessionContractError('SCHEMA_DRIFT', 'mixed Factory schema versions', schemaIssueDetail('schemaVersion'));
     return [...versions][0] ?? FACTORY_SOURCE_SCHEMA_VERSION;
 }
 function timestamp(value) {
@@ -375,7 +379,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Factory cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Factory cursor', schemaIssueDetail('cursor'));
     return Number(value);
 }
 const RECORD_KEYS = new Set([

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
 import { streamBoundedJsonLines } from '../readers.js';
 export const GENERIC_INTERCHANGE_KIND = 'aiwg.session-interchange';
 export const GENERIC_ADAPTER_VERSION = '1.0.0';
@@ -80,7 +80,7 @@ export class GenericSessionInterchangeAdapter {
             sessionSequences.add(sequenceKey);
         }
         if (!header)
-            throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty', schemaIssueDetail('<root>'));
         if (input.incompleteTail) {
             throw new SessionContractError('TRUNCATED_SOURCE', 'generic interchange contains a truncated record');
         }
@@ -88,6 +88,7 @@ export class GenericSessionInterchangeAdapter {
             sourceSchemaVersion: header.schemaVersion,
             consistency: header.consistency,
             operationalState: 'available',
+            declaredWorkspaceId: header.workspace.id,
         };
     }
     async *stream(source, cursor) {
@@ -99,7 +100,7 @@ export class GenericSessionInterchangeAdapter {
             const first = await iterator.next();
             await iterator.return?.();
             if (first.done)
-                throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty');
+                throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty', schemaIssueDetail('<root>'));
             header = this.validateHeader(first.value.value, source);
         }
         const input = await this.openStream(source, byteCursor ?? undefined);
@@ -159,7 +160,7 @@ export class GenericSessionInterchangeAdapter {
             };
         }
         if (!header) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty', schemaIssueDetail('<root>'));
         }
         if (input.incompleteTail) {
             throw new SessionContractError('TRUNCATED_SOURCE', 'generic interchange contains a truncated record');
@@ -179,7 +180,10 @@ export class GenericSessionInterchangeAdapter {
         const header = parseHeader(value);
         assertSupportedSchemaMajor(header.schemaVersion);
         if (header.sourceId !== source.sourceId) {
-            throw new SessionContractError('SCHEMA_DRIFT', 'selected source identity does not match interchange header');
+            // SCHEMA_DRIFT: the selected identity no longer describes this file's
+            // declared source, so importing it would attach events to the wrong source.
+            throw new SessionContractError('SCHEMA_DRIFT', `selected source identity does not match interchange header: --source-id ${quoteValue(source.sourceId)} `
+                + `but header sourceId is ${quoteValue(header.sourceId)}; pass --source-id ${quoteValue(header.sourceId)}`, schemaIssueDetail('sourceId'));
         }
         return header;
     }
@@ -189,7 +193,7 @@ function parseByteCursor(value) {
         return null;
     const position = value.slice(5);
     if (!/^\d+$/.test(position)) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid generic byte cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid generic byte cursor', schemaIssueDetail('cursor'));
     }
     return Number(position);
 }
@@ -200,7 +204,10 @@ function parseHeader(value) {
     if (hasAmbiguousTimestamp(result.error)) {
         throw new SessionContractError('AMBIGUOUS_TIMESTAMP', 'generic interchange header has an ambiguous timestamp');
     }
-    throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared AIWG generic session interchange');
+    if (!isDeclaredInterchange(value)) {
+        throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared AIWG generic session interchange', schemaRejectionDetail(result.error));
+    }
+    throw new SessionContractError('MALFORMED_SOURCE', `generic interchange header ${describeIssue(result.error, true)}`, schemaRejectionDetail(result.error));
 }
 function parseEvent(value) {
     const result = GenericInterchangeEventSchema.safeParse(value);
@@ -209,7 +216,34 @@ function parseEvent(value) {
     if (hasAmbiguousTimestamp(result.error)) {
         throw new SessionContractError('AMBIGUOUS_TIMESTAMP', 'generic interchange event has an ambiguous timestamp');
     }
-    throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange event is malformed');
+    // Event values can carry transcript content, so name the field and the
+    // expected shape without echoing the received value.
+    throw new SessionContractError('MALFORMED_SOURCE', `generic interchange event is malformed: ${describeIssue(result.error, false)}`, schemaRejectionDetail(result.error));
+}
+function isDeclaredInterchange(value) {
+    return typeof value === 'object' && value !== null
+        && value.type === GENERIC_INTERCHANGE_KIND;
+}
+function quoteValue(value) {
+    const text = typeof value === 'string' ? value : JSON.stringify(value) ?? String(value);
+    return JSON.stringify(text.length > 64 ? `${text.slice(0, 64)}…` : text);
+}
+function describeIssue(error, echoReceived) {
+    const issue = error.issues[0];
+    const field = issue.path.length > 0 ? `field "${issue.path.join('.')}"` : 'record';
+    if (issue.code === z.ZodIssueCode.invalid_enum_value) {
+        const received = echoReceived ? ` (got ${quoteValue(issue.received)})` : '';
+        return `${field} must be one of ${issue.options.join('|')}${received}`;
+    }
+    if (issue.code === z.ZodIssueCode.invalid_type) {
+        return issue.received === 'undefined'
+            ? `${field} is required (${issue.expected})`
+            : `${field} must be ${issue.expected} (got ${issue.received})`;
+    }
+    if (issue.code === z.ZodIssueCode.invalid_literal) {
+        return `${field} must be ${quoteValue(issue.expected)}`;
+    }
+    return `${field} is invalid: ${issue.message}`;
 }
 function hasAmbiguousTimestamp(error) {
     return error.issues.some((issue) => issue.code === z.ZodIssueCode.custom
@@ -219,7 +253,7 @@ function parseEventCursor(value) {
     if (value === undefined || value === '')
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'generic event cursor is invalid');
+        throw new SessionContractError('SCHEMA_DRIFT', 'generic event cursor is invalid', schemaIssueDetail('cursor'));
     return Number(value);
 }
 //# sourceMappingURL=generic.js.map