@skill-harness/adapters 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -32,3 +32,5 @@ export * from "./archive-access.js";
 export * from "./archive-facts.js";
 export * from "./trust-lifecycle.js";
 export * from "./producer-review.js";
+export * from './session-observation.js';
+export * from './session-retention.js';

package/dist/index.js

@@ -44,4 +44,6 @@ export * from "./archive-access.js";
 export * from "./archive-facts.js";
 export * from "./trust-lifecycle.js";
 export * from "./producer-review.js";
+export * from './session-observation.js';
+export * from './session-retention.js';
 //# sourceMappingURL=index.js.map

package/dist/learning-workspace.d.ts

@@ -51,6 +51,68 @@ export interface LearningRegistryReceipt {
  * exposure, registry mutation, authentication or hostile-same-UID protection. */
 export declare function createLearningWorkspace(directory: string, input: LearningWorkspaceInput): {
     configuration: () => LearningWorkspaceInput;
+    bindSession(raw: {
+        name: string;
+        title: string;
+        manifestId: string;
+    }): {
+        name: string;
+        title: string;
+        manifestId: string;
+    };
+    noteSession(name: string, raw: {
+        kind: "finding" | "proposal" | "acceptance" | "context";
+        note: string;
+        item: number;
+        line: number;
+    }): {
+        author: string;
+        kind: "finding" | "proposal" | "acceptance" | "context";
+        note: string;
+        item: number;
+        line: number;
+    };
+    sessions(): ({
+        state: string;
+        sessionId: string;
+        reason: string;
+        name: string;
+        title: string;
+        manifestId: string;
+    } | {
+        state: string;
+        sessionId: null;
+        reason: string;
+        name: string;
+        title: string;
+        manifestId: string;
+    })[];
+    session(name: string): {
+        annotations: {
+            kind: string;
+            note: string;
+            item: number;
+            line: number;
+            author: string;
+        }[];
+        acceptance: "not-assessed";
+        parent: import("./session-observation.js").SessionObservation;
+        children: {
+            source: number;
+            executionId: string | null;
+            session: import("./session-observation.js").SessionObservation;
+        }[];
+        attempts: import("./session-observation.js").SessionAttempt[];
+        gaps: string[];
+        version: "retrospective-session-v1";
+        manifestId: string;
+        selectionDigest: string;
+        sources: (import("./session-retention.js").Source & {
+            manifestId: string;
+        })[];
+        name: string;
+        title: string;
+    };
     dashboardBinding(): {
         trustDirectory: string | null;
         trustPolicyId: string | null;
@@ -404,6 +466,21 @@ export declare function createLearningWorkspace(directory: string, input: Learni
         version: "learning-workspace-view-v1";
         configuration: LearningWorkspaceInput;
         mode: "deliberate-review";
+        sessions: ({
+            state: string;
+            sessionId: string;
+            reason: string;
+            name: string;
+            title: string;
+            manifestId: string;
+        } | {
+            state: string;
+            sessionId: null;
+            reason: string;
+            name: string;
+            title: string;
+            manifestId: string;
+        })[];
         cases: ({
             name: string;
             title: string;
@@ -485,6 +562,68 @@ export declare function createLearningWorkspace(directory: string, input: Learni
 };
 export declare function openLearningWorkspace(directory: string): {
     configuration: () => LearningWorkspaceInput;
+    bindSession(raw: {
+        name: string;
+        title: string;
+        manifestId: string;
+    }): {
+        name: string;
+        title: string;
+        manifestId: string;
+    };
+    noteSession(name: string, raw: {
+        kind: "finding" | "proposal" | "acceptance" | "context";
+        note: string;
+        item: number;
+        line: number;
+    }): {
+        author: string;
+        kind: "finding" | "proposal" | "acceptance" | "context";
+        note: string;
+        item: number;
+        line: number;
+    };
+    sessions(): ({
+        state: string;
+        sessionId: string;
+        reason: string;
+        name: string;
+        title: string;
+        manifestId: string;
+    } | {
+        state: string;
+        sessionId: null;
+        reason: string;
+        name: string;
+        title: string;
+        manifestId: string;
+    })[];
+    session(name: string): {
+        annotations: {
+            kind: string;
+            note: string;
+            item: number;
+            line: number;
+            author: string;
+        }[];
+        acceptance: "not-assessed";
+        parent: import("./session-observation.js").SessionObservation;
+        children: {
+            source: number;
+            executionId: string | null;
+            session: import("./session-observation.js").SessionObservation;
+        }[];
+        attempts: import("./session-observation.js").SessionAttempt[];
+        gaps: string[];
+        version: "retrospective-session-v1";
+        manifestId: string;
+        selectionDigest: string;
+        sources: (import("./session-retention.js").Source & {
+            manifestId: string;
+        })[];
+        name: string;
+        title: string;
+    };
     dashboardBinding(): {
         trustDirectory: string | null;
         trustPolicyId: string | null;
@@ -838,6 +977,21 @@ export declare function openLearningWorkspace(directory: string): {
         version: "learning-workspace-view-v1";
         configuration: LearningWorkspaceInput;
         mode: "deliberate-review";
+        sessions: ({
+            state: string;
+            sessionId: string;
+            reason: string;
+            name: string;
+            title: string;
+            manifestId: string;
+        } | {
+            state: string;
+            sessionId: null;
+            reason: string;
+            name: string;
+            title: string;
+            manifestId: string;
+        })[];
         cases: ({
             name: string;
             title: string;

package/dist/learning-workspace.js

@@ -1,3 +1,4 @@
+import { readRetainedSession, readRetainedSessionSource } from './session-retention.js';
 import { mkdirSync, readdirSync, lstatSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { buildHypothesis, buildAdoptionBinding, authorizeAdoption, authorizeRollback, buildRollbackRequest, classifyProductionObservation, } from '@skill-harness/core';
@@ -120,7 +121,7 @@ export function openLearningWorkspace(directory) {
     const history = () => {
         verifyLearningStore(input.archiveRoot, 'workspace', workspaceKey(input), directory, learningHash(initial));
         const rows = journal.read(), names = new Set(), decisions = new Map();
-        const known = new Set(['case-binding', 'comparison-binding', 'comparison-context', 'hypothesis-binding', 'unflagged-binding', 'trust-binding', 'quality-pending', 'quality', 'decision', 'adoption', 'activation', 'rollback-request', 'rollback', 'outcome', 'lifecycle']);
+        const known = new Set(['session-note', 'session-binding', 'case-binding', 'comparison-binding', 'comparison-context', 'hypothesis-binding', 'unflagged-binding', 'trust-binding', 'quality-pending', 'quality', 'decision', 'adoption', 'activation', 'rollback-request', 'rollback', 'outcome', 'lifecycle']);
         for (const row of rows.slice(1)) {
             const v = row.value;
             if (!known.has(String(v.type)))
@@ -313,6 +314,47 @@ export function openLearningWorkspace(directory) {
     history();
     return {
         configuration: () => learningCopy(input),
+        bindSession(raw) {
+            const b = learningCopy(raw);
+            closed(b, ['name', 'title', 'manifestId']);
+            named(b);
+            hash(b.manifestId);
+            readRetainedSession(input.archiveRoot, b.manifestId);
+            bound('session-binding', b);
+            return b;
+        },
+        noteSession(name, raw) {
+            const a = learningCopy(raw);
+            closed(a, ['kind', 'note', 'item', 'line']);
+            text(a.note);
+            if (!['finding', 'proposal', 'acceptance', 'context'].includes(a.kind) || !Number.isSafeInteger(a.item) || a.item < 1 || !Number.isSafeInteger(a.line) || a.line < 1)
+                throw Error('valid annotation and evidence reference required');
+            const b = selected('session-binding', name);
+            const bytes = readRetainedSessionSource(input.archiveRoot, b.manifestId, a.item - 1);
+            const content = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+            const count = content.length === 0 ? 0 : content.split('\n').length - (content.endsWith('\n') ? 1 : 0);
+            if (a.line > count)
+                throw Error('annotation evidence line outside retained source');
+            const annotation = { ...a, author: input.author };
+            append({ type: 'session-note', name, annotation });
+            return annotation;
+        },
+        sessions() {
+            return bindings('session-binding').map(b => {
+                try {
+                    const view = readRetainedSession(input.archiveRoot, b.manifestId);
+                    return { ...b, state: 'ready', sessionId: view.parent.sessionId, reason: 'retrospective evidence; assessment pending' };
+                }
+                catch (e) {
+                    return { ...b, state: 'deferred', sessionId: null, reason: message(e) };
+                }
+            });
+        },
+        session(name) {
+            const b = selected('session-binding', name);
+            return { ...b, ...readRetainedSession(input.archiveRoot, b.manifestId),
+                annotations: events().filter(e => e.type === 'session-note' && e.name === name).map(e => e.annotation) };
+        },
         dashboardBinding() {
             const trust = currentTrust(), binding = events().filter(e => e.type === 'trust-binding').at(-1);
             return { trustDirectory: trust && binding ? String(binding.directory) : null, trustPolicyId: trust ? trust.inspect(0).policyId : null };
@@ -616,7 +658,7 @@ export function openLearningWorkspace(directory) {
             catch (e) {
                 trust = { state: 'deferred', reason: message(e), automaticExposure: { mode: 'silent', reason: 'invalid-trust-evidence' } };
             }
-            return { version: 'learning-workspace-view-v1', configuration: learningCopy(input), mode: 'deliberate-review', cases, comparisons, trust, automaticExposureReserved: false, delegationStarted: false, acceptance: 'not-assessed' };
+            return { version: 'learning-workspace-view-v1', configuration: learningCopy(input), mode: 'deliberate-review', sessions: this.sessions(), cases, comparisons, trust, automaticExposureReserved: false, delegationStarted: false, acceptance: 'not-assessed' };
         },
     };
 }

package/dist/session-observation.d.ts

@@ -0,0 +1,50 @@
+type Row = Record<string, any>;
+export interface SessionTimelineEntry {
+    line: number;
+    timestamp: string | null;
+    kind: string;
+    excerpt: string;
+}
+export interface SessionObservation {
+    version: 'pi-session-observation-v1';
+    sessionId: string;
+    cwd: string;
+    timeline: SessionTimelineEntry[];
+    toolCalls: Record<string, number>;
+    userMessages: number;
+    assistantMessages: number;
+    modelRecords: {
+        provider: string;
+        model: string;
+        messages: number;
+    }[];
+    usage: {
+        fields: Record<string, {
+            sum: number;
+            reportedMessages: number;
+        }>;
+        assistantMessages: number;
+        scope: 'this-transcript-only';
+    };
+    lastActivity: string | null;
+    lastAssistantStop: string | null;
+    gaps: string[];
+}
+export declare function sessionText(bytes: Uint8Array): string;
+export declare function sessionRows(bytes: Uint8Array): Row[];
+/** Chronological visible history, including abandoned branches. Never interprets prose as approval. */
+export declare function observePiSession(bytes: Uint8Array): SessionObservation;
+export interface SessionAttempt {
+    executionId: string;
+    parentExecutionId: string | null;
+    logicalChildId: string;
+    agent: string | null;
+    state: string;
+    pane: string | null;
+    startedAt: string | null;
+    endedAt: string | null;
+    runningSeconds: number | null;
+}
+export declare function observeSessionLedger(bytes: Uint8Array): SessionAttempt[];
+export declare function sessionScope(observation: SessionObservation, sourceSha256: string): string;
+export {};

package/dist/session-observation.js

@@ -0,0 +1,186 @@
+import { learningHash } from './learning-journal.js';
+import { normalizePiDaddyLedgerV3 } from './trajectory.js';
+export function sessionText(bytes) {
+    if (bytes.byteLength > 8 * 1024 * 1024)
+        throw Error('session source exceeds 8 MiB');
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}
+export function sessionRows(bytes) {
+    const text = sessionText(bytes);
+    if (!text.endsWith('\n'))
+        throw Error('incomplete session/ledger line; retry after the writer settles');
+    const lines = text.slice(0, -1).split('\n');
+    if (lines.length > 4096)
+        throw Error('session source exceeds 4096 records');
+    return lines.map((line, i) => {
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            throw Error('invalid JSON record at line ' + (i + 1));
+        }
+        if (!row || typeof row !== 'object' || Array.isArray(row))
+            throw Error('object record required at line ' + (i + 1));
+        return row;
+    });
+}
+function value(v, max = 512) {
+    if (typeof v !== 'string' || !v.trim() || v.length > max)
+        throw Error('bounded session identifier required');
+    return v;
+}
+const stamp = (v) => typeof v === 'string' && Number.isFinite(Date.parse(v)) ? v : null;
+const excerpt = (v) => v.length > 512 ? v.slice(0, 512) + ' … [excerpt; inspect retained source for complete text]' : v;
+/** Chronological visible history, including abandoned branches. Never interprets prose as approval. */
+export function observePiSession(bytes) {
+    const rows = sessionRows(bytes), header = rows[0];
+    if (header?.type !== 'session' || header.version !== 3)
+        throw Error('Pi session format version 3 required');
+    const sessionId = value(header.id), cwd = value(header.cwd, 4096), ids = new Set();
+    const timeline = [], tools = new Map(), models = new Map();
+    const fields = {};
+    let userMessages = 0, assistantMessages = 0, lastAssistantStop = null, lastActivity = null, opaque = 0;
+    const add = (i, row, kind, text) => timeline.push({ line: i + 1, timestamp: stamp(row.timestamp), kind, excerpt: excerpt(text) });
+    rows.forEach((row, i) => {
+        if (i && row.type === 'session')
+            throw Error('multiple session headers');
+        if (row.id !== undefined) {
+            const id = value(row.id);
+            if (ids.has(id))
+                throw Error('duplicate session record id');
+            ids.add(id);
+        }
+        lastActivity = stamp(row.timestamp) ?? lastActivity;
+        if (row.type === 'model_change') {
+            add(i, row, 'model-setting', [row.provider, row.modelId].filter(x => typeof x === 'string').join('/'));
+            return;
+        }
+        if (row.type === 'thinking_level_change') {
+            add(i, row, 'thinking-setting', String(row.thinkingLevel ?? 'unknown'));
+            return;
+        }
+        if (row.type !== 'message')
+            return;
+        const m = row.message;
+        if (!m || typeof m !== 'object' || Array.isArray(m))
+            throw Error('invalid session message');
+        const content = typeof m.content === 'string' ? [{ type: 'text', text: m.content }] : m.content;
+        if (!Array.isArray(content))
+            throw Error('invalid session message content');
+        const text = content.filter(c => c?.type === 'text' && typeof c.text === 'string').map(c => c.text).join('\n');
+        if (m.role === 'user') {
+            userMessages++;
+            add(i, row, 'user-message', text);
+        }
+        else if (m.role === 'assistant') {
+            assistantMessages++;
+            lastAssistantStop = typeof m.stopReason === 'string' ? m.stopReason : null;
+            const provider = typeof m.provider === 'string' ? m.provider : 'unknown', model = typeof m.model === 'string' ? m.model : 'unknown';
+            const key = JSON.stringify([provider, model]), record = models.get(key) ?? { provider, model, messages: 0 };
+            record.messages++;
+            models.set(key, record);
+            if (text)
+                add(i, row, 'assistant-message', text);
+            for (const field of ['input', 'output', 'cacheRead', 'cacheWrite', 'totalTokens']) {
+                const n = m.usage?.[field];
+                if (n === undefined)
+                    continue;
+                if (!Number.isSafeInteger(n) || n < 0)
+                    throw Error('invalid provider-reported usage');
+                const f = fields[field] ?? { sum: 0, reportedMessages: 0 };
+                f.sum += n;
+                f.reportedMessages++;
+                if (!Number.isSafeInteger(f.sum))
+                    throw Error('usage sum overflow');
+                fields[field] = f;
+            }
+            for (const c of content)
+                if (c?.type === 'toolCall') {
+                    const name = value(c.name, 128);
+                    tools.set(name, (tools.get(name) ?? 0) + 1);
+                    add(i, row, 'tool-call', name);
+                }
+        }
+        else if (m.role === 'toolResult')
+            add(i, row, 'tool-result', String(m.toolName ?? 'unknown') + (m.isError === true ? ' — tool reported error' : ' — result recorded; success not inferred'));
+        else
+            opaque++;
+    });
+    const gaps = [
+        'Retrospective chronological transcript; branch selection and live continuity are not established.',
+        'Messages and tool results are evidence to inspect, not independently verified decisions, tests or acceptance.',
+        'Only explicit inputs are captured. Source revision, initial workspace and external user feedback may be missing.',
+        'Usage is provider-reported repeated-request usage, not unique context, billing or complete parent/child accounting.',
+    ];
+    if (opaque)
+        gaps.push(opaque + ' message(s) with other roles omitted from the timeline; retained source is complete.');
+    if (!assistantMessages || Object.values(fields).some(f => f.reportedMessages < assistantMessages) || Object.keys(fields).length < 5)
+        gaps.push('Usage fields are missing; sums cover only reported messages.');
+    if (lastAssistantStop !== 'stop')
+        gaps.push('No final assistant stop observed; this snapshot may represent unfinished work.');
+    return { version: 'pi-session-observation-v1', sessionId, cwd, timeline, toolCalls: Object.fromEntries(tools), userMessages, assistantMessages, modelRecords: [...models.values()], usage: { fields, assistantMessages, scope: 'this-transcript-only' }, lastActivity, lastAssistantStop, gaps };
+}
+export function observeSessionLedger(bytes) {
+    const rows = sessionRows(bytes);
+    normalizePiDaddyLedgerV3(sessionText(bytes));
+    const attempts = new Map(), decisions = new Set(), lifecycles = new Set(), deadlines = new Map(), displayed = new Set();
+    for (const row of rows) {
+        if (!['capability_decision', 'child_lifecycle', 'workspace_lease'].includes(row.event) || String(row.childId).startsWith('check:'))
+            continue;
+        const id = value(row.executionId), old = attempts.get(id);
+        if (old && (old.parentExecutionId !== row.parentExecutionId || old.logicalChildId !== row.childId))
+            throw Error('execution identity changed');
+        const a = old ?? { executionId: id, parentExecutionId: row.parentExecutionId, logicalChildId: row.childId, agent: null, state: 'unknown', pane: null, startedAt: null, endedAt: null, runningSeconds: null };
+        if (row.event === 'workspace_lease') {
+            attempts.set(id, a);
+            continue;
+        }
+        displayed.add(id);
+        if (row.event === 'capability_decision') {
+            if (decisions.has(id))
+                throw Error('duplicate capability decision for one execution');
+            decisions.add(id);
+            a.agent = row.agentType;
+            a.state = row.blocked ? 'refused' : a.state === 'unknown' ? 'authorised' : a.state;
+        }
+        else {
+            if (a.endedAt)
+                throw Error('lifecycle after terminal execution');
+            if (lifecycles.has(id) && row.state === 'starting')
+                throw Error('duplicate starting lifecycle event');
+            if (deadlines.has(id) && stamp(row.deadlineAt) && deadlines.get(id) !== row.deadlineAt)
+                throw Error('lifecycle deadline changed');
+            if (stamp(row.deadlineAt))
+                deadlines.set(id, row.deadlineAt);
+            lifecycles.add(id);
+            a.state = row.state;
+            a.pane = row.herdrPaneId ?? a.pane;
+            if (row.state === 'running')
+                a.startedAt = a.startedAt ?? row.ts;
+            if (['completed', 'failed'].includes(row.state))
+                a.endedAt = row.ts;
+        }
+        if (a.startedAt && a.endedAt) {
+            a.runningSeconds = (Date.parse(a.endedAt) - Date.parse(a.startedAt)) / 1000;
+            if (a.runningSeconds < 0)
+                throw Error('negative execution duration');
+        }
+        attempts.set(id, a);
+    }
+    for (const a of attempts.values()) {
+        const seen = new Set();
+        let cursor = a;
+        while (cursor) {
+            if (seen.has(cursor.executionId))
+                throw Error('execution parent cycle');
+            seen.add(cursor.executionId);
+            cursor = cursor.parentExecutionId ? attempts.get(cursor.parentExecutionId) : undefined;
+        }
+    }
+    return [...attempts.values()].filter(a => displayed.has(a.executionId));
+}
+export function sessionScope(observation, sourceSha256) {
+    return learningHash({ kind: 'retrospective-pi-session', sessionId: observation.sessionId, sourceSha256 });
+}
+//# sourceMappingURL=session-observation.js.map

package/dist/session-retention.d.ts

@@ -0,0 +1,48 @@
+import { observeSessionLedger, type SessionObservation } from './session-observation.js';
+export interface SessionSourceSelection {
+    kind: 'parent' | 'child' | 'ledger' | 'feedback' | 'artifact';
+    path: string;
+    executionId?: string;
+}
+export interface Source {
+    kind: SessionSourceSelection['kind'];
+    path: string;
+    sha256: string;
+    bytes: number;
+    executionId: string | null;
+}
+export interface SessionImportPreview {
+    version: 'session-import-preview-v1';
+    digest: string;
+    sources: Source[];
+    parent: SessionObservation;
+    children: {
+        source: number;
+        executionId: string | null;
+        session: SessionObservation;
+    }[];
+    attempts: ReturnType<typeof observeSessionLedger>;
+    gaps: string[];
+    acceptance: 'not-assessed';
+}
+/** Explicit local selection only. Does not scan session directories, follow links, or contact workers. */
+export declare function prepareSessionImport(selections: SessionSourceSelection[]): SessionImportPreview;
+export declare function retainSessionImport(root: string, preview: SessionImportPreview, expectedDigest: string): string;
+export declare function readRetainedSession(root: string, manifestId: string): {
+    acceptance: "not-assessed";
+    parent: SessionObservation;
+    children: {
+        source: number;
+        executionId: string | null;
+        session: SessionObservation;
+    }[];
+    attempts: import("./session-observation.js").SessionAttempt[];
+    gaps: string[];
+    version: "retrospective-session-v1";
+    manifestId: string;
+    selectionDigest: string;
+    sources: (Source & {
+        manifestId: string;
+    })[];
+};
+export declare function readRetainedSessionSource(root: string, manifestId: string, index: number): Buffer;

package/dist/session-retention.js

@@ -0,0 +1,121 @@
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { learningFile, learningHash, learningCopy } from './learning-journal.js';
+import { retainArchiveSource, readArchiveSource } from './evidence-archive.js';
+import { observePiSession, observeSessionLedger, sessionText } from './session-observation.js';
+const captured = new WeakMap();
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function checkedSelections(input) {
+    if (!Array.isArray(input) || input.length < 1 || input.length > 16)
+        throw Error('select 1–16 explicit session sources');
+    const seen = new Set(), executions = new Set();
+    let parents = 0, ledgers = 0;
+    for (const s of input) {
+        if (!s || typeof s !== 'object' || Object.keys(s).some(k => !['kind', 'path', 'executionId'].includes(k)))
+            throw Error('closed source selection required');
+        if (!['parent', 'child', 'ledger', 'feedback', 'artifact'].includes(s.kind) || typeof s.path !== 'string' || resolve(s.path) !== s.path)
+            throw Error('explicit absolute source path required');
+        if (seen.has(s.path))
+            throw Error('duplicate session source');
+        seen.add(s.path);
+        if (s.kind === 'parent')
+            parents++;
+        if (s.kind === 'ledger')
+            ledgers++;
+        if (s.executionId !== undefined) {
+            if (s.kind !== 'child' || !/^exec:[0-9a-f-]{36}$/i.test(s.executionId) || executions.has(s.executionId))
+                throw Error('unique child execution id required');
+            executions.add(s.executionId);
+        }
+    }
+    if (parents !== 1 || ledgers > 1)
+        throw Error('exactly one parent and at most one ledger required');
+}
+function projectSession(selections, buffers) {
+    const parent = observePiSession(buffers[selections.findIndex(s => s.kind === 'parent')]);
+    const children = selections.flatMap((s, i) => s.kind === 'child' ? [{ source: i, executionId: s.executionId ?? null, session: observePiSession(buffers[i]) }] : []);
+    if (new Set([parent.sessionId, ...children.map(c => c.session.sessionId)]).size !== children.length + 1)
+        throw Error('duplicate parent/child session id');
+    const ledger = selections.findIndex(s => s.kind === 'ledger'), attempts = ledger < 0 ? [] : observeSessionLedger(buffers[ledger]);
+    for (const child of children)
+        if (child.executionId && !attempts.some(a => a.executionId === child.executionId))
+            throw Error('selected child execution absent from ledger');
+    const gaps = [...parent.gaps, 'No quality, acceptance, calibrated learning or adoption is inferred from this import.'];
+    for (const child of children)
+        gaps.push(...child.session.gaps.map(g => 'Child source ' + (child.source + 1) + ' (' + child.session.sessionId + '): ' + g));
+    if (ledger < 0)
+        gaps.push('No delegation ledger selected.');
+    else
+        gaps.push('Ledger/session association is operator-selected, not authenticated; ledger may include other sessions.');
+    if (attempts.length > children.filter(c => c.executionId).length)
+        gaps.push('Child transcript coverage incomplete; no combined token total is claimed.');
+    if (children.length)
+        gaps.push('Child execution mappings are explicit operator declarations, not proof of parentage. Each transcript has separate usage.');
+    if (!selections.some(s => s.kind === 'feedback'))
+        gaps.push('External feedback not supplied; user messages remain available for review.');
+    if (!selections.some(s => s.kind === 'artifact'))
+        gaps.push('No final artifact or source snapshot supplied.');
+    return { parent, children, attempts, gaps };
+}
+/** Explicit local selection only. Does not scan session directories, follow links, or contact workers. */
+export function prepareSessionImport(selections) {
+    checkedSelections(selections);
+    const buffers = selections.map(s => learningFile(s.path, 8 * 1024 * 1024));
+    if (buffers.reduce((n, b) => n + b.length, 0) > 32 * 1024 * 1024)
+        throw Error('session selection exceeds 32 MiB');
+    const sources = selections.map((s, i) => ({ ...s, executionId: s.executionId ?? null, sha256: sha(buffers[i]), bytes: buffers[i].length }));
+    const { parent, children, attempts, gaps } = projectSession(selections, buffers);
+    const digest = learningHash({ version: 'session-selection-v1', sources });
+    const preview = { version: 'session-import-preview-v1', digest, sources, parent, children, attempts, gaps, acceptance: 'not-assessed' };
+    captured.set(preview, { preview: learningCopy(preview), buffers });
+    return preview;
+}
+export function retainSessionImport(root, preview, expectedDigest) {
+    const c = captured.get(preview);
+    if (!c || learningHash(c.preview) !== learningHash(preview) || expectedDigest !== c.preview.digest)
+        throw Error('exact preview digest required; changed or forged session import');
+    for (const s of c.preview.sources)
+        if (sha(learningFile(s.path, 8 * 1024 * 1024)) !== s.sha256)
+            throw Error('session source changed since preview; prepare again');
+    const sources = c.preview.sources.map((s, i) => {
+        const parser = s.kind === 'parent' || s.kind === 'child' ? 'pi-session-jsonl' : s.kind === 'ledger' ? 'pi-daddy-session-ledger' : 'session-evidence';
+        const r = retainArchiveSource(root, { sourceId: 'session-' + s.sha256, parser: { id: parser, version: '1' }, retention: 'exact', bytes: c.buffers[i] });
+        return { ...s, manifestId: r.manifestId };
+    });
+    const record = { version: 'retrospective-session-v1', selectionDigest: preview.digest, sources };
+    return retainArchiveSource(root, { sourceId: 'retrospective-' + preview.digest, parser: { id: 'retrospective-session', version: '1' }, retention: 'exact', bytes: Buffer.from(JSON.stringify(record)) }).manifestId;
+}
+export function readRetainedSession(root, manifestId) {
+    const selected = readArchiveSource(root, manifestId);
+    if (selected.status !== 'available' || selected.reference.retention !== 'exact' || selected.reference.parser.id !== 'retrospective-session' || selected.reference.parser.version !== '1')
+        throw Error('retained session unavailable or unsupported');
+    const record = JSON.parse(sessionText(selected.bytes));
+    if (!record || record.version !== 'retrospective-session-v1' || Object.keys(record).sort().join() !== 'selectionDigest,sources,version' || !Array.isArray(record.sources))
+        throw Error('invalid retained session');
+    checkedSelections(record.sources.map(s => ({ kind: s.kind, path: s.path, ...(s.executionId === null ? {} : { executionId: s.executionId }) })));
+    const sources = record.sources.map(s => {
+        if (Object.keys(s).sort().join() !== 'bytes,executionId,kind,manifestId,path,sha256')
+            throw Error('invalid retained session source');
+        const r = readArchiveSource(root, s.manifestId);
+        if (r.status !== 'available' || r.reference.retention !== 'exact' || r.reference.sha256 !== s.sha256 || r.bytes.length !== s.bytes)
+            throw Error('retained session source missing or changed');
+        return { selection: s, bytes: r.bytes };
+    });
+    if (sources.reduce((n, s) => n + s.bytes.length, 0) > 32 * 1024 * 1024)
+        throw Error('session selection exceeds 32 MiB');
+    const plain = record.sources.map(({ manifestId, ...s }) => s);
+    if (learningHash({ version: 'session-selection-v1', sources: plain }) !== record.selectionDigest)
+        throw Error('retained session selection mismatch');
+    const projection = projectSession(record.sources.map(s => ({ kind: s.kind, path: s.path, ...(s.executionId === null ? {} : { executionId: s.executionId }) })), sources.map(s => s.bytes));
+    return { version: record.version, manifestId, selectionDigest: record.selectionDigest, sources: record.sources, ...projection, acceptance: 'not-assessed' };
+}
+export function readRetainedSessionSource(root, manifestId, index) {
+    const session = readRetainedSession(root, manifestId), source = session.sources[index];
+    if (!Number.isSafeInteger(index) || !source)
+        throw Error('select a listed session source');
+    const result = readArchiveSource(root, source.manifestId);
+    if (result.status !== 'available')
+        throw Error('session source unavailable');
+    return result.bytes;
+}
+//# sourceMappingURL=session-retention.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@skill-harness/adapters",
-    "version": "0.16.0",
+    "version": "0.17.0",
     "description": "skill-harness harness adapters — pi runner + claude-code judge routing (internal API)",
     "type": "module",
     "license": "MIT",
@@ -40,7 +40,7 @@
         "prepack": "node ../../scripts/release-pack.mjs --guard"
     },
     "dependencies": {
-        "@skill-harness/core": "0.16.0",
+        "@skill-harness/core": "0.17.0",
         "typebox": "1.3.4"
     }
 }