@aiwg/cli 2026.9.12 → 2026.9.16

package/dist/src/sessions/export-plan.js

@@ -0,0 +1,243 @@
+/**
+ * Builds and re-verifies a session export selection plan (#2564). A plan
+ * binds a reviewable, human-inspectable selection to the exact session ids
+ * and source/event digests seen at plan time, so `sessions export build`
+ * can detect a stale plan (source changed since planning) rather than
+ * silently exporting drifted data.
+ */
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SessionContractError } from './contracts.js';
+import { buildSessionAiwgFortemiIndexExport, SESSION_EXPORT_INDEX_SCHEMA_VERSION, } from './fortemi-export-mapping.js';
+import { discoverSessionOutputCandidates } from './output-lineage.js';
+import { FilesystemDerivedOutputIndex } from './output-registration.js';
+export const SESSION_EXPORT_PLAN_SCHEMA_VERSION = '1.1.0';
+function eventDigestSummary(events) {
+    const hash = createHash('sha256');
+    for (const event of events)
+        hash.update(event.digest);
+    return `sha256:${hash.digest('hex')}`;
+}
+function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function sessionMetadataDigest(session, catalogTags) {
+    return sha256(JSON.stringify({ session, catalogTags: [...catalogTags].sort() }));
+}
+function localEventAttachment(event, projectRoot) {
+    const nativeEnvelope = Object.entries(event.extensions)
+        .find(([key, value]) => key.startsWith('native.') && value && typeof value === 'object')?.[1];
+    const attachment = event.extensions.attachment ?? nativeEnvelope?.attachment;
+    if (!attachment || typeof attachment !== 'object')
+        return null;
+    const value = attachment;
+    const filename = typeof value.displayName === 'string' && value.displayName.length > 0
+        ? value.displayName
+        : typeof value.filename === 'string' && value.filename.length > 0 && !value.filename.startsWith('[REDACTED:')
+            ? value.filename
+            : `${event.eventId}.bin`;
+    const mediaType = typeof value.mime === 'string' && value.mime.length > 0 ? value.mime : 'application/octet-stream';
+    if (Array.isArray(value.dataBytes)
+        && value.dataBytes.every((item) => Number.isInteger(item) && Number(item) >= 0 && Number(item) <= 255)) {
+        return { filename, mediaType, bytes: Uint8Array.from(value.dataBytes) };
+    }
+    if (typeof value.dataUrl === 'string') {
+        const match = /^data:([^;,]*)(;base64)?,(.*)$/s.exec(value.dataUrl);
+        if (!match)
+            throw new SessionContractError('MALFORMED_SOURCE', `invalid data URL attachment: ${event.eventId}`);
+        const bytes = match[2]
+            ? Buffer.from(match[3], 'base64')
+            : Buffer.from(decodeURIComponent(match[3]), 'utf8');
+        return { filename, mediaType: match[1] || mediaType, bytes };
+    }
+    if (typeof value.fileUrl === 'string') {
+        if (!projectRoot)
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'project root is required for file attachments');
+        const root = realpathSync(projectRoot);
+        const candidate = fileURLToPath(value.fileUrl);
+        const stat = lstatSync(candidate);
+        if (stat.isSymbolicLink())
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `attachment is a symbolic link: ${event.eventId}`);
+        const actual = realpathSync(candidate);
+        if (actual !== root && !actual.startsWith(`${root}${sep}`)) {
+            throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', `attachment resolves outside the project: ${event.eventId}`);
+        }
+        return { filename, mediaType, bytes: readFileSync(actual) };
+    }
+    return null;
+}
+/**
+ * Selects the requested sessions from the repository and builds a plan.
+ * Rejects an empty or duplicate selection, and any session id the
+ * repository cannot authorize for the given workspace -- an unauthorized
+ * or unknown id is a planning error, not something to silently skip.
+ */
+export function buildSessionExportPlan(repository, options) {
+    const requested = [...new Set(options.sessionIds)];
+    if (requested.length === 0) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'session export plan requires at least one session id');
+    }
+    if (requested.length !== options.sessionIds.length) {
+        throw new SessionContractError('INVALID_ARGUMENT', 'session export plan selection contains duplicate session ids');
+    }
+    const sessions = [];
+    const eventsBySessionId = new Map();
+    const entries = [];
+    for (const sessionId of requested) {
+        const session = repository.getSession(sessionId, options.workspaceId);
+        if (!session) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `session is unknown or not authorized for this workspace: ${sessionId}`);
+        }
+        const events = repository.listEvents(sessionId, options.workspaceId);
+        const catalogTags = repository.listTags(sessionId, options.workspaceId);
+        sessions.push(session);
+        eventsBySessionId.set(sessionId, events);
+        entries.push({
+            sessionId: session.sessionId,
+            nativeSessionId: session.nativeSessionId,
+            provider: session.provider,
+            sourceId: session.sourceId,
+            sourceDigest: session.sourceDigest,
+            metadataDigest: sessionMetadataDigest(session, catalogTags),
+            catalogTags,
+            eventCount: events.length,
+            eventDigestSummary: eventDigestSummary(events),
+        });
+    }
+    const sampleSize = options.previewSampleSize ?? 5;
+    const outputCandidates = options.projectRoot
+        ? discoverSessionOutputCandidates(new FilesystemDerivedOutputIndex(options.projectRoot).registrations(), sessions)
+        : [];
+    const outputs = outputCandidates.map((candidate) => ({
+        sessionId: candidate.sessionId,
+        registrationId: candidate.registration.registrationId,
+        outputLocator: candidate.registration.output.locator,
+        outputDigest: candidate.registration.output.digest,
+        outputByteLength: candidate.registration.output.byteLength,
+        mediaType: candidate.registration.output.mediaType,
+        lineage: candidate.lineage,
+        matchReason: candidate.matchReason,
+    }));
+    const attachments = [];
+    for (const session of sessions) {
+        for (const event of eventsBySessionId.get(session.sessionId) ?? []) {
+            const attachment = localEventAttachment(event, options.projectRoot);
+            if (attachment)
+                attachments.push({
+                    sessionId: session.sessionId,
+                    eventId: event.eventId,
+                    filename: attachment.filename,
+                    mediaType: attachment.mediaType,
+                    digest: sha256(attachment.bytes),
+                    byteLength: attachment.bytes.length,
+                });
+        }
+    }
+    const catalogTagsBySessionId = new Map(entries.map((entry) => [entry.sessionId, entry.catalogTags]));
+    const index = buildSessionAiwgFortemiIndexExport(options.workspaceId, sessions, eventsBySessionId, outputs, catalogTagsBySessionId);
+    const plan = {
+        schemaVersion: SESSION_EXPORT_PLAN_SCHEMA_VERSION,
+        indexSchemaVersion: SESSION_EXPORT_INDEX_SCHEMA_VERSION,
+        generatedAt: new Date().toISOString(),
+        workspaceId: options.workspaceId,
+        sessions: entries,
+        outputs,
+        attachments,
+        totals: {
+            sessionCount: sessions.length,
+            eventCount: entries.reduce((sum, entry) => sum + entry.eventCount, 0),
+            outputCount: outputs.length,
+            attachmentCount: attachments.length,
+            recordCount: index.items.length,
+        },
+        preview: {
+            recordCount: index.items.length,
+            sampleRecordIds: index.items.slice(0, sampleSize).map((item) => item.id),
+        },
+    };
+    return { plan, sessions, eventsBySessionId };
+}
+/**
+ * Re-selects the plan's sessions from the repository and compares digests
+ * against what the plan recorded. Any drift -- a changed source, a
+ * changed/reimported event set, or a session/id that has since disappeared
+ * -- fails closed rather than exporting silently-stale data (#2564
+ * acceptance criteria: "Plans reject stale sources ... changed analysis
+ * bytes").
+ */
+export function reverifySessionExportPlan(repository, plan, options = {}) {
+    const sessions = [];
+    const eventsBySessionId = new Map();
+    const catalogTagsBySessionId = new Map();
+    for (const entry of plan.sessions) {
+        const session = repository.getSession(entry.sessionId, plan.workspaceId);
+        if (!session) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `planned session no longer exists or is not authorized: ${entry.sessionId}`);
+        }
+        if (session.sourceDigest !== entry.sourceDigest) {
+            throw new SessionContractError('SCHEMA_DRIFT', `session source changed since the plan was generated: ${entry.sessionId}`);
+        }
+        const catalogTags = repository.listTags(entry.sessionId, plan.workspaceId);
+        if (entry.metadataDigest !== sessionMetadataDigest(session, catalogTags)
+            || JSON.stringify(entry.catalogTags) !== JSON.stringify(catalogTags)) {
+            throw new SessionContractError('SCHEMA_DRIFT', `session metadata or tags changed since the plan was generated: ${entry.sessionId}`);
+        }
+        const events = repository.listEvents(entry.sessionId, plan.workspaceId);
+        if (events.length !== entry.eventCount || eventDigestSummary(events) !== entry.eventDigestSummary) {
+            throw new SessionContractError('SCHEMA_DRIFT', `session events changed since the plan was generated: ${entry.sessionId}`);
+        }
+        sessions.push(session);
+        eventsBySessionId.set(entry.sessionId, events);
+        catalogTagsBySessionId.set(entry.sessionId, catalogTags);
+    }
+    const outputBytesByRegistrationId = new Map();
+    if (plan.outputs.length > 0) {
+        if (!options.projectRoot) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'project root is required to verify planned outputs');
+        }
+        const root = realpathSync(options.projectRoot);
+        for (const output of plan.outputs) {
+            const candidate = resolve(root, output.outputLocator);
+            let stat;
+            try {
+                stat = lstatSync(candidate);
+            }
+            catch {
+                throw new SessionContractError('SCHEMA_DRIFT', `registered output is missing since the plan was generated: ${output.outputLocator}`);
+            }
+            if (stat.isSymbolicLink()) {
+                throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `planned output is a symbolic link: ${output.outputLocator}`);
+            }
+            if (!stat.isFile()) {
+                throw new SessionContractError('SCHEMA_DRIFT', `planned output is no longer a regular file: ${output.outputLocator}`);
+            }
+            if (stat.size !== output.outputByteLength) {
+                throw new SessionContractError('SCHEMA_DRIFT', `registered output changed since the plan was generated: ${output.outputLocator}`);
+            }
+            const actual = realpathSync(candidate);
+            if (actual !== root && !actual.startsWith(`${root}${sep}`)) {
+                throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'planned output resolves outside the project');
+            }
+            const bytes = readFileSync(actual);
+            if (sha256(bytes) !== output.outputDigest) {
+                throw new SessionContractError('SCHEMA_DRIFT', `registered output changed since the plan was generated: ${output.outputLocator}`);
+            }
+            outputBytesByRegistrationId.set(output.registrationId, bytes);
+        }
+    }
+    const attachmentBytesByEventId = new Map();
+    for (const planned of plan.attachments ?? []) {
+        const event = eventsBySessionId.get(planned.sessionId)?.find((candidate) => candidate.eventId === planned.eventId);
+        const attachment = event ? localEventAttachment(event, options.projectRoot) : null;
+        if (!attachment || attachment.bytes.length !== planned.byteLength || sha256(attachment.bytes) !== planned.digest) {
+            throw new SessionContractError('SCHEMA_DRIFT', `session attachment changed since the plan was generated: ${planned.eventId}`);
+        }
+        attachmentBytesByEventId.set(planned.eventId, attachment.bytes);
+    }
+    return {
+        sessions, eventsBySessionId, catalogTagsBySessionId, outputBytesByRegistrationId, attachmentBytesByEventId,
+    };
+}
+//# sourceMappingURL=export-plan.js.map

package/dist/src/sessions/fortemi-export-mapping.js

@@ -0,0 +1,300 @@
+/**
+ * `record.v1`/`export.v1` forbid exactly the fields this mapping needs
+ * (`source.origin`/`generated`/`checksum`/`updated_at`, relationship
+ * `direction`/`confidence`/`privacy`) -- verified empirically against
+ * @fortemi/core's bundled AJV schema, since the type declarations alone
+ * don't encode this v1/v2 split. Use v2 throughout.
+ */
+export const SESSION_EXPORT_RECORD_SCHEMA_VERSION = 'aiwg.fortemi.index.record.v2';
+export const SESSION_EXPORT_INDEX_SCHEMA_VERSION = 'aiwg.fortemi.index.export.v2';
+const INDEX_GRAPH_ID = 'aiwg-sessions';
+function tag(key, value) {
+    return `${key}:${value}`;
+}
+export function sessionRecordLocator(session) {
+    return `aiwg-session://${session.provider}/${session.sessionId}`;
+}
+export function sessionEventRecordLocator(session, event) {
+    return `${sessionRecordLocator(session)}/event/${event.eventId}`;
+}
+export function sessionToAiwgFortemiRecord(session, catalogTags = []) {
+    const locator = sessionRecordLocator(session);
+    const updatedAt = session.updatedAt ?? session.startedAt ?? new Date(0).toISOString();
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: session.sessionId,
+        type: 'aiwg.session',
+        source: {
+            path: locator,
+            repo_relative_path: locator,
+            locator,
+            origin: 'aiwg-session-catalog',
+            generated: true,
+            checksum: session.sourceDigest,
+            updated_at: updatedAt,
+        },
+        // `title`/`text` are required by @fortemi/core's runtime schema even
+        // though the published type marks them optional -- always emit a
+        // deterministic fallback rather than an empty/undefined value.
+        title: session.intent.title ?? `${session.provider} session ${session.nativeSessionId}`,
+        text: session.intent.summary ?? `AIWG session ${session.sessionId} (${session.provider}, ${session.lifecycle})`,
+        facets: {},
+        tags: [
+            tag('provider', session.provider),
+            tag('lifecycle', session.lifecycle),
+            ...catalogTags.map((value) => tag('catalogTag', value)),
+        ],
+        concepts: [],
+        relationships: [],
+        provenance: [{
+                field: 'source',
+                source: 'aiwg-session-catalog',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+            }],
+        // Structural identifiers this export exists to preserve, carried as a
+        // native provenance_events attribute bag rather than an unmapped
+        // `compatibility` field the full-v1 converter would refuse to archive.
+        provenance_events: [{
+                activity: 'aiwg.session',
+                agent: session.provider,
+                started_at: session.startedAt ?? updatedAt,
+                source: 'aiwg-session-catalog',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+                attributes: {
+                    nativeSessionId: session.nativeSessionId,
+                    sourceId: session.sourceId,
+                    workspaceId: session.workspaceId,
+                    consistency: session.consistency,
+                },
+            }],
+        privacy: { classification: 'public', pii: false },
+        updated_at: updatedAt,
+    };
+}
+export function sessionEventToAiwgFortemiRecord(session, event) {
+    const locator = sessionEventRecordLocator(session, event);
+    const parentLocator = sessionRecordLocator(session);
+    const updatedAt = event.occurredAt ?? new Date(0).toISOString();
+    const relationships = [{
+            type: 'parent-session',
+            target_id: session.sessionId,
+            target_path: parentLocator,
+            direction: 'upstream',
+            // This edge is a structural fact from the session catalog, not a
+            // probabilistic inference -- maximum confidence, not a default.
+            confidence: 1,
+            privacy: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+        }];
+    const provenance = [{
+            field: 'text',
+            source: 'aiwg-session-catalog',
+            path: locator,
+            confidence: 'source',
+            privacy: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+        }];
+    const provenanceEvents = [{
+            activity: `aiwg.session-event.${event.kind}`,
+            agent: event.model ?? session.provider,
+            started_at: event.occurredAt ?? updatedAt,
+            source: 'aiwg-session-catalog',
+            path: locator,
+            confidence: 'source',
+            privacy: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+            attributes: {
+                sessionId: event.sessionId,
+                sourceId: event.sourceId,
+                nativeId: event.nativeId,
+                sequence: event.sequence,
+                toolCallId: event.toolCallId,
+            },
+        }];
+    const tags = [
+        tag('kind', event.kind),
+        ...(event.role ? [tag('role', event.role)] : []),
+        ...(event.toolName ? [tag('tool', event.toolName)] : []),
+        ...(event.entities ?? []).map((entity) => tag('entity', entity)),
+    ];
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: event.eventId,
+        type: 'aiwg.session-event',
+        source: {
+            path: locator,
+            repo_relative_path: locator,
+            locator,
+            origin: 'aiwg-session-catalog',
+            generated: true,
+            checksum: event.digest,
+            updated_at: updatedAt,
+        },
+        title: `${event.kind}${event.role ? ` (${event.role})` : ''} -- ${session.sessionId}`,
+        text: event.searchableText.length > 0 ? event.searchableText : `[${event.kind}: no text content]`,
+        facets: {},
+        tags,
+        // Entities are AIWG-extracted strings, not real SKOS taxonomy concepts
+        // with definitions -- represented as `entity:` tags above, not as
+        // `concepts` (which the full-v1 converter treats as SKOS references and
+        // refuses to archive without SKOS metadata backing them).
+        concepts: [],
+        relationships,
+        provenance,
+        provenance_events: provenanceEvents,
+        privacy: {
+            classification: event.sensitivity.classification === 'sensitive' ? 'private' : 'public',
+            pii: event.sensitivity.classes.length > 0,
+        },
+        updated_at: updatedAt,
+    };
+}
+/**
+ * A registered analysis output associated with a session (#2566), mapped as
+ * a reference record. Like session-event attachments (#2565), this does not
+ * embed the output's original bytes -- only its registration metadata and
+ * digest, which is enough for a consumer to locate and verify the output
+ * against the original registration, not to recover it from the shard
+ * alone. Full byte embedding needs a blob-store integration that neither
+ * #2564 nor #2566 has landed yet; that limitation is shared and explicit,
+ * not silently dropped.
+ */
+export function sessionOutputToAiwgFortemiRecord(session, output) {
+    const locator = `${sessionRecordLocator(session)}/output/${output.registrationId}`;
+    const now = new Date().toISOString();
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: `output_${output.registrationId}`,
+        type: 'aiwg.session-output',
+        source: {
+            path: locator,
+            repo_relative_path: output.outputLocator,
+            locator,
+            origin: 'aiwg-output-registration',
+            generated: true,
+            checksum: output.outputDigest,
+            updated_at: now,
+        },
+        title: `registered output for ${session.sessionId}`,
+        text: `${output.mediaType} output registered at ${output.outputLocator} (${output.matchReason}); `
+            + (output.bytesEmbedded ? 'original bytes embedded as a native attachment.' : 'bytes not embedded -- reference and digest only.'),
+        facets: {},
+        tags: [tag('mediaType', output.mediaType), tag('lineage', 'registered')],
+        concepts: [],
+        relationships: [{
+                type: 'parent-session',
+                target_id: session.sessionId,
+                target_path: sessionRecordLocator(session),
+                direction: 'upstream',
+                confidence: 1,
+                privacy: 'private',
+            }],
+        provenance: [{
+                field: 'source',
+                source: 'aiwg-output-registration',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+            }],
+        provenance_events: [{
+                activity: 'aiwg.session-output',
+                agent: 'aiwg-output-registration',
+                started_at: now,
+                source: 'aiwg-output-registration',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+                attributes: {
+                    sessionId: output.sessionId,
+                    registrationId: output.registrationId,
+                    outputLocator: output.outputLocator,
+                    matchReason: output.matchReason,
+                    bytesEmbedded: output.bytesEmbedded === true,
+                },
+            }],
+        privacy: { classification: 'private', pii: false },
+        updated_at: now,
+    };
+}
+/**
+ * A full-v1 archive has no per-archive metadata sidecar -- only the
+ * `aiwg_source` embedded on each individual note. Without this record, the
+ * index-level wrapper (`source.repo`/`privacy`/`graph`, `generated_at`)
+ * would be a real, disclosed recovery gap. Representing it as one more
+ * ordinary record closes that gap using the exact mechanism already built
+ * for every other field (`provenance_events[0].attributes`), rather than
+ * inventing a second, parallel embedding path.
+ *
+ * The id is prefixed to sort after every `event_`/`output_`/`session_` id
+ * (deterministic regardless of content), and the type is namespaced so
+ * recovery can find and exclude it from the recovered `items` unambiguously.
+ */
+export const EXPORT_MANIFEST_RECORD_TYPE = 'aiwg.session-catalog-export-manifest';
+export const EXPORT_MANIFEST_RECORD_ID = 'zzz-aiwg-session-catalog-export-manifest';
+function exportManifestRecord(repoRef, generatedAt) {
+    const locator = `aiwg-session-catalog://export-manifest/${repoRef}`;
+    return {
+        schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
+        id: EXPORT_MANIFEST_RECORD_ID,
+        type: EXPORT_MANIFEST_RECORD_TYPE,
+        source: {
+            path: locator,
+            repo_relative_path: locator,
+            locator,
+            origin: 'aiwg-session-catalog',
+            generated: true,
+            updated_at: generatedAt,
+        },
+        title: 'AIWG session export manifest',
+        text: `Index-level metadata for this session export (${repoRef}). Not a session, event, or output record.`,
+        facets: {},
+        tags: [tag('graph', INDEX_GRAPH_ID)],
+        concepts: [],
+        relationships: [],
+        provenance: [{
+                field: 'source', source: 'aiwg-session-catalog', path: locator, confidence: 'source', privacy: 'private',
+            }],
+        provenance_events: [{
+                activity: EXPORT_MANIFEST_RECORD_TYPE,
+                agent: 'aiwg-session-catalog',
+                started_at: generatedAt,
+                source: 'aiwg-session-catalog',
+                path: locator,
+                confidence: 'source',
+                privacy: 'private',
+                attributes: { repo: repoRef, privacy: 'private', graph: INDEX_GRAPH_ID, generatedAt },
+            }],
+        privacy: { classification: 'private', pii: false },
+        updated_at: generatedAt,
+    };
+}
+/**
+ * Builds the full record graph for a selected set of sessions. `repoRef` is
+ * a caller-supplied identity for `AiwgFortemiIndexExport.source.repo` (the
+ * session catalog's workspace id, not a git repo -- the field is repurposed
+ * honestly rather than left to imply something untrue).
+ */
+export function buildSessionAiwgFortemiIndexExport(repoRef, sessions, eventsBySessionId, outputs = [], catalogTagsBySessionId = new Map()) {
+    const generatedAt = new Date().toISOString();
+    const items = [exportManifestRecord(repoRef, generatedAt)];
+    for (const session of sessions) {
+        items.push(sessionToAiwgFortemiRecord(session, catalogTagsBySessionId.get(session.sessionId) ?? []));
+        for (const event of eventsBySessionId.get(session.sessionId) ?? []) {
+            items.push(sessionEventToAiwgFortemiRecord(session, event));
+        }
+        for (const output of outputs.filter((entry) => entry.sessionId === session.sessionId)) {
+            items.push(sessionOutputToAiwgFortemiRecord(session, output));
+        }
+    }
+    // Deterministic ordering: reproducible archives, easier diffing.
+    items.sort((left, right) => left.id.localeCompare(right.id));
+    return {
+        schema_version: SESSION_EXPORT_INDEX_SCHEMA_VERSION,
+        generated_at: generatedAt,
+        source: { repo: repoRef, privacy: 'private', graph: INDEX_GRAPH_ID },
+        compatibility: { previous_schema_version: 'aiwg.fortemi.index.export.v1', strategy: 'supported' },
+        items,
+    };
+}
+//# sourceMappingURL=fortemi-export-mapping.js.map

package/dist/src/sessions/fortemi-shard-blobs.js

@@ -0,0 +1,78 @@
+import { computeBlobHash, packTarGz, sha256Hex, unpackTarGz, validateFullV1ShardArchive, } from '@fortemi/core';
+function jsonLines(values) {
+    return new TextEncoder().encode(`${values.map((value) => JSON.stringify(value)).join('\n')}\n`);
+}
+export async function embedAttachmentsInFullV1Shard(archive, attachments) {
+    if (attachments.length === 0)
+        return archive;
+    const files = unpackTarGz(archive);
+    const notesBytes = files.get('notes.jsonl');
+    const manifestBytes = files.get('manifest.json');
+    if (!notesBytes || !manifestBytes)
+        throw new Error('full-v1 shard is missing notes.jsonl or manifest.json');
+    const notes = new TextDecoder().decode(notesBytes).split('\n').filter(Boolean)
+        .map((line) => JSON.parse(line));
+    const byRecordId = new Map(notes.map((note) => [note.metadata?.aiwg_source?.record_id, note]));
+    for (const entry of attachments) {
+        const note = byRecordId.get(entry.recordId);
+        if (!note)
+            throw new Error(`cannot attach bytes: shard record is missing: ${entry.recordId}`);
+        const checksum = computeBlobHash(entry.bytes);
+        note.attachments ??= [];
+        note.attachments.push({
+            extracted_text: null,
+            extraction_status: 'deferred',
+            reason: 'no_extracted_text',
+            attachment: {
+                id: entry.attachmentId,
+                path: entry.filename,
+                mime: entry.mimeType,
+                checksum,
+                bytes: entry.bytes.length,
+            },
+        });
+        files.set(`blobs/${checksum.slice('blake3:'.length)}`, entry.bytes);
+    }
+    const updatedNotes = jsonLines(notes);
+    files.set('notes.jsonl', updatedNotes);
+    const manifest = JSON.parse(new TextDecoder().decode(manifestBytes));
+    manifest.checksums['notes.jsonl'] = await sha256Hex(updatedNotes);
+    files.set('manifest.json', new TextEncoder().encode(JSON.stringify(manifest, null, 2)));
+    const packed = packTarGz(files);
+    const validation = await validateFullV1ShardArchive(packed);
+    if (!validation.valid)
+        throw new Error(`embedded shard failed validation: ${validation.errors.join('; ')}`);
+    return packed;
+}
+export function recoverEmbeddedAttachments(archive) {
+    const files = unpackTarGz(archive);
+    const notesBytes = files.get('notes.jsonl');
+    if (!notesBytes)
+        return [];
+    const notes = new TextDecoder().decode(notesBytes).split('\n').filter(Boolean)
+        .map((line) => JSON.parse(line));
+    const recovered = [];
+    for (const note of notes) {
+        const recordId = note.metadata?.aiwg_source?.record_id;
+        if (!recordId)
+            continue;
+        for (const projection of note.attachments ?? []) {
+            const ref = projection.attachment;
+            const bytes = files.get(`blobs/${ref.checksum.replace(/^blake3:/, '')}`);
+            if (!bytes)
+                continue;
+            if (bytes.length !== ref.bytes || computeBlobHash(bytes) !== ref.checksum) {
+                throw new Error(`embedded attachment failed size/hash verification: ${ref.id}`);
+            }
+            recovered.push({
+                recordId,
+                attachmentId: ref.id,
+                filename: ref.path,
+                mimeType: ref.mime,
+                bytes,
+            });
+        }
+    }
+    return recovered;
+}
+//# sourceMappingURL=fortemi-shard-blobs.js.map