@aiwg/cli 2026.10.3 → 2026.10.4

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');
         }
@@ -100,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);
@@ -160,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');
@@ -183,7 +183,7 @@ export class GenericSessionInterchangeAdapter {
             // 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)}`);
+                + `but header sourceId is ${quoteValue(header.sourceId)}; pass --source-id ${quoteValue(header.sourceId)}`, schemaIssueDetail('sourceId'));
         }
         return header;
     }
@@ -193,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);
 }
@@ -205,9 +205,9 @@ function parseHeader(value) {
         throw new SessionContractError('AMBIGUOUS_TIMESTAMP', 'generic interchange header has an ambiguous timestamp');
     }
     if (!isDeclaredInterchange(value)) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared AIWG generic session interchange');
+        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)}`);
+    throw new SessionContractError('MALFORMED_SOURCE', `generic interchange header ${describeIssue(result.error, true)}`, schemaRejectionDetail(result.error));
 }
 function parseEvent(value) {
     const result = GenericInterchangeEventSchema.safeParse(value);
@@ -218,7 +218,7 @@ function parseEvent(value) {
     }
     // 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)}`);
+    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
@@ -253,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

package/dist/src/sessions/adapters/grok-build.js

@@ -1,5 +1,5 @@
 import { basename, extname } from 'node:path';
-import { SessionContractError, } from '../contracts.js';
+import { SessionContractError, schemaIssueDetail, } from '../contracts.js';
 import { readBoundedText } from '../readers.js';
 export const GROK_BUILD_ADAPTER_VERSION = '1.0.0';
 export const GROK_BUILD_CLI_EXPORT_SCHEMA_VERSION = '1.0.0';
@@ -75,7 +75,7 @@ export class GrokBuildSessionAdapter {
         }
         const filename = basename(source.locator, extname(source.locator));
         if (extname(source.locator).toLowerCase() !== '.md' || !UUID.test(filename)) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Grok Build export filename must be <session-id>.md so the documented CLI session ID is preserved.');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Grok Build export filename must be <session-id>.md so the documented CLI session ID is preserved.', schemaIssueDetail('filename'));
         }
         const { value } = await readBoundedText({
             selectedPath: source.locator,
@@ -93,7 +93,7 @@ export function validateGrokBuildMarkdown(value) {
             parseTools(block.text, sequence);
     }
     if (blocks.length === 0 || !blocks.some((block) => block.heading === 'User')) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Unrecognized Grok Build CLI export; expected exact `## User`, `## Assistant`, or `## Tools` headings.');
+        throw new SessionContractError('MALFORMED_SOURCE', 'Unrecognized Grok Build CLI export; expected exact `## User`, `## Assistant`, or `## Tools` headings.', schemaIssueDetail('headings'));
     }
     return blocks;
 }
@@ -105,7 +105,7 @@ function parseBlocks(value) {
             return;
         const text = current.lines.join('\n').trim();
         if (!text && current.heading === 'Tools') {
-            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block is empty');
+            throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block is empty', schemaIssueDetail('tools'));
         }
         if (text)
             blocks.push({ heading: current.heading, text });
@@ -117,13 +117,13 @@ function parseBlocks(value) {
             current = { heading: match[1], lines: [] };
         }
         else if (/^##\s+/.test(line)) {
-            throw new SessionContractError('SCHEMA_DRIFT', `unknown Grok Build CLI export heading: ${line}`);
+            throw new SessionContractError('SCHEMA_DRIFT', `unknown Grok Build CLI export heading: ${line}`, schemaIssueDetail('headings'));
         }
         else if (current) {
             current.lines.push(line);
         }
         else if (line.trim()) {
-            throw new SessionContractError('SCHEMA_DRIFT', 'unexpected content before the first Grok Build CLI export heading');
+            throw new SessionContractError('SCHEMA_DRIFT', 'unexpected content before the first Grok Build CLI export heading', schemaIssueDetail('headings'));
         }
     }
     flush();
@@ -132,17 +132,17 @@ function parseBlocks(value) {
 function parseTools(text, blockSequence) {
     const lines = text.split('\n').filter((line) => line.trim());
     if (lines.length === 0 || lines.length > 1_000) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block has no summaries or exceeds 1,000 summaries');
+        throw new SessionContractError('SCHEMA_DRIFT', 'Grok Build tools block has no summaries or exceeds 1,000 summaries', schemaIssueDetail('tools'));
     }
     return lines.map((line, index) => {
         const match = /^- (.+)$/.exec(line);
         if (!match) {
-            throw new SessionContractError('SCHEMA_DRIFT', `unrecognized Grok Build tool summary: ${line}`);
+            throw new SessionContractError('SCHEMA_DRIFT', `unrecognized Grok Build tool summary: ${line}`, schemaIssueDetail('tools'));
         }
         const summary = match[1];
         const name = summary.split(/:| \(/, 1)[0]?.trim();
         if (!name) {
-            throw new SessionContractError('SCHEMA_DRIFT', 'empty Grok Build tool summary');
+            throw new SessionContractError('SCHEMA_DRIFT', 'empty Grok Build tool summary', schemaIssueDetail('tools'));
         }
         return { sequence: blockSequence * 1_000 + index, name, text: summary };
     });
@@ -176,11 +176,11 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value)) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build export cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build export cursor', schemaIssueDetail('cursor'));
     }
     const cursor = Number(value);
     if (!Number.isSafeInteger(cursor)) {
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build export cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Build export cursor', schemaIssueDetail('cursor'));
     }
     return cursor;
 }

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

@@ -55,7 +55,7 @@
 import { opendir } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { z } from 'zod';
-import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
 import { readBoundedJson } from '../readers.js';
 import { GenericSessionInterchangeAdapter, } from './generic.js';
 import { classifyGrokbotBlobName, grokbotConversationIdFromLocator, } from './grokbot-locator.js';
@@ -130,10 +130,10 @@ const NoticeEntrySchema = GrokbotEntryBaseSchema.extend({
 });
 const GrokbotReplicaValueSchema = z.object({
     entries: z.array(GrokbotEntryBaseSchema),
-    epochHint: z.string().optional(),
-    acceptedSequenceHint: z.number().int().nonnegative().optional(),
-    persistedAt: z.number().int().nonnegative().optional(),
-    precedingTimestampMs: z.number().int().nonnegative().optional(),
+    epochHint: z.string().nullish(),
+    acceptedSequenceHint: z.number().int().nonnegative().nullish(),
+    persistedAt: z.number().int().nonnegative().nullish(),
+    precedingTimestampMs: z.number().int().nonnegative().nullish(),
 }).passthrough();
 const GrokbotReplicaDocumentSchema = z.object({
     schemaVersion: z.number().int().nonnegative(),
@@ -181,7 +181,7 @@ export class GrokbotSessionAdapter {
                 if (classification?.kind !== 'transcript-replica')
                     continue;
                 if (++count > this.maxFiles) {
-                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Bot native discovery exceeded the authorized file limit');
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Grok Bot native discovery exceeded the authorized file limit', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
                 }
                 yield {
                     provider: 'grokbot',
@@ -268,7 +268,7 @@ export class GrokbotSessionAdapter {
         }, this.limits);
         const parsed = GrokbotReplicaDocumentSchema.safeParse(value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Grok Bot transcript replica is malformed');
+            throw malformedGrokbotSource('transcript replica', parsed.error);
         }
         assertSupportedSchemaMajor(`${parsed.data.schemaVersion}.0.0`, GROKBOT_NATIVE_SCHEMA_MAJOR);
         const { entries, precedingTimestampMs } = parsed.data.value;
@@ -287,7 +287,7 @@ function parseNativeCursor(value) {
         return 0;
     const raw = value.startsWith('native:') ? value.slice('native:'.length) : value;
     if (!/^\d+$/.test(raw))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Bot native cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Grok Bot native cursor', schemaIssueDetail('cursor'));
     return Number(raw);
 }
 function mapGrokbotEntry(entry) {
@@ -308,10 +308,21 @@ function mapGrokbotEntry(entry) {
             return null;
     }
 }
+function malformedGrokbotSource(subject, error) {
+    // Include only schema paths and codes, never Zod messages or input values.
+    const issues = error.issues.map((issue) => `${issue.path.join('.') || '<root>'} (${issue.code})`);
+    return new SessionContractError('MALFORMED_SOURCE', `Grok Bot ${subject} is malformed at ${issues.join(', ')}`, schemaRejectionDetail(error));
+}
 function mapSendMessage(raw, occurredAt) {
+    const messageType = z.object({ type: z.string().min(1) }).safeParse(raw.message);
+    if (messageType.success && !SendMessageEntrySchema.shape.message.options.some((option) => option.shape.type.value === messageType.data.type)) {
+        // Like unknown entry kinds, unknown message types are skipped without inventing content.
+        // Known types still go through their full schema validation below.
+        return null;
+    }
     const parsed = SendMessageEntrySchema.safeParse(raw);
     if (!parsed.success) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Grok Bot send-message entry is malformed');
+        throw malformedGrokbotSource('send-message entry', parsed.error);
     }
     const entry = parsed.data;
     const { message } = entry;
@@ -359,7 +370,7 @@ function mapSendMessage(raw, occurredAt) {
 function mapMessage(raw, occurredAt) {
     const parsed = MessageEntrySchema.safeParse(raw);
     if (!parsed.success) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Grok Bot message entry is malformed');
+        throw malformedGrokbotSource('message entry', parsed.error);
     }
     const entry = parsed.data;
     return {
@@ -380,7 +391,7 @@ function mapMessage(raw, occurredAt) {
 function mapUserAttachment(raw, occurredAt) {
     const parsed = UserAttachmentEntrySchema.safeParse(raw);
     if (!parsed.success) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Grok Bot user-attachment entry is malformed');
+        throw malformedGrokbotSource('user-attachment entry', parsed.error);
     }
     const entry = parsed.data;
     return {
@@ -405,7 +416,7 @@ function mapUserAttachment(raw, occurredAt) {
 function mapEvent(raw, occurredAt) {
     const parsed = EventEntrySchema.safeParse(raw);
     if (!parsed.success) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Grok Bot event entry is malformed');
+        throw malformedGrokbotSource('event entry', parsed.error);
     }
     const entry = parsed.data;
     const label = stringOrEmpty(entry.event.kind) || stringOrEmpty(entry.event.type) || 'event';
@@ -426,7 +437,7 @@ function mapEvent(raw, occurredAt) {
 function mapNotice(raw, occurredAt) {
     const parsed = NoticeEntrySchema.safeParse(raw);
     if (!parsed.success) {
-        throw new SessionContractError('MALFORMED_SOURCE', 'Grok Bot notice entry is malformed');
+        throw malformedGrokbotSource('notice entry', parsed.error);
     }
     const entry = parsed.data;
     return {

package/dist/src/sessions/adapters/hermes.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 HERMES_ADAPTER_VERSION = '1.0.0';
 export const HERMES_EXPORT_SCHEMA_VERSION = '1.0.0';
 export const HERMES_NATIVE_SCHEMA_VERSION = '23.0.0';
@@ -73,6 +73,15 @@ export class HermesSessionAdapter {
         // Native exports and consistent snapshots require explicit selection.
     }
     async inspect(source) {
+        if (source.locatorClass === 'hermes-export-jsonl'
+            || source.locatorClass === 'hermes-consistent-snapshot-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,
@@ -94,21 +103,23 @@ export class HermesSessionAdapter {
             let outputIndex = 0;
             let schema = null;
             let sawRecord = false;
+            let complete = true;
             for await (const line of input) {
                 sawRecord = true;
                 const parsed = ExportSchema.safeParse(line.value);
                 if (!parsed.success) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'Hermes export is malformed');
+                    throw new SessionContractError('MALFORMED_SOURCE', 'Hermes export is malformed', schemaRejectionDetail(parsed.error));
                 }
+                complete &&= ended(parsed.data);
                 const currentSchema = declaredSchema(parsed.data);
                 if (schema && schema !== currentSchema) {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed Hermes export schemas');
+                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed Hermes export schemas', schemaIssueDetail('schemaVersion'));
                 }
                 schema = currentSchema;
                 assertSupportedSchemaMajor(schema, 23);
                 if (source.locatorClass === 'hermes-consistent-snapshot-jsonl'
                     && parsed.data.snapshotConsistency !== 'sqlite-backup') {
-                    throw new SessionContractError('SCHEMA_DRIFT', 'Hermes snapshot lacks sqlite3.backup() consistency evidence');
+                    throw new SessionContractError('SCHEMA_DRIFT', 'Hermes snapshot lacks sqlite3.backup() consistency evidence', schemaIssueDetail('snapshotConsistency'));
                 }
                 for (const record of normalizeSession(parsed.data, line, source.locatorClass)) {
                     if (outputIndex++ >= start)
@@ -116,16 +127,21 @@ export class HermesSessionAdapter {
                 }
             }
             if (!sawRecord)
-                throw new SessionContractError('MALFORMED_SOURCE', 'Hermes source is empty');
+                throw new SessionContractError('MALFORMED_SOURCE', 'Hermes source is empty', schemaIssueDetail('<root>'));
             if (input.incompleteTail && source.locatorClass !== 'hermes-export-jsonl') {
                 throw new SessionContractError('TRUNCATED_SOURCE', 'Hermes consistent snapshot is truncated');
             }
-            return;
+            return {
+                sourceSchemaVersion: HERMES_EXPORT_SCHEMA_VERSION,
+                consistency: complete ? '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) {
         if (source.locatorClass === 'hermes-state-db') {
@@ -143,37 +159,19 @@ export class HermesSessionAdapter {
                 value, sequence, byteOffset: sequence, byteLength: Buffer.byteLength(JSON.stringify(value)),
             }));
         }
-        else if (source.locatorClass === 'hermes-export-jsonl'
-            || source.locatorClass === 'hermes-consistent-snapshot-jsonl') {
-            const result = await readBoundedJsonLines({
-                selectedPath: source.locator,
-                allowedRoots: source.authorizedScope.allowedRoots,
-            }, {
-                consistency: source.locatorClass === 'hermes-export-jsonl' ? 'provisional' : 'complete',
-                limits: this.limits,
-            });
-            input = result.records;
-            if (result.incompleteTail && source.locatorClass !== 'hermes-export-jsonl') {
-                throw new SessionContractError('TRUNCATED_SOURCE', 'Hermes consistent snapshot is truncated');
-            }
-        }
         else {
             throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported Hermes source class');
         }
         if (input.length === 0)
-            throw new SessionContractError('MALFORMED_SOURCE', 'Hermes source is empty');
+            throw new SessionContractError('MALFORMED_SOURCE', 'Hermes source is empty', schemaIssueDetail('<root>'));
         const parsed = input.map((line) => {
             const result = ExportSchema.safeParse(line.value);
             if (!result.success)
-                throw new SessionContractError('MALFORMED_SOURCE', 'Hermes export is malformed');
+                throw new SessionContractError('MALFORMED_SOURCE', 'Hermes export is malformed', schemaRejectionDetail(result.error));
             return { line, value: result.data };
         });
         const schemaVersion = declaredVersion(parsed.map(({ value }) => value));
         assertSupportedSchemaMajor(schemaVersion, 23);
-        if (source.locatorClass === 'hermes-consistent-snapshot-jsonl'
-            && parsed.some(({ value }) => value.snapshotConsistency !== 'sqlite-backup')) {
-            throw new SessionContractError('SCHEMA_DRIFT', 'Hermes snapshot lacks sqlite3.backup() consistency evidence');
-        }
         return {
             schemaVersion: HERMES_EXPORT_SCHEMA_VERSION,
             consistency: parsed.every(({ value }) => ended(value)) ? 'complete' : 'provisional',
@@ -291,7 +289,7 @@ function ended(value) {
 function declaredVersion(values) {
     const versions = new Set(values.map(declaredSchema));
     if (versions.size !== 1)
-        throw new SessionContractError('SCHEMA_DRIFT', 'mixed Hermes export schemas');
+        throw new SessionContractError('SCHEMA_DRIFT', 'mixed Hermes export schemas', schemaIssueDetail('schemaVersion'));
     return [...versions][0];
 }
 function declaredSchema(value) {
@@ -330,7 +328,7 @@ function parseCursor(value) {
     if (!value)
         return 0;
     if (!/^\d+$/.test(value))
-        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Hermes cursor');
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Hermes cursor', schemaIssueDetail('cursor'));
     return Number(value);
 }
 const SESSION_KEYS = new Set([