yam-flow 2.8.1 → 2.8.3

package/dist/lib/design-production.d.ts

@@ -129,7 +129,7 @@ export declare function createPlanReviewCanvas(input: {
         visual_correctness: string;
         implementation_correctness: string;
     };
-    truth_status: "verified" | "partial";
+    truth_status: "partial" | "verified";
 }>;
 export declare function addPlanReviewComment(input: {
     root: string;
@@ -147,7 +147,7 @@ export declare function addPlanReviewComment(input: {
         visual_correctness: string;
         implementation_correctness: string;
     };
-    truth_status: "verified" | "partial";
+    truth_status: "partial" | "verified";
 }>;
 export declare function closePlanReviewCanvas(input: {
     root: string;
@@ -165,7 +165,7 @@ export declare function closePlanReviewCanvas(input: {
         visual_correctness: string;
         implementation_correctness: string;
     };
-    truth_status: "verified" | "partial";
+    truth_status: "partial" | "verified";
 }>;
 export declare function readPlanReviewSession(file: string): Promise<PlanReviewSession>;
 export declare function createDesignRevisionState(input: {
@@ -228,7 +228,7 @@ export declare function verifyFinalGalleryManifest(input: {
         implementation_correctness: string;
     };
     next_action: string;
-    truth_status: "blocked" | "partial";
+    truth_status: "partial" | "blocked";
 }>;
 export declare function finalizeDesignProductionPhase(input: {
     root: string;
@@ -283,7 +283,7 @@ export declare function finalizeDesignProductionPhase(input: {
         server: false;
         background_service: false;
     };
-    phase_evidence_status: "complete" | "bounded_stop" | "incomplete";
+    phase_evidence_status: "complete" | "incomplete" | "bounded_stop";
     ready: boolean;
     ready_to_claim_correctness: boolean;
     next_action: string;
@@ -301,6 +301,6 @@ export declare function verifyDesignProductionPhaseReceipt(input: {
     receipt_digest: string;
     ready_to_claim_correctness: boolean;
     next_action: string;
-    truth_status: "blocked" | "partial";
+    truth_status: "partial" | "blocked";
 }>;
 export {};

package/dist/lib/external-updates.d.ts

@@ -22,6 +22,7 @@ export interface ExternalUpdatePaths {
 export interface ExternalUpdateDependencies {
     run?: (command: string, args: string[], options?: ExternalCommandOptions) => Promise<ExternalCommandResult> | ExternalCommandResult;
     fetchJson?: (url: string) => Promise<any>;
+    probeArtifact?: (url: string) => Promise<number>;
     now?: () => Date;
     homeDir?: string;
     env?: NodeJS.ProcessEnv;
@@ -33,7 +34,7 @@ export interface ExternalComponentCheck {
     installed_version: string;
     latest_version: string;
     update_available: boolean;
-    status: 'up_to_date' | 'update_available' | 'not_installed' | 'check_failed';
+    status: 'up_to_date' | 'update_available' | 'not_installed' | 'pending_distribution' | 'check_failed';
     source: string;
     source_revision?: {
         local: string;
@@ -132,4 +133,8 @@ export declare function applyExternalUpdates(currentYamVersion: string, selectio
     truth_status: string;
     next_action: string;
 }>;
+export declare class RegistryHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, url: string);
+}
 export {};

package/dist/lib/external-updates.js

@@ -22,7 +22,7 @@ export async function checkExternalUpdates(currentYamVersion, dependencies = {})
         checkScrapling(deps),
         checkInsaneSearch(deps)
     ]);
-    const failed = checks.filter((item) => item.status === 'check_failed');
+    const failed = checks.filter((item) => item.status === 'check_failed' || item.status === 'pending_distribution');
     return {
         schema: 'yam.external-update-check.v1',
         generated_at: deps.now().toISOString(),
@@ -212,6 +212,7 @@ async function resolveDependencies(input) {
     return {
         run,
         fetchJson: input.fetchJson || defaultFetchJson,
+        probeArtifact: input.probeArtifact || defaultProbeArtifact,
         now: input.now || (() => new Date()),
         homeDir,
         env,
@@ -267,18 +268,57 @@ async function acquireApplyLock(deps) {
     return handle;
 }
 async function checkYam(currentYamVersion, deps) {
+    let pending;
     try {
         const data = await deps.fetchJson(YAM_REGISTRY_URL);
         const latest = requireStableVersion(data?.version, 'yam registry version');
         const installed = requireStableVersion(currentYamVersion, 'installed yam version');
         const integrity = requireIntegrityValue(data?.dist?.integrity, 'yam registry integrity');
         const revision = requireGitRevision(data?.gitHead, 'yam registry gitHead');
+        if (data?.name !== 'yam-flow')
+            throw new Error('yam registry package name mismatch');
+        const tarball = requireYamTarball(data?.dist?.tarball, latest);
+        const exactUrl = `${NPM_REGISTRY}yam-flow/${latest}`;
+        pending = {
+            ...componentCheck('yam', installed, latest, 'npm:yam-flow'),
+            status: 'pending_distribution',
+            error: 'pending_distribution: exact-version metadata or tarball returned HTTP 404; retry the explicit update later',
+            source_receipt: {
+                canonical_url: YAM_REGISTRY_URL,
+                retrieved_at: deps.now().toISOString(),
+                access_path: 'npm latest observed; exact-version distribution readiness incomplete',
+                version: latest,
+                revision,
+                integrity: [integrity]
+            }
+        };
+        let exact;
+        try {
+            exact = await deps.fetchJson(exactUrl);
+        }
+        catch (error) {
+            if (error instanceof RegistryHttpError && error.status === 404)
+                return pending;
+            throw error;
+        }
+        if (exact?.name !== 'yam-flow' || data?.name !== 'yam-flow'
+            || requireStableVersion(exact?.version, 'yam exact registry version') !== latest
+            || requireIntegrityValue(exact?.dist?.integrity, 'yam exact registry integrity') !== integrity
+            || requireGitRevision(exact?.gitHead, 'yam exact registry gitHead') !== revision
+            || requireYamTarball(exact?.dist?.tarball, latest) !== tarball) {
+            throw new Error('yam latest and exact-version registry metadata disagree');
+        }
+        const artifactStatus = await deps.probeArtifact(tarball);
+        if (artifactStatus === 404)
+            return pending;
+        if (artifactStatus !== 200)
+            throw new Error(`yam tarball availability check failed: HTTP ${artifactStatus}`);
         return {
             ...componentCheck('yam', installed, latest, 'npm:yam-flow'),
             source_receipt: {
                 canonical_url: YAM_REGISTRY_URL,
                 retrieved_at: deps.now().toISOString(),
-                access_path: 'npm registry latest endpoint',
+                access_path: 'npm latest + exact-version metadata + bounded no-redirect tarball HEAD (availability only)',
                 version: latest,
                 revision,
                 integrity: [integrity]
@@ -446,7 +486,7 @@ function failedCheck(component, installed, source, error) {
 }
 async function applyYam(currentYamVersion, deps) {
     const check = await checkYam(currentYamVersion, deps);
-    if (check.status === 'check_failed')
+    if (check.status === 'check_failed' || check.status === 'pending_distribution')
         return persistFailureFromCheck(check, deps);
     if (!check.update_available) {
         return persistReceipt(baseReceipt(check, 'up_to_date', [], {
@@ -1378,15 +1418,62 @@ async function defaultRun(command, args, options = {}) {
 }
 async function defaultFetchJson(url) {
     const response = await fetch(url, {
+        redirect: 'error',
+        credentials: 'omit',
         headers: {
             accept: 'application/json',
             'user-agent': 'yam-flow external-update-check'
         },
         signal: AbortSignal.timeout(30000)
     });
-    if (!response.ok)
-        throw new Error(`HTTP ${response.status} for ${url}`);
-    return response.json();
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new RegistryHttpError(response.status, url);
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error(`empty registry response for ${url}`);
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 1024 * 1024)
+                throw new Error('registry metadata exceeds 1 MiB limit');
+            chunks.push(chunk.value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
+export class RegistryHttpError extends Error {
+    status;
+    constructor(status, url) {
+        super(`HTTP ${status} for ${url}`);
+        this.status = status;
+    }
+}
+function requireYamTarball(value, version) {
+    const expected = `${NPM_REGISTRY}yam-flow/-/yam-flow-${version}.tgz`;
+    if (value !== expected)
+        throw new Error('yam tarball must be the exact-version artifact on the official npm registry');
+    return expected;
+}
+async function defaultProbeArtifact(url) {
+    const response = await fetch(url, {
+        method: 'HEAD',
+        redirect: 'error',
+        credentials: 'omit',
+        headers: { 'user-agent': 'yam-flow external-update-check' },
+        signal: AbortSignal.timeout(10000)
+    });
+    await response.body?.cancel();
+    return response.status;
 }
 function requireStableVersion(value, label) {
     const version = String(value || '').trim();

package/dist/lib/hook-readiness.d.ts

@@ -0,0 +1,54 @@
+/** Select an upgrade-stable alias only when it resolves to the running Node binary. */
+export declare function selectHookNode(executable?: string, searchPath?: string): Promise<{
+    executable: string;
+    canonical: string;
+    selection: string;
+    dev: number;
+    ino: number;
+}>;
+export declare function summarizeHookDiscovery(value: unknown, cwd: string, commands: Record<string, string[]>, configPath?: string): {
+    state: string;
+    reason: string;
+    profiles: {};
+    warning_count?: undefined;
+    error_count?: undefined;
+} | {
+    state: string;
+    reason: string;
+    profiles: {
+        [k: string]: {
+            state: string;
+            enabled_trusted: number;
+            eligible_event_coverage: boolean;
+            discovered_count: number;
+            trust_statuses: string[];
+            execution_observed: boolean;
+        };
+    };
+    warning_count: number;
+    error_count: number;
+};
+/** Opt-in discovery in a new app-server process, not the active desktop session. */
+export declare function probeHookDiscovery(options: {
+    executable: string;
+    cwd: string;
+    commands: Record<string, string[]>;
+    configPath?: string;
+    timeoutMs?: number;
+}): Promise<Record<string, unknown>>;
+export declare function recordHookObservation(cwd: string, profile: string, event: string, entrypoint: string): Promise<void>;
+export declare function inspectHookObservation(cwd: string, profile: string, entrypoint: string): Promise<{
+    state: string;
+    reason: string;
+    truth_status: string;
+    host_authenticated: boolean;
+    observed_at?: undefined;
+    event?: undefined;
+} | {
+    state: string;
+    observed_at: any;
+    event: any;
+    host_authenticated: boolean;
+    truth_status: string;
+    reason: string;
+}>;

package/dist/lib/hook-readiness.js

@@ -0,0 +1,259 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+const MAX_BYTES = 256 * 1024;
+const sha = (text) => createHash('sha256').update(text).digest('hex');
+/** Select an upgrade-stable alias only when it resolves to the running Node binary. */
+export async function selectHookNode(executable = process.execPath, searchPath = process.env.PATH || '') {
+    const real = await fsp.realpath(executable);
+    const running = await fsp.stat(real);
+    const candidates = searchPath.split(path.delimiter).filter((dir) => path.isAbsolute(dir))
+        .map((dir) => path.join(dir, process.platform === 'win32' ? 'node.exe' : 'node'));
+    for (const candidate of candidates) {
+        try {
+            const canonical = await fsp.realpath(candidate);
+            const stat = await fsp.stat(canonical);
+            await fsp.access(candidate, fs.constants.X_OK);
+            if (stat.isFile() && stat.dev === running.dev && stat.ino === running.ino && canonical === real) {
+                return { executable: candidate, canonical, selection: 'verified_runtime_alias', dev: stat.dev, ino: stat.ino };
+            }
+        }
+        catch { /* An unverified PATH candidate is never executed. */ }
+    }
+    return { executable: real, canonical: real, selection: 'current_runtime_fallback', dev: running.dev, ino: running.ino };
+}
+export function summarizeHookDiscovery(value, cwd, commands, configPath) {
+    const input = value;
+    if (!Array.isArray(input?.data))
+        return { state: 'unknown', reason: 'unsupported_response_schema', profiles: {} };
+    const entry = input.data.find((row) => row.cwd === cwd);
+    if (!entry || !Array.isArray(entry.hooks) || !Array.isArray(entry.errors) || !Array.isArray(entry.warnings)) {
+        return { state: 'unknown', reason: 'missing_cwd_or_unsupported_response', profiles: {} };
+    }
+    const profiles = Object.fromEntries(Object.entries(commands).map(([profile, expected]) => {
+        const matches = entry.hooks.filter((hook) => hook.handlerType === 'command' && expected.includes(String(hook.command))
+            && (!configPath || hook.sourcePath === configPath));
+        const approved = matches.filter((hook) => hook.enabled === true && ['trusted', 'managed'].includes(String(hook.trustStatus)));
+        const expectedEvents = profile === 'study-note' ? ['userPromptSubmit', 'stop'] : ['userPromptSubmit'];
+        return [profile, { state: matches.length ? 'discovered' : 'not_discovered', enabled_trusted: approved.length,
+                eligible_event_coverage: expectedEvents.every((event) => approved.filter((hook) => hook.eventName === event).length === 1),
+                discovered_count: matches.length, trust_statuses: [...new Set(matches.map((hook) => String(hook.trustStatus)))],
+                execution_observed: false }];
+    }));
+    return { state: entry.errors.length ? 'partial' : 'queried', reason: entry.errors.length ? 'host_discovery_errors' : '',
+        profiles, warning_count: entry.warnings.length, error_count: entry.errors.length };
+}
+/** Opt-in discovery in a new app-server process, not the active desktop session. */
+export async function probeHookDiscovery(options) {
+    const timeoutMs = Math.min(Math.max(options.timeoutMs || 5000, 100), 10000);
+    return new Promise((resolve) => {
+        let finished = false;
+        let stopping = false;
+        let failure = '';
+        let result;
+        let buffer = '';
+        let total = 0;
+        let timer;
+        let killTimer;
+        const child = spawn(options.executable, ['app-server'], { cwd: options.cwd, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+        const stop = (reason = '') => {
+            if (stopping)
+                return;
+            stopping = true;
+            failure = reason;
+            child.stdin.end();
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), 500);
+        };
+        const send = (value) => { if (!stopping)
+            child.stdin.write(`${JSON.stringify(value)}\n`); };
+        child.stdin.on('error', () => stop('protocol_stdin_failed'));
+        child.on('error', () => { failure = 'host_unavailable'; });
+        child.stderr.on('data', (chunk) => { total += chunk.length; if (total > MAX_BYTES)
+            stop('output_limit'); });
+        child.stdout.on('data', (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BYTES)
+                return stop('output_limit');
+            buffer += chunk.toString('utf8');
+            let index;
+            while (!stopping && (index = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    stop('invalid_protocol_json');
+                    break;
+                }
+                if (message.id === 0) {
+                    if (message.error) {
+                        stop('initialization_rejected');
+                        break;
+                    }
+                    send({ method: 'initialized', params: {} });
+                    send({ method: 'hooks/list', id: 1, params: { cwds: [options.cwd] } });
+                }
+                else if (message.id === 1) {
+                    if (message.error) {
+                        stop('hooks_list_unsupported_or_rejected');
+                        break;
+                    }
+                    result = summarizeHookDiscovery(message.result, options.cwd, options.commands, options.configPath);
+                    stop();
+                }
+                else if (message.id != null && message.method) {
+                    stop('unexpected_server_request');
+                }
+            }
+        });
+        child.on('close', (_code, signal) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            clearTimeout(killTimer);
+            resolve({ ...(result || { state: 'unknown', profiles: {} }), ...(failure ? { state: 'unknown', reason: failure } : {}),
+                host_context: 'separate_app_server_probe', active_session_loaded: 'not_measured',
+                execution_observed: false, process_exit_observed: true, termination_signal: signal || null,
+                truth_status: 'partial', reason: failure || (result ? result.reason : 'host_exited_before_response') });
+        });
+        timer = setTimeout(() => stop('probe_timeout'), timeoutMs);
+        send({ method: 'initialize', id: 0, params: { clientInfo: { name: 'yam_hook_probe', version: '1' }, capabilities: { experimentalApi: true } } });
+    });
+}
+async function safeObservationDirectory(cwd, create) {
+    const root = await fsp.realpath(cwd);
+    let current = root;
+    const identities = [];
+    for (const part of ['', '.yam', 'hooks']) {
+        if (part)
+            current = path.join(current, part);
+        if (create && part)
+            await fsp.mkdir(current, { mode: 0o700 }).catch((error) => { if (error.code !== 'EEXIST')
+                throw error; });
+        const stat = await fsp.lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('unsafe_observation_directory');
+        identities.push({ target: current, dev: stat.dev, ino: stat.ino });
+    }
+    return { directory: current, identities };
+}
+async function checkParents(identities) {
+    for (const identity of identities) {
+        const stat = await fsp.lstat(identity.target);
+        if (stat.isSymbolicLink() || !stat.isDirectory() || stat.dev !== identity.dev || stat.ino !== identity.ino)
+            throw new Error('observation_parent_changed');
+    }
+}
+async function configurationDigest(cwd) {
+    const paths = [path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'hooks.json'), path.join(await fsp.realpath(cwd), '.codex', 'hooks.json')];
+    const values = [];
+    for (const target of paths) {
+        try {
+            const before = await fsp.lstat(target);
+            if (!before.isFile() || before.isSymbolicLink() || before.size > MAX_BYTES)
+                throw new Error('unsafe_hook_configuration');
+            const handle = await fsp.open(target, fs.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0));
+            try {
+                const stat = await handle.stat();
+                if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > MAX_BYTES)
+                    throw new Error('hook_configuration_changed');
+                const buffer = Buffer.alloc(MAX_BYTES + 1);
+                const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+                if (bytesRead > MAX_BYTES)
+                    throw new Error('hook_configuration_limit');
+                values.push(sha(buffer.subarray(0, bytesRead).toString('utf8')));
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            values.push('absent');
+        }
+    }
+    return sha(JSON.stringify(values));
+}
+export async function recordHookObservation(cwd, profile, event, entrypoint) {
+    if (!['lite', 'study-note'].includes(profile) || !['UserPromptSubmit', 'Stop'].includes(event))
+        throw new Error('unsupported_observation');
+    const { directory, identities } = await safeObservationDirectory(cwd, true);
+    const value = { schema: 'yam.hook-observation.v1', profile, event, observed_at: new Date().toISOString(),
+        cwd_digest: sha(await fsp.realpath(cwd)), entrypoint_digest: sha(await fsp.readFile(entrypoint, 'utf8')),
+        configuration_digest: await configurationDigest(cwd),
+        host_authenticated: false, evidence_kind: 'local_entrypoint_invocation' };
+    const target = path.join(directory, `${profile}.json`);
+    const noFollow = process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0;
+    const before = await fsp.lstat(target).catch((error) => { if (error.code === 'ENOENT')
+        return null; throw error; });
+    if (before && (!before.isFile() || before.isSymbolicLink() || before.nlink !== 1))
+        throw new Error('unsafe_observation_file');
+    const handle = await fsp.open(target, fs.constants.O_WRONLY | noFollow | (before ? 0 : fs.constants.O_CREAT | fs.constants.O_EXCL), 0o600);
+    try {
+        const stat = await handle.stat();
+        const pathname = await fsp.lstat(target);
+        if (!stat.isFile() || stat.nlink !== 1 || pathname.isSymbolicLink() || pathname.dev !== stat.dev || pathname.ino !== stat.ino
+            || (before && (before.dev !== stat.dev || before.ino !== stat.ino)))
+            throw new Error('unsafe_observation_file');
+        await checkParents(identities);
+        await handle.chmod(0o600);
+        await handle.truncate(0);
+        await handle.writeFile(`${JSON.stringify(value)}\n`);
+        await checkParents(identities);
+        const after = await fsp.lstat(target);
+        if (after.isSymbolicLink() || after.dev !== stat.dev || after.ino !== stat.ino)
+            throw new Error('observation_identity_changed');
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function inspectHookObservation(cwd, profile, entrypoint) {
+    try {
+        if (!['lite', 'study-note'].includes(profile))
+            throw new Error('unsupported_profile');
+        const { directory, identities } = await safeObservationDirectory(cwd, false);
+        const target = path.join(directory, `${profile}.json`);
+        const before = await fsp.lstat(target);
+        if (!before.isFile() || before.isSymbolicLink() || before.size > 4096 || before.nlink !== 1)
+            throw new Error('unsafe_observation_file');
+        const handle = await fsp.open(target, fs.constants.O_RDONLY | (process.platform === 'win32' ? 0 : fs.constants.O_NOFOLLOW || 0));
+        let value;
+        try {
+            const stat = await handle.stat();
+            if (stat.dev !== before.dev || stat.ino !== before.ino || stat.size > 4096)
+                throw new Error('observation_identity_changed');
+            const data = Buffer.alloc(4097);
+            const { bytesRead } = await handle.read(data, 0, data.length, 0);
+            if (bytesRead > 4096)
+                throw new Error('observation_limit');
+            value = JSON.parse(data.subarray(0, bytesRead).toString('utf8'));
+            await checkParents(identities);
+        }
+        finally {
+            await handle.close();
+        }
+        const age = Date.now() - Date.parse(value.observed_at);
+        if (value.schema !== 'yam.hook-observation.v1' || value.profile !== profile || !['UserPromptSubmit', 'Stop'].includes(value.event)
+            || value.host_authenticated !== false || value.evidence_kind !== 'local_entrypoint_invocation'
+            || !Number.isFinite(age) || age < 0 || age > 24 * 60 * 60 * 1000
+            || value.cwd_digest !== sha(await fsp.realpath(cwd)) || value.configuration_digest !== await configurationDigest(cwd)
+            || value.entrypoint_digest !== sha(await fsp.readFile(entrypoint, 'utf8'))) {
+            return { state: 'unknown', reason: 'stale_or_mismatched_observation', truth_status: 'partial', host_authenticated: false };
+        }
+        return { state: 'entrypoint_observed', observed_at: value.observed_at, event: value.event,
+            host_authenticated: false, truth_status: 'partial', reason: 'local_same_user_evidence_not_host_attestation' };
+    }
+    catch (error) {
+        return { state: 'not_observed', reason: error.code === 'ENOENT' ? 'no_observation' : 'observation_unreadable_or_unsafe',
+            host_authenticated: false, truth_status: 'partial' };
+    }
+}

package/dist/lib/memory-records.d.ts

@@ -0,0 +1,29 @@
+import fsp from 'node:fs/promises';
+export type MemoryReadState = 'missing' | 'empty' | 'complete' | 'unreadable' | 'invalid' | 'incomplete';
+export interface MemoryRecord {
+    schemaVersion: number;
+    id: string;
+    kind: string;
+    status: string;
+    summary: string;
+    evidence?: string;
+    action?: string;
+    source?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface MemoryReadReport {
+    schema: 'yam.memory-read.v1';
+    state: MemoryReadState;
+    complete: boolean;
+    records: MemoryRecord[];
+    diagnostics: Array<{
+        operation: string;
+        code: string;
+        record_index?: number;
+    }>;
+    diagnostics_truncated: boolean;
+}
+export type MemoryReadIo = Pick<typeof fsp, 'access' | 'readdir' | 'readFile'>;
+/** Diagnostics intentionally contain no filesystem paths, record text, or exception messages. */
+export declare function readMemoryDirectory(recordsDir: string, io?: MemoryReadIo): Promise<MemoryReadReport>;

package/dist/lib/memory-records.js

@@ -0,0 +1,92 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+const kinds = new Set(['wrong_decision', 'repeat_mistake', 'direction_change', 'lesson', 'risk', 'command']);
+const safeCodes = new Set(['ENOENT', 'EACCES', 'EPERM', 'EIO', 'ENOTDIR', 'EISDIR', 'EMFILE', 'ENFILE', 'ELOOP']);
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === 'string' && safeCodes.has(code) ? code : 'READ_FAILED';
+}
+function isMemoryRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const r = value;
+    return r.schemaVersion === 1 && typeof r.id === 'string' && r.id.length > 0
+        && typeof r.kind === 'string' && kinds.has(r.kind)
+        && (r.status === 'active' || r.status === 'resolved')
+        && typeof r.summary === 'string' && r.summary.trim().length > 0
+        && ['evidence', 'action', 'source', 'createdAt', 'resolvedAt', 'resolution'].every((key) => r[key] === undefined || typeof r[key] === 'string');
+}
+/** Diagnostics intentionally contain no filesystem paths, record text, or exception messages. */
+export async function readMemoryDirectory(recordsDir, io = fsp) {
+    const report = {
+        schema: 'yam.memory-read.v1', state: 'complete', complete: true,
+        records: [], diagnostics: [], diagnostics_truncated: false
+    };
+    const diagnose = (operation, code, record_index) => {
+        if (report.diagnostics.length < 20)
+            report.diagnostics.push({ operation, code, ...(record_index === undefined ? {} : { record_index }) });
+        else
+            report.diagnostics_truncated = true;
+    };
+    try {
+        await io.access(recordsDir);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        report.state = code === 'ENOENT' ? 'missing' : 'unreadable';
+        report.complete = false;
+        diagnose('access', code);
+        return report;
+    }
+    let entries;
+    try {
+        entries = await io.readdir(recordsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        // An existing directory disappearing mid-read is incomplete, not an empty memory.
+        report.state = errorCode(error) === 'ENOENT' ? 'incomplete' : 'unreadable';
+        report.complete = false;
+        diagnose('readdir', errorCode(error));
+        return report;
+    }
+    let invalid = 0;
+    let unreadable = 0;
+    const candidates = entries.filter((entry) => entry.name.endsWith('.json')).sort((a, b) => a.name.localeCompare(b.name));
+    for (const [index, entry] of candidates.entries()) {
+        if (!entry.isFile()) {
+            unreadable += 1;
+            diagnose('record_type', 'NOT_REGULAR_FILE', index);
+            continue;
+        }
+        let text;
+        try {
+            text = await io.readFile(path.join(recordsDir, entry.name), 'utf8');
+        }
+        catch (error) {
+            unreadable += 1;
+            diagnose('read', errorCode(error), index);
+            continue;
+        }
+        let record;
+        try {
+            record = JSON.parse(text);
+        }
+        catch {
+            invalid += 1;
+            diagnose('parse', 'INVALID_JSON', index);
+            continue;
+        }
+        if (!isMemoryRecord(record)) {
+            invalid += 1;
+            diagnose('validate', 'INVALID_RECORD', index);
+            continue;
+        }
+        report.records.push(record);
+    }
+    report.records.sort((a, b) => String(a.createdAt || '').localeCompare(String(b.createdAt || '')));
+    report.complete = invalid + unreadable === 0;
+    report.state = report.complete ? (report.records.length ? 'complete' : 'empty')
+        : report.records.length || (invalid && unreadable) ? 'incomplete'
+            : unreadable ? 'unreadable' : 'invalid';
+    return report;
+}

package/dist/lib/study-note-scope.d.ts

@@ -0,0 +1,8 @@
+/** Hash-only, bounded scope evidence; not a security attestation. */
+export declare function studyNoteTurnScope(input: any, cwd: string, begin?: boolean): {
+    available: boolean;
+    files: string[];
+    source: string;
+    mode: string;
+    reason: string;
+};