@bookedsolid/rea 0.1.0 → 0.2.0

package/dist/cli/install/fs-safe.js

@@ -0,0 +1,347 @@
+/**
+ * Shared safe-filesystem primitives for install-time writes (G12).
+ *
+ * Extracted from `copy.ts` so `upgrade.ts` inherits the same defenses:
+ *   - path containment (destinations must live inside a resolved root)
+ *   - symlink refusal (never write through a link — `rea init` originally
+ *     defended against a malicious PR planting `.claude/hooks/x → /etc/shadow`)
+ *   - parent-directory TOCTOU: `snapshotAncestors` + `verifyAncestorsUnchanged`
+ *   - leaf-level race safety via `O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW`
+ *
+ * Every mutation in `copy.ts` and `upgrade.ts` must go through helpers here.
+ * Adding a new write path and *not* using these helpers is a security bug.
+ */
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+export class UnsafeInstallPathError extends Error {
+    kind;
+    targetPath;
+    linkTarget;
+    constructor(kind, targetPath, linkTarget, message) {
+        super(message);
+        this.name = 'UnsafeInstallPathError';
+        this.kind = kind;
+        this.targetPath = targetPath;
+        if (linkTarget !== undefined)
+            this.linkTarget = linkTarget;
+    }
+}
+/**
+ * Validate that `candidate` is a relative path that stays inside `resolvedRoot`.
+ * Rejects absolute paths, `..` segments, and anything that resolves outside the
+ * root. Returns the fully-resolved absolute path on success.
+ *
+ * Use this on every path that originates from user- or manifest-supplied data
+ * before it touches disk. An attacker who plants
+ * `{"path": "../../../etc/passwd"}` in `.rea/install-manifest.json` must be
+ * refused before any `unlink` / `open` / `copyFile` / `readFile` runs.
+ */
+export function resolveContained(resolvedRoot, candidate) {
+    if (path.isAbsolute(candidate)) {
+        throw new UnsafeInstallPathError('escape', candidate, undefined, `refusing absolute path: ${candidate}`);
+    }
+    // Reject `..` segments on either separator, independent of OS.
+    const parts = candidate.split(/[\\/]/);
+    if (parts.includes('..')) {
+        throw new UnsafeInstallPathError('escape', candidate, undefined, `refusing path with parent-directory segments: ${candidate}`);
+    }
+    const absolute = path.resolve(resolvedRoot, candidate);
+    const rootWithSep = resolvedRoot.endsWith(path.sep)
+        ? resolvedRoot
+        : resolvedRoot + path.sep;
+    if (absolute !== resolvedRoot && !absolute.startsWith(rootWithSep)) {
+        throw new UnsafeInstallPathError('escape', absolute, undefined, `refusing to resolve outside install root: ${absolute} is not under ${resolvedRoot}`);
+    }
+    return absolute;
+}
+/**
+ * Assert that `dstPath` resolves to a location inside `resolvedRoot` and is
+ * either absent or a regular file — never a symlink. Returns `true` if the
+ * destination already exists (regular file), `false` if absent.
+ */
+export async function assertSafeDestination(resolvedRoot, dstPath) {
+    const resolvedDst = path.resolve(dstPath);
+    const rootWithSep = resolvedRoot.endsWith(path.sep)
+        ? resolvedRoot
+        : resolvedRoot + path.sep;
+    if (resolvedDst !== resolvedRoot && !resolvedDst.startsWith(rootWithSep)) {
+        throw new UnsafeInstallPathError('escape', resolvedDst, undefined, `refusing to write outside install root: ${resolvedDst} is not under ${resolvedRoot}`);
+    }
+    let stat;
+    try {
+        stat = await fsPromises.lstat(dstPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+    if (stat.isSymbolicLink()) {
+        let linkTarget = '<unreadable>';
+        try {
+            linkTarget = await fsPromises.readlink(dstPath);
+        }
+        catch {
+            /* informational only */
+        }
+        throw new UnsafeInstallPathError('symlink', dstPath, linkTarget, `refusing to write through symlink at ${dstPath} → ${linkTarget}. ` +
+            `Remove the symlink manually after auditing where it points.`);
+    }
+    if (!stat.isFile()) {
+        throw new UnsafeInstallPathError('escape', dstPath, undefined, `refusing to write: ${dstPath} exists but is not a regular file (mode ${stat.mode.toString(8)})`);
+    }
+    return true;
+}
+export async function assertSafeDirectory(resolvedRoot, dirPath) {
+    const resolvedDir = path.resolve(dirPath);
+    const rootWithSep = resolvedRoot.endsWith(path.sep)
+        ? resolvedRoot
+        : resolvedRoot + path.sep;
+    if (resolvedDir !== resolvedRoot && !resolvedDir.startsWith(rootWithSep)) {
+        throw new UnsafeInstallPathError('escape', resolvedDir, undefined, `refusing to operate on directory outside install root: ${resolvedDir}`);
+    }
+    let stat;
+    try {
+        stat = await fsPromises.lstat(dirPath);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (stat.isSymbolicLink()) {
+        let linkTarget = '<unreadable>';
+        try {
+            linkTarget = await fsPromises.readlink(dirPath);
+        }
+        catch {
+            /* informational only */
+        }
+        throw new UnsafeInstallPathError('symlink', dirPath, linkTarget, `refusing to traverse symlinked directory at ${dirPath} → ${linkTarget}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new UnsafeInstallPathError('escape', dirPath, undefined, `refusing to operate: ${dirPath} exists but is not a directory`);
+    }
+}
+export async function snapshotAncestors(resolvedRoot, dstPath) {
+    const snapshot = new Map();
+    const rootWithSep = resolvedRoot.endsWith(path.sep)
+        ? resolvedRoot
+        : resolvedRoot + path.sep;
+    const leafDir = path.dirname(path.resolve(dstPath));
+    let cursor = leafDir;
+    let reachedRoot = false;
+    while (true) {
+        let lstat;
+        try {
+            lstat = await fsPromises.lstat(cursor);
+        }
+        catch (err) {
+            throw err;
+        }
+        if (lstat.isSymbolicLink()) {
+            let linkTarget = '<unreadable>';
+            try {
+                linkTarget = await fsPromises.readlink(cursor);
+            }
+            catch {
+                /* informational only */
+            }
+            throw new UnsafeInstallPathError('symlink', cursor, linkTarget, `refusing to snapshot: ancestor ${cursor} is a symbolic link → ${linkTarget}. ` +
+                `Remove the symlink manually after auditing where it points.`);
+        }
+        let real;
+        try {
+            real = await fsPromises.realpath(cursor);
+        }
+        catch (err) {
+            throw err;
+        }
+        if (real !== resolvedRoot && !real.startsWith(rootWithSep)) {
+            throw new UnsafeInstallPathError('escape', real, undefined, `refusing to snapshot: ancestor ${cursor} resolves to ${real}, which is outside install root ${resolvedRoot}`);
+        }
+        snapshot.set(cursor, real);
+        if (cursor === resolvedRoot) {
+            reachedRoot = true;
+            break;
+        }
+        const parent = path.dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    if (!reachedRoot) {
+        throw new UnsafeInstallPathError('escape', leafDir, undefined, `refusing to snapshot: ancestor walk from ${leafDir} never reached install root ${resolvedRoot}`);
+    }
+    return snapshot;
+}
+export async function verifyAncestorsUnchanged(snapshot) {
+    for (const [ancestor, originalReal] of snapshot) {
+        let currentReal;
+        try {
+            currentReal = await fsPromises.realpath(ancestor);
+        }
+        catch (err) {
+            throw new UnsafeInstallPathError('ancestor-changed', ancestor, undefined, `refusing to write: ancestor directory ${ancestor} disappeared or became unreadable between validation and write (${err.code ?? 'unknown'})`);
+        }
+        if (currentReal !== originalReal) {
+            throw new UnsafeInstallPathError('ancestor-changed', ancestor, currentReal, `refusing to write: ancestor directory ${ancestor} changed between validation and write (was ${originalReal}, now ${currentReal})`);
+        }
+    }
+}
+/**
+ * Race-safe write: `O_WRONLY | O_CREAT | O_EXCL | O_NOFOLLOW`. Caller must
+ * ensure the leaf does not already exist — `upgrade.ts` overwrite path
+ * `unlink`s first and then calls this.
+ */
+export async function writeFileExclusiveNoFollow(dstPath, contents, mode = 0o644) {
+    const flags = fs.constants.O_WRONLY |
+        fs.constants.O_CREAT |
+        fs.constants.O_EXCL |
+        fs.constants.O_NOFOLLOW;
+    const fh = await fsPromises.open(dstPath, flags, mode);
+    try {
+        await fh.writeFile(contents);
+    }
+    finally {
+        await fh.close();
+    }
+}
+/**
+ * Atomic-ish safe copy: validate containment, snapshot ancestors, `unlink` any
+ * existing regular file (refuse symlinks), write via `O_NOFOLLOW|O_EXCL`, then
+ * `chmod`. Every mutation is bracketed by `verifyAncestorsUnchanged` to close
+ * the TOCTOU window on ancestor swaps.
+ *
+ * Returns the resolved absolute destination path on success.
+ */
+export async function safeInstallFile(opts) {
+    const dstAbs = resolveContained(opts.resolvedRoot, opts.destRelPath);
+    const exists = await assertSafeDestination(opts.resolvedRoot, dstAbs);
+    await fsPromises.mkdir(path.dirname(dstAbs), { recursive: true });
+    const ancestors = await snapshotAncestors(opts.resolvedRoot, dstAbs);
+    const contents = await fsPromises.readFile(opts.srcAbsPath);
+    if (exists) {
+        await verifyAncestorsUnchanged(ancestors);
+        await fsPromises.unlink(dstAbs);
+    }
+    await verifyAncestorsUnchanged(ancestors);
+    await writeFileExclusiveNoFollow(dstAbs, contents, opts.mode);
+    await fsPromises.chmod(dstAbs, opts.mode);
+    return dstAbs;
+}
+/**
+ * Safe delete: validate containment, refuse if the leaf is a symlink or not a
+ * regular file. Used by `rea upgrade` on `removed-upstream` classifications
+ * where the path comes from a manifest (attacker-controllable).
+ */
+export async function safeDeleteFile(resolvedRoot, destRelPath) {
+    const abs = resolveContained(resolvedRoot, destRelPath);
+    let stat;
+    try {
+        stat = await fsPromises.lstat(abs);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (stat.isSymbolicLink()) {
+        let linkTarget = '<unreadable>';
+        try {
+            linkTarget = await fsPromises.readlink(abs);
+        }
+        catch {
+            /* informational */
+        }
+        throw new UnsafeInstallPathError('symlink', abs, linkTarget, `refusing to delete symlink at ${abs} → ${linkTarget}. Audit and remove manually.`);
+    }
+    if (!stat.isFile()) {
+        throw new UnsafeInstallPathError('escape', abs, undefined, `refusing to delete: ${abs} is not a regular file (mode ${stat.mode.toString(8)})`);
+    }
+    // Ancestors must be clean. Snapshot + re-verify to close the TOCTOU window.
+    const ancestors = await snapshotAncestors(resolvedRoot, abs);
+    await verifyAncestorsUnchanged(ancestors);
+    await fsPromises.unlink(abs);
+}
+/**
+ * Safe read: validate containment and that the leaf is a regular file
+ * (refuses symlinks). Used by the drift report and by upgrade's SHA readers
+ * when the path originates from the manifest.
+ */
+export async function safeReadFile(resolvedRoot, destRelPath) {
+    const abs = resolveContained(resolvedRoot, destRelPath);
+    let stat;
+    try {
+        stat = await fsPromises.lstat(abs);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+    if (stat.isSymbolicLink()) {
+        throw new UnsafeInstallPathError('symlink', abs, undefined, `refusing to read symlink at ${abs}`);
+    }
+    if (!stat.isFile())
+        return null;
+    return fsPromises.readFile(abs);
+}
+/**
+ * Atomic tmp + rename with a three-file dance that avoids the Windows
+ * data-loss window. On POSIX, `rename(2)` replaces the destination atomically
+ * and the dance collapses. On Windows, when `rename(tmp → final)` fails with
+ * EEXIST/EPERM:
+ *
+ *   1. `rename(final → final.bak)` — preserves the previous manifest
+ *   2. `rename(tmp → final)` — installs the new one
+ *   3. On success: `unlink(final.bak)`
+ *   4. On failure: `rename(final.bak → final)` to restore; throw
+ *
+ * At every point on disk there is exactly one valid file (either `final` or
+ * `final.bak`). A crash in the middle leaves `final.bak` recoverable.
+ */
+export async function atomicReplaceFile(finalPath, contents) {
+    const dir = path.dirname(finalPath);
+    await fsPromises.mkdir(dir, { recursive: true });
+    const tmp = `${finalPath}.tmp`;
+    const bak = `${finalPath}.bak`;
+    const bytes = typeof contents === 'string' ? Buffer.from(contents, 'utf8') : contents;
+    await fsPromises.writeFile(tmp, bytes);
+    try {
+        await fsPromises.rename(tmp, finalPath);
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== 'EEXIST' && code !== 'EPERM') {
+            await fsPromises.unlink(tmp).catch(() => undefined);
+            throw err;
+        }
+    }
+    // Windows replace path: preserve the current file under .bak first.
+    let movedToBak = false;
+    try {
+        await fsPromises.rename(finalPath, bak);
+        movedToBak = true;
+        await fsPromises.rename(tmp, finalPath);
+        await fsPromises.unlink(bak).catch(() => undefined);
+        return;
+    }
+    catch (retryErr) {
+        // Restore: if we moved the old file to .bak but failed to install the new
+        // one, put the old one back. Never leave the caller with no file at all.
+        if (movedToBak) {
+            try {
+                await fsPromises.rename(bak, finalPath);
+            }
+            catch {
+                // Best-effort. If even the restore fails, the .bak file remains on
+                // disk as a recoverable artifact.
+            }
+        }
+        await fsPromises.unlink(tmp).catch(() => undefined);
+        throw retryErr;
+    }
+}

package/dist/cli/install/manifest-io.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Atomic read/write for `.rea/install-manifest.json` (G12).
+ *
+ * Write uses the three-file dance in `fs-safe.atomicReplaceFile` so that a
+ * Windows rename-retry never leaves the user with *no* manifest — there is
+ * always either `install-manifest.json` or `install-manifest.json.bak` on
+ * disk to recover from.
+ */
+import { type InstallManifest } from './manifest-schema.js';
+export declare function manifestExists(baseDir: string): boolean;
+export declare function readManifest(baseDir: string): Promise<InstallManifest | null>;
+export declare function writeManifestAtomic(baseDir: string, manifest: InstallManifest): Promise<string>;

package/dist/cli/install/manifest-io.js

@@ -0,0 +1,44 @@
+/**
+ * Atomic read/write for `.rea/install-manifest.json` (G12).
+ *
+ * Write uses the three-file dance in `fs-safe.atomicReplaceFile` so that a
+ * Windows rename-retry never leaves the user with *no* manifest — there is
+ * always either `install-manifest.json` or `install-manifest.json.bak` on
+ * disk to recover from.
+ */
+import fs from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import path from 'node:path';
+import { atomicReplaceFile } from './fs-safe.js';
+import { InstallManifestSchema, MANIFEST_RELPATH, serializeManifest, } from './manifest-schema.js';
+function manifestPath(baseDir) {
+    return path.join(baseDir, MANIFEST_RELPATH);
+}
+export function manifestExists(baseDir) {
+    return fs.existsSync(manifestPath(baseDir));
+}
+export async function readManifest(baseDir) {
+    const filePath = manifestPath(baseDir);
+    if (!fs.existsSync(filePath))
+        return null;
+    const raw = await fsPromises.readFile(filePath, 'utf8');
+    let parsedJson;
+    try {
+        parsedJson = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`install manifest is not valid JSON at ${filePath}: ${err instanceof Error ? err.message : String(err)}. ` +
+            `Delete \`.rea/install-manifest.json\` and run \`rea upgrade\` to rebuild from current disk state.`);
+    }
+    const parsed = InstallManifestSchema.safeParse(parsedJson);
+    if (!parsed.success) {
+        throw new Error(`invalid install manifest at ${filePath}: ${parsed.error.message}. ` +
+            `Delete \`.rea/install-manifest.json\` and run \`rea upgrade\` to rebuild.`);
+    }
+    return parsed.data;
+}
+export async function writeManifestAtomic(baseDir, manifest) {
+    const filePath = manifestPath(baseDir);
+    await atomicReplaceFile(filePath, serializeManifest(manifest));
+    return filePath;
+}

package/dist/cli/install/manifest-schema.d.ts

@@ -0,0 +1,83 @@
+/**
+ * G12 — Install manifest schema.
+ *
+ * `rea init` writes `.rea/install-manifest.json` alongside `.rea/policy.yaml`.
+ * `rea upgrade` reads it to classify each canonical shipped file as
+ * `unmodified | drifted | removed-upstream` and decide what to do. `rea doctor
+ * --drift` uses the same data.
+ *
+ * The manifest is strict (zod `.strict()`): unknown fields are rejected at load
+ * time so a newer rea version writing new fields does not silently get
+ * downgraded by an older rea.
+ */
+import { z } from 'zod';
+export declare const MANIFEST_RELPATH = ".rea/install-manifest.json";
+export declare const SourceKindSchema: z.ZodEnum<["hook", "agent", "command", "husky", "claude-md", "settings"]>;
+export type SourceKind = z.infer<typeof SourceKindSchema>;
+export declare const ManifestEntrySchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+    sha256: z.ZodString;
+    source: z.ZodEnum<["hook", "agent", "command", "husky", "claude-md", "settings"]>;
+    mode: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    sha256: string;
+    source: "command" | "hook" | "agent" | "husky" | "claude-md" | "settings";
+    mode?: number | undefined;
+}, {
+    path: string;
+    sha256: string;
+    source: "command" | "hook" | "agent" | "husky" | "claude-md" | "settings";
+    mode?: number | undefined;
+}>;
+export type ManifestEntry = z.infer<typeof ManifestEntrySchema>;
+export declare const InstallManifestSchema: z.ZodObject<{
+    version: z.ZodString;
+    profile: z.ZodString;
+    installed_at: z.ZodString;
+    upgraded_at: z.ZodOptional<z.ZodString>;
+    bootstrap: z.ZodOptional<z.ZodBoolean>;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+        sha256: z.ZodString;
+        source: z.ZodEnum<["hook", "agent", "command", "husky", "claude-md", "settings"]>;
+        mode: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        path: string;
+        sha256: string;
+        source: "command" | "hook" | "agent" | "husky" | "claude-md" | "settings";
+        mode?: number | undefined;
+    }, {
+        path: string;
+        sha256: string;
+        source: "command" | "hook" | "agent" | "husky" | "claude-md" | "settings";
+        mode?: number | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    version: string;
+    profile: string;
+    installed_at: string;
+    files: {
+        path: string;
+        sha256: string;
+        source: "command" | "hook" | "agent" | "husky" | "claude-md" | "settings";
+        mode?: number | undefined;
+    }[];
+    upgraded_at?: string | undefined;
+    bootstrap?: boolean | undefined;
+}, {
+    version: string;
+    profile: string;
+    installed_at: string;
+    files: {
+        path: string;
+        sha256: string;
+        source: "command" | "hook" | "agent" | "husky" | "claude-md" | "settings";
+        mode?: number | undefined;
+    }[];
+    upgraded_at?: string | undefined;
+    bootstrap?: boolean | undefined;
+}>;
+export type InstallManifest = z.infer<typeof InstallManifestSchema>;
+export declare function parseManifest(raw: unknown): InstallManifest;
+export declare function serializeManifest(manifest: InstallManifest): string;

package/dist/cli/install/manifest-schema.js

@@ -0,0 +1,80 @@
+/**
+ * G12 — Install manifest schema.
+ *
+ * `rea init` writes `.rea/install-manifest.json` alongside `.rea/policy.yaml`.
+ * `rea upgrade` reads it to classify each canonical shipped file as
+ * `unmodified | drifted | removed-upstream` and decide what to do. `rea doctor
+ * --drift` uses the same data.
+ *
+ * The manifest is strict (zod `.strict()`): unknown fields are rejected at load
+ * time so a newer rea version writing new fields does not silently get
+ * downgraded by an older rea.
+ */
+import { z } from 'zod';
+export const MANIFEST_RELPATH = '.rea/install-manifest.json';
+export const SourceKindSchema = z.enum([
+    'hook',
+    'agent',
+    'command',
+    'husky',
+    'claude-md',
+    'settings',
+]);
+const Sha256Hex = z.string().regex(/^[a-f0-9]{64}$/, 'expected lowercase hex sha256');
+/**
+ * Path validation for manifest entries. The manifest is attacker-controllable
+ * (it lives in `.rea/install-manifest.json`, a regular repo file that a
+ * compromised PR could mutate), so every entry path must be:
+ *
+ *   - relative (no leading `/` or drive letter)
+ *   - free of `..` segments on either separator
+ *   - free of ASCII control characters (including `\x1b` terminal escapes
+ *     that could corrupt a doctor/upgrade report display)
+ *   - either a canonical install path (plain relative path) or one of two
+ *     synthetic entries: `CLAUDE.md#rea:managed:v1`,
+ *     `.claude/settings.json#rea:desired`
+ *
+ * Absolute paths, parent-directory segments, and control chars all throw at
+ * load time — before any write or delete runs against the entry.
+ */
+const ManifestPath = z
+    .string()
+    .min(1)
+    .refine((p) => !/[\x00-\x1f\x7f]/.test(p), 'path contains control characters')
+    .refine((p) => {
+    // `#` is allowed only for the two synthetic entries (see canonical.ts).
+    // Everything else must be a clean relative path with no `#` and no
+    // absolute-path leading characters.
+    if (p.includes('#'))
+        return true;
+    if (/^[A-Za-z]:[\\/]/.test(p))
+        return false; // windows drive letter
+    if (p.startsWith('/') || p.startsWith('\\'))
+        return false;
+    const parts = p.split(/[\\/]/);
+    return !parts.includes('..');
+}, 'path must be relative and must not contain `..` segments');
+export const ManifestEntrySchema = z
+    .object({
+    path: ManifestPath,
+    sha256: Sha256Hex,
+    source: SourceKindSchema,
+    mode: z.number().int().nonnegative().optional(),
+})
+    .strict();
+export const InstallManifestSchema = z
+    .object({
+    version: z.string().min(1),
+    profile: z.string().min(1),
+    installed_at: z.string().min(1),
+    upgraded_at: z.string().min(1).optional(),
+    bootstrap: z.boolean().optional(),
+    files: z.array(ManifestEntrySchema),
+})
+    .strict();
+export function parseManifest(raw) {
+    return InstallManifestSchema.parse(raw);
+}
+export function serializeManifest(manifest) {
+    return JSON.stringify(manifest, null, 2) + '\n';
+}

package/dist/cli/install/reagent.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Translate a `.reagent/policy.yaml` into a `.rea/policy.yaml`-shaped payload.
+ *
+ * ## Explicit contract
+ *
+ * Reagent had a broader policy schema than rea. Most top-level fields either
+ * transfer directly (same semantics) or are dropped because their governance
+ * model changed. Dropping a security-relevant field silently would downgrade a
+ * guarantee the user already expected — that is forbidden.
+ *
+ * Fields fall into one of three lists:
+ *
+ *   - **copy list**: copy verbatim into the rea policy.
+ *   - **drop list**: SECURITY-RELEVANT fields that were removed or restructured
+ *     in rea. If any drop-list field is present in the input policy, this
+ *     function refuses to translate unless `acceptDropped === true`.
+ *   - **ignore list**: non-governance fields (metadata, project name, notes)
+ *     that are simply not written to the rea policy. No warning emitted.
+ *
+ * ## Autonomy clamping
+ *
+ * If the reagent policy's `max_autonomy_level` exceeds the chosen profile's
+ * ceiling, we clamp down to the profile ceiling and record a notice. A reagent
+ * install that allowed L3 cannot silently survive a migration into an
+ * `open-source` profile capped at L2.
+ */
+import { AutonomyLevel } from '../../policy/types.js';
+import { type Profile } from '../../policy/profiles.js';
+export interface TranslateOptions {
+    /**
+     * Upper bound on `max_autonomy_level`. Profile ceiling (typically L2).
+     * If the reagent file declares a higher ceiling, we clamp and warn.
+     */
+    profileCeiling: AutonomyLevel;
+    /** Set by `--accept-dropped-fields` on the CLI. */
+    acceptDropped: boolean;
+}
+export interface TranslateResult {
+    translated: Profile;
+    notices: string[];
+    droppedFields: string[];
+    clampedAutonomy: boolean;
+}
+export declare class ReagentDroppedFieldsError extends Error {
+    readonly dropped: string[];
+    constructor(dropped: string[]);
+}
+/**
+ * Translate the reagent policy at `reagentPath`, enforcing drop-list rules.
+ *
+ * @throws {ReagentDroppedFieldsError} if drop-list fields are present and
+ *   `acceptDropped` is false.
+ */
+export declare function translateReagentPolicy(reagentPath: string, options: TranslateOptions): TranslateResult;
+/**
+ * Resolve the default reagent policy path inside a target directory.
+ * Convenience for the CLI's `--from-reagent` flag.
+ */
+export declare function defaultReagentPath(targetDir: string): string;