@aiwg/cli 2026.10.1 → 2026.10.4

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

@@ -1,49 +1,459 @@
 /**
- * Grok Bot session adapter — manual-export only until product evidence exists
- * for a native session filesystem or API locator.
+ * Grok Bot session adapter — manual-export interchange plus an evidence-gated
+ * native locator for the Grok Bot desktop app's local transcript cache.
  *
- * Auto-discover is unsupported and must never scrape invented ~/.grokbot,
- * Cursor session paths, or other unverified roots.
+ * Native discovery (#2970) is Linux-only and requires an explicitly
+ * authorized `sand-client-persistence` root (`--grokbot-root`); there is no
+ * default path and nothing is guessed for macOS/Windows, where the layout is
+ * unverified. The store is one JSON document per key, named `<base32
+ * key>.blob` (RFC 4648 section 6, lowercase, unpadded). Discovery decodes
+ * ONLY filenames to classify them; it never opens a file whose decoded key
+ * is outside the allowlist below, and it never recurses or follows symlinks.
  *
- * Authorized imports reuse the AIWG generic session interchange format so
- * operators can supply an explicit export without inventing a Grok schema.
+ * Allowlisted keys (see grokbot-locator.ts):
+ *   - `...transcript.replicas.<conversation-uuid>` — one conversation; the
+ *     only key class ever selected as an importable source.
+ *   - `...roster.last-roster` — account conversation index; never opened by
+ *     this adapter (no session content), kept out of discover() results.
+ * Every other key (composer-drafts, send-journal, experiments, ui-layout,
+ * sand-secrets, box-secrets, cookies, local/session storage, etc.) is never
+ * decoded content, never opened, and `~/.grokbot` (daemon credentials) is
+ * never referenced.
+ *
+ * Grok Bot conversations carry no workspace/cwd field — there is no native
+ * evidence linking a conversation to a project directory. Following the
+ * established precedent for other account-scoped, non-workspace-scoped
+ * native locators (`pi`, `deepseek-harness`: no per-source workspace
+ * filtering in workspace-discovery.ts), every authorized conversation under
+ * `--grokbot-root` surfaces to whichever workspace runs discovery; this
+ * adapter never guesses a workspace link and `inspect()` never sets
+ * `declaredWorkspaceId` for native sources.
+ *
+ * The replica is a bounded client-side cache (~200 entries) that can evict
+ * its oldest entries as new ones arrive, so a re-read is not append-only —
+ * the file may shrink, and Grok Bot may rewrite it via a rename-swap that
+ * changes its inode. This adapter declares `sourceContinuity: 'snapshot'`
+ * (contracts.ts), which tells the shared importer to skip its generic
+ * size-shrink / file-identity / prefix-rewrite checks (those assume
+ * append-only growth) for this source. Idempotent, non-duplicating re-import
+ * across the sliding window then relies on two things instead: (1)
+ * `workspace-discovery.ts` assigns a conversation-id–derived,
+ * content-independent `sourceId` for native sources (mirroring the existing
+ * OMP convention), so the importer's checkpoint continuity survives content
+ * changes; (2) `stream()` resumes from the native, monotonic `seq` carried
+ * by each entry (not a position/byte offset, which the sliding window would
+ * invalidate) and tags every record's `sourceCursor` as `native:<seq>` — an
+ * opaque provider-native resume token the importer stores verbatim
+ * (`positionKind: 'provider-native'`), never reinterpreted as a byte offset.
+ * Combined with the catalog's identity-keyed `INSERT OR IGNORE`, re-importing
+ * after the window has slid can only add genuinely new entries, never
+ * duplicate ones.
  *
  * @see docs/providers/grokbot-sessions.md
- * @issue #215
+ * @issue #215, #2970
  */
-import { SessionContractError, } from '../contracts.js';
+import { opendir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+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';
 export const GROKBOT_ADAPTER_VERSION = '1.0.0';
 export const GROKBOT_EXPORT_SCHEMA_VERSION = '1.0.0';
+export const GROKBOT_NATIVE_SCHEMA_VERSION = '1.0.0';
+export const GROKBOT_NATIVE_SCHEMA_MAJOR = 1;
 export const GROKBOT_LOCATOR_CLASS = 'manual-export';
+export const GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS = 'grokbot-native-transcript-replica';
+const GrokbotEntryBaseSchema = z.object({
+    kind: z.string().min(1),
+    id: z.string().min(1),
+    timestampMs: z.number().int().nonnegative(),
+    requestId: z.string().optional(),
+    seq: z.number().int().nonnegative(),
+}).passthrough();
+const SendMessageEntrySchema = GrokbotEntryBaseSchema.extend({
+    kind: z.literal('send-message'),
+    respondedValue: z.unknown().optional(),
+    secretProvided: z.boolean().optional(),
+    message: z.discriminatedUnion('type', [
+        z.object({ type: z.literal('text'), content: z.string() }).passthrough(),
+        z.object({
+            type: z.literal('widget'),
+            widget: z.object({ prompt: z.string() }).passthrough(),
+        }).passthrough(),
+        z.object({
+            type: z.literal('email-draft'),
+            draft: z.object({ subject: z.string().optional(), body: z.string() }).passthrough(),
+        }).passthrough(),
+        z.object({
+            type: z.literal('slack-draft'),
+            draft: z.object({ target: z.string().optional(), body: z.string() }).passthrough(),
+        }).passthrough(),
+        z.object({
+            type: z.literal('attachment'),
+            url: z.string(),
+            file_name: z.string(),
+        }).passthrough(),
+        z.object({
+            type: z.literal('user-form'),
+            formRequest: z.object({ title: z.string() }).passthrough(),
+        }).passthrough(),
+        z.object({
+            type: z.literal('secret-request'),
+            secretRequest: z.object({ label: z.string() }).passthrough(),
+        }).passthrough(),
+    ]),
+});
+const MessageEntrySchema = GrokbotEntryBaseSchema.extend({
+    kind: z.literal('message'),
+    role: z.enum(['user', 'assistant']),
+    content: z.string(),
+    fromAgent: z.object({ id: z.string().optional(), name: z.string().optional() })
+        .passthrough().optional(),
+});
+const UserAttachmentEntrySchema = GrokbotEntryBaseSchema.extend({
+    kind: z.literal('user-attachment'),
+    file_name: z.string(),
+    file_path: z.string().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    byteSize: z.number().optional(),
+});
+const EventEntrySchema = GrokbotEntryBaseSchema.extend({
+    kind: z.literal('event'),
+    event: z.record(z.string(), z.unknown()),
+});
+const NoticeEntrySchema = GrokbotEntryBaseSchema.extend({
+    kind: z.literal('notice'),
+    text: z.string(),
+});
+const GrokbotReplicaValueSchema = z.object({
+    entries: z.array(GrokbotEntryBaseSchema),
+    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(),
+    value: GrokbotReplicaValueSchema,
+}).passthrough();
 export class GrokbotSessionAdapter {
+    limits;
+    maxFiles;
     provider = 'grokbot';
     adapterVersion = GROKBOT_ADAPTER_VERSION;
-    disposition = 'manual-only';
-    supportedOperations = ['inspect', 'stream'];
-    acquisitionModes = ['manual-export'];
+    disposition = 'implemented';
+    supportedOperations = ['discover', 'inspect', 'stream'];
+    acquisitionModes = ['manual-export', 'jsonl'];
+    /**
+     * The replica is rewritten wholesale (sliding window, possible
+     * rename-swap), not appended to. See the class-level doc comment.
+     */
+    sourceContinuity = 'snapshot';
     interchange;
-    constructor(limits) {
+    constructor(limits, maxFiles = 10_000) {
+        this.limits = limits;
+        this.maxFiles = maxFiles;
         this.interchange = new GenericSessionInterchangeAdapter(limits);
     }
-    async *discover(_scope) {
-        throw new SessionContractError('UNSUPPORTED_OPERATION', 'Grok Bot session auto-discover is unsupported until a verified native locator exists; '
-            + 'select an authorized manual export explicitly. AIWG does not scrape ~/.grokbot, '
-            + '~/grokbot-skills, or Cursor session paths.');
+    async *discover(scope) {
+        if (scope.allowedRoots.length === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Bot native discovery requires an explicitly authorized sand-client-persistence root; '
+                + 'pass --grokbot-root. There is no default root and nothing is guessed for macOS or Windows.');
+        }
+        let count = 0;
+        for (const root of [...scope.allowedRoots].sort()) {
+            let directory;
+            try {
+                directory = await opendir(resolve(root));
+            }
+            catch {
+                continue;
+            }
+            for await (const dirent of directory) {
+                // Never recurse, never follow symlinks: only plain files directly
+                // under the authorized root are even filename-classified.
+                if (!dirent.isFile())
+                    continue;
+                const classification = classifyGrokbotBlobName(dirent.name);
+                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', { limit: 'maxFiles', configured: this.maxFiles, observed: count });
+                }
+                yield {
+                    provider: 'grokbot',
+                    locator: resolve(root, dirent.name),
+                    locatorClass: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS,
+                };
+            }
+        }
     }
     async inspect(source) {
-        this.assertManualExport(source);
-        return this.interchange.inspect(source);
+        if (source.locatorClass === GROKBOT_LOCATOR_CLASS) {
+            return this.interchange.inspect(source);
+        }
+        this.assertNativeReplica(source);
+        const native = await this.readReplica(source);
+        return {
+            sourceSchemaVersion: GROKBOT_NATIVE_SCHEMA_VERSION,
+            consistency: native.truncated ? 'provisional' : 'complete',
+            operationalState: 'available',
+            // No native evidence links a conversation to a workspace/cwd; never
+            // fabricate one.
+        };
     }
     async *stream(source, cursor) {
-        this.assertManualExport(source);
-        yield* this.interchange.stream(source, cursor);
+        if (source.locatorClass === GROKBOT_LOCATOR_CLASS) {
+            yield* this.interchange.stream(source, cursor);
+            return;
+        }
+        this.assertNativeReplica(source);
+        const native = await this.readReplica(source);
+        const conversationId = grokbotConversationIdFromLocator(source.locator);
+        if (!conversationId) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Bot native locator does not decode to an authorized transcript-replica key');
+        }
+        const lastSeq = parseNativeCursor(cursor?.value);
+        const seen = new Set();
+        for (const entry of native.entries) {
+            if (seen.has(entry.seq)) {
+                throw new SessionContractError('DUPLICATE_NATIVE_ID', 'Grok Bot transcript replica contains a duplicate entry sequence');
+            }
+            seen.add(entry.seq);
+            if (entry.seq <= lastSeq)
+                continue;
+            const mapped = mapGrokbotEntry(entry);
+            if (!mapped)
+                continue; // Unrecognized entry kind: skipped, never fabricated.
+            yield {
+                nativeSessionId: conversationId,
+                nativeEventId: mapped.nativeEventId,
+                sequence: mapped.sequence,
+                kind: mapped.kind,
+                role: mapped.role,
+                participant: mapped.participant,
+                text: mapped.text,
+                occurredAt: mapped.occurredAt,
+                // Opaque provider-native resume token: the importer stores this
+                // verbatim (positionKind: 'provider-native') and never reinterprets
+                // it as a byte offset. It encodes the last imported native `seq`,
+                // which is monotonic and stable across the bounded cache evicting
+                // old entries. See the class-level doc comment for the full
+                // rationale.
+                sourceCursor: `native:${entry.seq}`,
+                rawReference: { locatorClass: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS, sequence: entry.seq },
+                extensions: mapped.extensions,
+            };
+        }
+    }
+    assertNativeReplica(source) {
+        if (source.locatorClass !== GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', `Grok Bot supports only locatorClass "${GROKBOT_LOCATOR_CLASS}" or `
+                + `"${GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS}" (got "${source.locatorClass}"). `
+                + 'Do not reuse Cursor or other provider locators.');
+        }
+        // Enforce the filename allowlist before any read, not only in discover():
+        // a caller can hand inspect()/stream() any path with the native class.
+        if (!grokbotConversationIdFromLocator(source.locator)) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Grok Bot native locator does not decode to an authorized transcript-replica key');
+        }
     }
-    assertManualExport(source) {
-        if (source.locatorClass !== GROKBOT_LOCATOR_CLASS) {
-            throw new SessionContractError('UNSUPPORTED_OPERATION', `Grok Bot supports only locatorClass "${GROKBOT_LOCATOR_CLASS}" until native session evidence exists `
-                + `(got "${source.locatorClass}"). Do not reuse Cursor session locators.`);
+    async readReplica(source) {
+        const { value } = await readBoundedJson({
+            selectedPath: source.locator,
+            allowedRoots: source.authorizedScope.allowedRoots,
+        }, this.limits);
+        const parsed = GrokbotReplicaDocumentSchema.safeParse(value);
+        if (!parsed.success) {
+            throw malformedGrokbotSource('transcript replica', parsed.error);
         }
+        assertSupportedSchemaMajor(`${parsed.data.schemaVersion}.0.0`, GROKBOT_NATIVE_SCHEMA_MAJOR);
+        const { entries, precedingTimestampMs } = parsed.data.value;
+        // The resume cursor is the last yielded seq, so stream in seq order even
+        // if the cache stores entries out of order.
+        entries.sort((left, right) => left.seq - right.seq);
+        // A window that no longer starts at seq 1 has evicted history, whether or
+        // not the optional precedingTimestampMs hint is present.
+        const truncated = entries.length > 0
+            && (entries[0].seq > 1 || (precedingTimestampMs ?? 0) > 0);
+        return { entries, truncated };
+    }
+}
+function parseNativeCursor(value) {
+    if (!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', schemaIssueDetail('cursor'));
+    return Number(raw);
+}
+function mapGrokbotEntry(entry) {
+    const occurredAt = new Date(entry.timestampMs).toISOString();
+    switch (entry.kind) {
+        case 'send-message':
+            return mapSendMessage(entry, occurredAt);
+        case 'message':
+            return mapMessage(entry, occurredAt);
+        case 'user-attachment':
+            return mapUserAttachment(entry, occurredAt);
+        case 'event':
+            return mapEvent(entry, occurredAt);
+        case 'notice':
+            return mapNotice(entry, occurredAt);
+        default:
+            // Unrecognized entry kind: safely skipped, never fabricated into a record.
+            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 malformedGrokbotSource('send-message entry', parsed.error);
+    }
+    const entry = parsed.data;
+    const { message } = entry;
+    let text;
+    switch (message.type) {
+        case 'text':
+            text = message.content;
+            break;
+        case 'widget':
+            text = `[widget] ${message.widget.prompt} -> ${stringOrEmpty(entry.respondedValue)}`;
+            break;
+        case 'email-draft':
+            text = `[email-draft] ${message.draft.subject ?? ''}\n${message.draft.body}`;
+            break;
+        case 'slack-draft':
+            text = `[slack-draft] ${message.draft.target ?? ''}\n${message.draft.body}`;
+            break;
+        case 'attachment':
+            text = `[attachment] ${message.file_name} (${message.url})`;
+            break;
+        case 'user-form':
+            text = `[user-form] ${message.formRequest.title}`;
+            break;
+        case 'secret-request':
+            text = `[secret-request] ${message.secretRequest.label} (value not exported)`;
+            break;
+        default:
+            text = '';
+    }
+    return {
+        nativeEventId: entry.id,
+        sequence: entry.seq,
+        kind: `grokbot.send-message.${message.type}`,
+        role: 'assistant',
+        text,
+        occurredAt,
+        extensions: {
+            nativeKind: 'send-message',
+            messageType: message.type,
+            secretProvided: entry.secretProvided,
+            provenance: { acquisition: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS },
+        },
+    };
+}
+function mapMessage(raw, occurredAt) {
+    const parsed = MessageEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        throw malformedGrokbotSource('message entry', parsed.error);
+    }
+    const entry = parsed.data;
+    return {
+        nativeEventId: entry.id,
+        sequence: entry.seq,
+        kind: 'grokbot.message',
+        role: entry.role,
+        participant: entry.fromAgent?.name ?? entry.fromAgent?.id,
+        text: entry.content,
+        occurredAt,
+        extensions: {
+            nativeKind: 'message',
+            fromAgent: entry.fromAgent,
+            provenance: { acquisition: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS },
+        },
+    };
+}
+function mapUserAttachment(raw, occurredAt) {
+    const parsed = UserAttachmentEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        throw malformedGrokbotSource('user-attachment entry', parsed.error);
+    }
+    const entry = parsed.data;
+    return {
+        nativeEventId: entry.id,
+        sequence: entry.seq,
+        kind: 'grokbot.user-attachment',
+        role: 'user',
+        text: `[user-attachment] ${entry.file_name} `
+            + `(${entry.width ?? '?'}x${entry.height ?? '?'}, ${entry.byteSize ?? '?'} bytes)`,
+        occurredAt,
+        extensions: {
+            nativeKind: 'user-attachment',
+            fileName: entry.file_name,
+            filePath: entry.file_path,
+            width: entry.width,
+            height: entry.height,
+            byteSize: entry.byteSize,
+            provenance: { acquisition: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS },
+        },
+    };
+}
+function mapEvent(raw, occurredAt) {
+    const parsed = EventEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        throw malformedGrokbotSource('event entry', parsed.error);
+    }
+    const entry = parsed.data;
+    const label = stringOrEmpty(entry.event.kind) || stringOrEmpty(entry.event.type) || 'event';
+    return {
+        nativeEventId: entry.id,
+        sequence: entry.seq,
+        kind: 'grokbot.event',
+        role: 'system',
+        text: `[event] ${label}`,
+        occurredAt,
+        extensions: {
+            nativeKind: 'event',
+            event: entry.event,
+            provenance: { acquisition: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS },
+        },
+    };
+}
+function mapNotice(raw, occurredAt) {
+    const parsed = NoticeEntrySchema.safeParse(raw);
+    if (!parsed.success) {
+        throw malformedGrokbotSource('notice entry', parsed.error);
+    }
+    const entry = parsed.data;
+    return {
+        nativeEventId: entry.id,
+        sequence: entry.seq,
+        kind: 'grokbot.notice',
+        role: 'system',
+        text: entry.text,
+        occurredAt,
+        extensions: {
+            nativeKind: 'notice',
+            provenance: { acquisition: GROKBOT_NATIVE_REPLICA_LOCATOR_CLASS },
+        },
+    };
+}
+function stringOrEmpty(value) {
+    return typeof value === 'string' ? value : '';
+}
 //# sourceMappingURL=grokbot.js.map

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([