@holmes-lab/holmes-kit 0.19.6 → 0.20.1

package/dist/holmes/mcp/handlers/spec-authoring.d.ts

@@ -0,0 +1,57 @@
+import { SpecStore } from '../../spec/spec-store';
+import { Spec } from '../../spec/spec-parser';
+export interface SpecAuthoringContext {
+    store: SpecStore;
+    projectRootOf(root: string): string;
+    resolver(specs: Spec[]): (id: string) => Spec | null;
+}
+export declare function createSpecAuthoringHandlers(context: SpecAuthoringContext): {
+    spec_create(a: any): Promise<{
+        ok: boolean;
+        reason: string;
+        created?: undefined;
+    } | {
+        created: any;
+        ok?: undefined;
+        reason?: undefined;
+    }>;
+    /**
+     * @implements A-SPEC-184
+     * Raise ONE named document from an older spec format to the current one.
+     *
+     * The compatibility policy this implements: older documents are read and left alone by default,
+     * and rise only when a human points at the one they intend to use. There is deliberately no bulk
+     * path — 155 documents here and 90 in the measured adoption target, and which of them are still
+     * live specifications is a judgement only a person holds.
+     *
+     * It declares a KIND. It does not confer approval: 37 of this repository's legacy documents read
+     * `status: Approved`, and carrying that across would mint approvals that never passed the sealing
+     * act. The old value is preserved as evidence and the document restarts at `draft`.
+     *
+     * Takes no `root`: the store is bound at server construction, exactly as `spec_create` is.
+     */
+    spec_upgrade(a: {
+        id: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        upgraded?: undefined;
+        type?: undefined;
+        legacyStatus?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        upgraded: boolean;
+        reason: string;
+        type?: undefined;
+        legacyStatus?: undefined;
+        remaining?: undefined;
+    } | {
+        ok: boolean;
+        upgraded: boolean;
+        type: import("../../spec/spec-types").SpecType;
+        legacyStatus: string;
+        remaining: import("../../spec/validator").Finding[];
+        reason?: undefined;
+    }>;
+};

package/dist/holmes/mcp/handlers/spec-authoring.js

@@ -0,0 +1,326 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSpecAuthoringHandlers = createSpecAuthoringHandlers;
+// @implements A-SPEC-618, A-SPEC-100.2, A-SPEC-128, A-SPEC-151, A-SPEC-169, A-SPEC-189, A-SPEC-420, A-SPEC-174, A-SPEC-252, A-SPEC-188, A-SPEC-146, A-SPEC-184
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const spec_store_1 = require("../../spec/spec-store");
+const validator_1 = require("../../spec/validator");
+const spec_types_1 = require("../../spec/spec-types");
+const legacy_format_1 = require("../../spec/legacy-format");
+const write_target_1 = require("../../guardrail/write-target");
+const spec_id_guard_1 = require("../spec-id-guard");
+function createSpecAuthoringHandlers(context) {
+    const { store, projectRootOf, resolver } = context;
+    return {
+        async spec_create(a) {
+            // @implements A-SPEC-169
+            // `root` is a CONTROL argument. Without excluding it, the catch-all below stores it as
+            // frontmatter and a machine-local absolute path lands in a git-shared document. A blacklist,
+            // not a whitelist: domain fields (`priority`, `slice`, …) must keep flowing through without
+            // anyone maintaining a list of them.
+            const { type, id, title, depends_on = [], root: reqRoot, ...extra } = a;
+            // The server binds its spec store once, so a `root` naming another project cannot be honoured.
+            // Silently writing to this one is a data-integrity problem; refusing says so. Compared by
+            // resolved identity (A-SPEC-163) — `<root>//.` is the same directory, not a different project.
+            // @implements A-SPEC-189 §9 (round 11) — the question is "same PROJECT?", and this asked "does
+            // `<root>/.ax/specs` equal the bound store?" — the default layout hardcoded. On the first-class
+            // `--specs-dir docs/specs` deployment no root could ever satisfy it: measured, the project's own
+            // root was refused as another project's, so `spec_create` was unusable there. `spec_approve`
+            // learned this in round 3 and compares at project level; this is the same comparison.
+            // @implements A-SPEC-189 §16 (round 13) — the siblings all ask "did the derivation actually
+            // FIND a marker?" before speaking for a project (spec_approve, phase_status,
+            // foreignRootReason). Without it, a store whose derivation lands on itself (an absolute
+            // `--specs-dir` outside any `.ax` tree) calls itself the bound project and refuses the
+            // project's real root — the inverse defect rounds 3/9/11 fixed elsewhere.
+            // 파생은 이 분기 안에서만, 그리고 실패는 '표지를 못 찾았다'로 읽는다 — 스펙 트리를 이제
+            // 만들려는 참이라 스토어 경로가 아직 없을 수 있고, 그것이 예외가 되어선 안 된다.
+            const boundSpecsRoot = store instanceof spec_store_1.LocalMarkdownRepository ? store.specsRoot : null;
+            const derivedForCreate = (() => {
+                if (boundSpecsRoot === null)
+                    return null;
+                try {
+                    const d = projectRootOf(boundSpecsRoot);
+                    return fs.existsSync(path.join(d, '.ax')) ? d : null;
+                }
+                catch {
+                    return null;
+                }
+            })();
+            if (typeof reqRoot === 'string' && reqRoot !== '' && derivedForCreate !== null) {
+                const asked = (0, write_target_1.resolveTarget)(projectRootOf(reqRoot), '.');
+                const bound = (0, write_target_1.resolveTarget)(derivedForCreate, '.');
+                if (asked !== bound) {
+                    return {
+                        ok: false,
+                        // A-SPEC-169: 두 경로를 모두 이름한다 — 어느 저장소가 묶여 있는지 호출자가 보아야 한다.
+                        reason: `이 서버는 ${bound} 프로젝트(스펙 저장소 ${boundSpecsRoot})에 바인딩되어 있습니다`
+                            + ` — 요청한 root ${reqRoot}는 ${asked}를 가리킵니다.`
+                            + ' 다른 프로젝트를 조용히 수정하지 않기 위해 거부합니다.',
+                    };
+                }
+            }
+            // @implements A-SPEC-420
+            // The branch above steps aside when the server's spec directory does not exist yet, so that a
+            // project can create its first spec. Right intent, but the gap let something else through:
+            // measured against the INSTALLED server from a cwd outside any project, `spec_create` with
+            // `root` naming an established other project wrote REQ-990 into the SERVER's directory and
+            // answered `{"created":"REQ-990"}`. The caller's project gained nothing and was told it had.
+            //
+            // Layout-independent on purpose: the test is not "<root>/.ax/specs equals my store" — that
+            // hardcodes the default layout and, as the note above records, made `--specs-dir docs/specs`
+            // deployments refuse their own root. It is "you named a project that already exists, and my
+            // store is not inside it", which is true whatever the specs directory is called.
+            if (typeof reqRoot === 'string' && reqRoot !== '' && derivedForCreate === null && boundSpecsRoot !== null) {
+                const real = (p2) => { try {
+                    return fs.realpathSync(p2);
+                }
+                catch {
+                    return path.resolve(p2);
+                } };
+                let askedRoot = null;
+                try {
+                    askedRoot = real(projectRootOf(reqRoot));
+                }
+                catch {
+                    askedRoot = null;
+                }
+                if (askedRoot !== null && fs.existsSync(path.join(askedRoot, '.ax'))
+                    && !real(boundSpecsRoot).startsWith(askedRoot + path.sep)) {
+                    return {
+                        ok: false,
+                        reason: `이 서버의 스펙 저장소 ${boundSpecsRoot} 는 아직 만들어지지 않았고 ${askedRoot} 안에도`
+                            + ' 있지 않습니다 — 요청한 root 는 이미 스펙 저장소를 가진 다른 프로젝트입니다.'
+                            + ' 여기서 만들면 파일은 호출자가 지정한 곳이 아니라 이 서버 쪽에 생깁니다.'
+                            + ' 서버를 그 프로젝트에서 시작하거나 HOLMES_SPECS 로 그 프로젝트의 스펙 경로를 지정하십시오.',
+                    };
+                }
+            }
+            // @implements A-SPEC-174
+            // Refuse what can never become valid; accept what is merely not filled in yet.
+            //
+            // Measured 2026-08-12 against the installed server: `REQ-7`, `hello`, `A-SPEC-7.1` and four
+            // more were all created and are all refused at approval on `bad-id`. The id IS the filename,
+            // so the author's only repair is to delete the spec and start over — after writing the body.
+            // The stubs below are the opposite case: they are placeholders BY DESIGN, and blocking
+            // approval until someone answers them is what they are for (A-SPEC-146).
+            //
+            // Every judgement here quotes SPEC_TYPES, which is what approval reads. A second statement of
+            // the rule drifts, and the drift is either this defect again or its worse inverse — refused
+            // at creation, accepted at approval.
+            const def = spec_types_1.SPEC_TYPES[type];
+            if (!def) {
+                return { ok: false, reason: `알 수 없는 스펙 타입 "${String(type)}" — 유효한 타입: ${spec_types_1.SPEC_ORDER.join(', ')}` };
+            }
+            if (!def.idRegex.test(String(id))) {
+                return {
+                    ok: false,
+                    reason: `id "${String(id)}"는 ${def.type}의 형식 ${def.idRegex}에 맞지 않습니다 — 예: ${def.example}.`
+                        + ' 승인 시점에 거부될 값이므로 지금 거부합니다(id는 파일명이라 나중에 고칠 수 없습니다).',
+                };
+            }
+            for (const pid of depends_on) {
+                // The parent is judged WITHOUT resolving it: not existing yet is a legitimate state an
+                // author reaches by creating the child first. A wrong type is wrong forever.
+                const ptype = (0, spec_types_1.specTypeOfId)(String(pid));
+                if (ptype === null) {
+                    return { ok: false, reason: `depends_on "${String(pid)}"는 어떤 스펙 타입의 id 형식에도 맞지 않습니다 — 그 id를 가진 스펙은 존재할 수 없습니다.` };
+                }
+                if (!def.parents.includes(ptype)) {
+                    return { ok: false, reason: `depends_on "${String(pid)}"는 ${ptype}입니다 — ${def.type}의 부모는 ${def.parents.join('|') || '없음(빈 depends_on)'}이어야 합니다.` };
+                }
+            }
+            // @implements A-SPEC-252
+            // A new id may not LEAP past the sequence. spec_slice_init assigns nextId = max(base)+1, which
+            // is only predictable while numbering stays sequential; a hand-picked wild id (REQ-1403) once
+            // dragged max to 1403 and every slice after jumped to 1404. Refused here, at the one door that
+            // lets a manual id in — so max+1 can never be poisoned again. After the shape check on purpose:
+            // an id whose base cannot be read is the shape check's to name, not this guard's.
+            const corpus = await store.list();
+            const seq = (0, spec_id_guard_1.sequentialIdVerdict)(String(id), corpus.map((s) => s.id));
+            if (!seq.ok)
+                return { ok: false, reason: seq.reason };
+            // @implements A-SPEC-188
+            // Creation creates. Probed before this check existed: spec_create over an approved+sealed
+            // REQ returned {"created"} while the disk went draft / seal gone / prose gone — the sanctioned
+            // door destroying what risk_check guards every shell path against. Checked AFTER the format
+            // refusals on purpose: a malformed id must keep its own message (order is pinned by test).
+            // Legacy (typeless) documents count as existing too — overwriting one makes the store's
+            // orphan removal delete the differently-named original file along with its history.
+            const existing = corpus.find((s) => s.id === id);
+            if (existing) {
+                const sealed = existing.status === 'approved' || Boolean(existing.frontmatter?.approved_digest);
+                const kind = existing.type ? `${existing.type} (status: ${existing.status})` : `옛 형식 문서 (status: ${existing.status})`;
+                return {
+                    ok: false,
+                    reason: `${id}은(는) 이미 존재합니다 — ${kind}. `
+                        + (sealed
+                            ? '봉인(approved)된 문서이므로, 내용을 바꾸려면 파일을 편집한 뒤 spec_approve로 재봉인하십시오. '
+                            : '그 문서를 고치려는 것이면 파일을 직접 편집하십시오. ')
+                        + '새 문서를 만들려는 것이면 다른 id를 쓰십시오. 생성은 아무것도 덮어쓰지 않습니다.',
+                };
+            }
+            const sections = Object.fromEntries(def.requiredSections.map((s) => [s, spec_types_1.FIELD_PLACEHOLDER]));
+            // Stub the required FRONTMATTER too, not just the sections. Without this every created spec
+            // fails the project's own `spec_validate` on `missing-field` the moment it is written, and
+            // the author has to rediscover the per-type field list by reading spec-types.ts. Caller-
+            // supplied values win; `coverage` needs a shaped default because T-SPEC reads its keys.
+            // `source` is a citation LIST, so a bare 'TODO' string would fail the shape check the moment
+            // the spec is written. The stub is validly shaped but obviously unfilled: it validates while
+            // the REQ is drafted and blocks approval until a real origin replaces the placeholder.
+            const stub = (f) => {
+                if (f === 'coverage')
+                    return { normal: false, corner: false, negative: false, boundary: false };
+                if (f === 'source')
+                    return [{ kind: 'other', ref: spec_types_1.CITATION_PLACEHOLDER, note: 'cite the real origin before approval' }];
+                return spec_types_1.FIELD_PLACEHOLDER;
+            };
+            const required = Object.fromEntries(def.requiredFields.filter((f) => !(f in extra)).map((f) => [f, stub(f)]));
+            // @implements A-SPEC-146
+            // Scaffolded but not required by `validateSpec` — see SpecTypeDef.stubOnlyFields for why the
+            // gap exists. The stub value is `TODO`, which is NOT an accepted grade, so the field is
+            // visible to the author while the approval still refuses until it is actually answered.
+            // Pre-filling `none` would be easier and would make the formulaic answer the default, which is
+            // exactly what ADR-013 recorded as its revisit trigger.
+            const stubOnly = Object.fromEntries((def.stubOnlyFields ?? []).filter((f) => !(f in extra)).map((f) => [f, stub(f)]));
+            const spec = { id, type, title, status: 'draft', dependsOn: depends_on, frontmatter: { ...required, ...stubOnly, ...extra }, sections };
+            // @implements A-SPEC-188 — existence is a PATH question, not only a list() question.
+            // Round-2 review probed the gap: list() drops unparseable files, so a prose note or
+            // broken-YAML document sitting at the exact target path was invisible to the id check above
+            // and got silently overwritten — with the refusal text elsewhere promising the opposite.
+            // A file the store cannot read as this id is a file a human must look at first.
+            if (store instanceof spec_store_1.LocalMarkdownRepository) {
+                const target = store.targetPathFor(spec);
+                if (fs.existsSync(target)) {
+                    return {
+                        ok: false,
+                        reason: `${id}의 목적지(${target})에 파일이 이미 있는데 스토어가 이 id의 스펙으로 읽지 못합니다`
+                            + ' — 손으로 쓰던 초안이거나 깨진 문서일 수 있습니다. 사람이 확인해 옮기거나 고치기 전까지 덮어쓰지 않습니다'
+                            + ' (doctor가 읽을 수 없는 스펙 파일을 보고합니다).',
+                    };
+                }
+            }
+            try {
+                await store.write(spec);
+            }
+            catch (e) {
+                // The pre-write path check above makes this a narrow race backstop; the store guard is the
+                // authority and this act relays it in the same wording the other writers use.
+                if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                    return {
+                        ok: false,
+                        reason: `${id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
+                            + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오.',
+                    };
+                }
+                throw e;
+            }
+            return { created: id };
+        },
+        /**
+         * @implements A-SPEC-184
+         * Raise ONE named document from an older spec format to the current one.
+         *
+         * The compatibility policy this implements: older documents are read and left alone by default,
+         * and rise only when a human points at the one they intend to use. There is deliberately no bulk
+         * path — 155 documents here and 90 in the measured adoption target, and which of them are still
+         * live specifications is a judgement only a person holds.
+         *
+         * It declares a KIND. It does not confer approval: 37 of this repository's legacy documents read
+         * `status: Approved`, and carrying that across would mint approvals that never passed the sealing
+         * act. The old value is preserved as evidence and the document restarts at `draft`.
+         *
+         * Takes no `root`: the store is bound at server construction, exactly as `spec_create` is.
+         */
+        async spec_upgrade(a) {
+            // @implements A-SPEC-188 — same read-then-write shape as spec_approve, so the same window
+            // AND the same duplicate hazard: read() resolves the last-walked copy, and the write's orphan
+            // removal would delete the other. Refuse rather than pick a side.
+            if ((await store.list()).filter((s) => s.id === a.id).length > 1) {
+                return {
+                    ok: false,
+                    reason: `${a.id}이(가) 스토어에 두 번 이상 존재합니다 — 어느 사본이 진본인지 도구가 고를 수 없어 보강 전에 거부합니다.`
+                        + ' doctor로 중복 파일을 확인해 하나로 정리한 뒤 다시 시도하십시오.',
+                };
+            }
+            const cur = await store.read(a.id);
+            if (!cur)
+                return { ok: false, reason: `spec ${a.id} not found` };
+            const spec = cur.spec;
+            const plan = (0, legacy_format_1.upgradePlan)(spec);
+            if (!plan) {
+                const why = (0, legacy_format_1.legacyMessage)(spec);
+                // No plan for two opposite reasons. Already current is success and writes nothing — a second
+                // run must not churn the file. An unsupported kind is a refusal, and its wording must not
+                // send the holder after a type that does not exist.
+                return why ? { ok: false, reason: why } : { ok: true, upgraded: false, reason: `${a.id}은(는) 이미 현행 양식입니다` };
+            }
+            const upgraded = {
+                ...spec,
+                type: plan.type,
+                status: 'draft',
+                frontmatter: (0, legacy_format_1.upgradedFrontmatter)(spec, plan),
+            };
+            try {
+                await store.write(upgraded, { expectedVersion: cur.version });
+            }
+            catch (e) {
+                if (e instanceof spec_store_1.SpecVersionConflictError) {
+                    return {
+                        ok: false,
+                        reason: `보강 진행 중 ${a.id}이(가) 바뀌었습니다 — 바뀐 내용을 확인하고 다시 시도하십시오.`
+                            + ' 이번 보강은 아무것도 쓰지 않았습니다.',
+                    };
+                }
+                // @implements A-SPEC-188 — the upgrade RELOCATES by design (legacy filename → canonical),
+                // so an unreadable file at the canonical path is the store's occupied-target refusal.
+                if (e instanceof spec_store_1.TargetPathOccupiedError) {
+                    return {
+                        ok: false,
+                        reason: `${a.id}의 목적지(${e.occupiedPath})에 스토어가 읽지 못하는 파일이 이미 있습니다 — 덮어쓰지 않습니다.`
+                            + ' 사람이 확인해 옮기거나 고친 뒤 다시 시도하십시오. 이번 보강은 아무것도 쓰지 않았습니다.',
+                    };
+                }
+                throw e;
+            }
+            // Report what still stands between this document and approval. Silence would read as "done",
+            // and a legacy document typically lacks most required sections.
+            const after = await store.list();
+            const remaining = (0, validator_1.validateSpec)(upgraded, resolver(after)).findings.filter((f) => f.level === 'error');
+            return { ok: true, upgraded: true, type: plan.type, legacyStatus: plan.legacyStatus, remaining };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts

@@ -0,0 +1,122 @@
+import { SpecStore } from '../../spec/spec-store';
+import { Approval } from '../../guardrail/risk-gate';
+export interface SpecLifecycleContext {
+    store: SpecStore;
+    resolveLedgerRoot(root?: string): {
+        ok: true;
+        root: string;
+    } | {
+        ok: false;
+        reason: string;
+    };
+    resolveHandlerApproval(root: string | undefined, approval: Approval | undefined, action: {
+        kind: string;
+        target: string;
+    }, now: string): {
+        approval: Approval;
+        source: 'env' | 'grant';
+        root?: string;
+    } | undefined;
+    refusalQueueHint(root: string | undefined, request: {
+        kind: string;
+        target: string;
+        why: string;
+    }): string;
+}
+export declare function createSpecLifecycleHandlers(context: SpecLifecycleContext): {
+    /**
+     * Move a document to `outdated` — the only path there.
+     *
+     * @implements A-SPEC-222
+     * `outdated` was in SPEC_STATUSES with no code writing it and no document carrying it: a
+     * declared state nothing could reach. That mattered the moment 23 deprecated REQs needed
+     * cleaning up, because the only transition tool sends everything to `draft`, and calling a
+     * retired document "draft" is a worse lie than the non-canonical word it replaced.
+     *
+     * Retirement withdraws authority rather than granting it, so it does NOT need the approval key
+     * by default. Two cases invert that, and the threshold follows the RISK rather than the name of
+     * the act:
+     *
+     *  - A sealed document. The code gate demands an approved T-SPEC naming the target A-SPEC;
+     *    retiring that T-SPEC removes the demand. Unguarded, retirement is an approval bypass.
+     *  - A document an APPROVED spec depends on. That chain is holding something up right now.
+     */
+    spec_retire(a: {
+        root?: string;
+        id: string;
+        reason?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        retired?: undefined;
+        id?: undefined;
+        dependents?: undefined;
+    } | {
+        ok: boolean;
+        retired: boolean;
+        id: string;
+        dependents: never[];
+        reason: string;
+    } | {
+        ok: boolean;
+        retired: boolean;
+        id: string;
+        dependents: string[];
+        reason?: undefined;
+    }>;
+    spec_renumber(a: {
+        root?: string;
+        oldBase: string;
+        newBase: string;
+        dryRun?: boolean;
+    }): Promise<{
+        ok: boolean;
+        dryRun: boolean;
+        plan: import("../../spec/renumber").RenumberPlan;
+        reason?: undefined;
+        movedSpecs?: undefined;
+    } | {
+        ok: boolean;
+        dryRun: boolean;
+        movedSpecs: number;
+        plan: import("../../spec/renumber").RenumberPlan;
+        reason?: undefined;
+    } | {
+        ok: boolean;
+        reason: string;
+    }>;
+    /**
+     * @implements A-SPEC-538.1
+     * The inverse of spec_approve: returns a SEALED (approved) spec to an editable `draft`, clearing
+     * `approved_digest` and `parent_digests` in ONE act, and records `spec-unsealed`. Hand-editing
+     * only `status` leaves seal residue that later trips validation; this atomizes the reverse.
+     *
+     * Un-sealing WITHDRAWS a seal, so — like retiring a sealed document — it demands a covering
+     * out-of-band HOLMES_APPROVAL (fail-closed): un-sealing an approved T-SPEC removes the code
+     * gate's demand, so an unguarded un-seal would be an approval bypass. And it refuses when an
+     * APPROVED spec depends on the target, because that dependent's `parent_digests` — the snapshot
+     * drift detection compares against — would silently go stale.
+     */
+    spec_unseal(a: {
+        root?: string;
+        id: string;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        unsealed?: undefined;
+        id?: undefined;
+        dependents?: undefined;
+    } | {
+        ok: boolean;
+        unsealed: boolean;
+        id: string;
+        dependents: never[];
+        reason: string;
+    } | {
+        ok: boolean;
+        unsealed: boolean;
+        id: string;
+        dependents: string[];
+        reason?: undefined;
+    }>;
+};