dorfl 0.0.0 → 0.1.0

package/dist/apply-persist.js

@@ -0,0 +1,359 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { run } from './git.js';
+import { applyAtomic } from './sidecar-apply.js';
+import { allAnswered, appendQuestions, parseSidecar, sidecarPathFor, } from './sidecar.js';
+import { APPLY_LIFECYCLE_FOLDERS, resolveItemPathByIdentity, } from './item-path.js';
+/**
+ * The engine-owned APPLY PERSIST (prd `advance-loop`, task `advance-rung-apply`;
+ * AGENTIC apply, task `agentic-apply-retire-disposition-vocabulary`) — the half of
+ * the APPLY rung the ENGINE owns. On `classify=apply` (ALL sidecar entries
+ * answered), it applies the HUMAN's answers to the item ATOMICALLY (item body +
+ * sidecar in ONE commit, via the sidecar contract's {@link applyAtomic}), then
+ * EITHER:
+ *
+ *   - **append / re-pause** — when the apply has NEW questions to ask: append
+ *     `qN+1…`, stay `needsAnswers:true`, re-pause (the "all answered?" flips back
+ *     to false); OR
+ *   - **discharge by deletion** — when the caller decided the SOURCE should leave
+ *     by deletion (`discharge` set): `git rm` the source + sidecar in a STANDALONE
+ *     revertible commit, the reason in the commit message (git history is the
+ *     archive); OR
+ *   - **resolve fully** (the default) — clear `needsAnswers` + DELETE the sidecar
+ *     in the SAME atomic commit (the invariant `needsAnswers:false ⟺ no active
+ *     sidecar`); the item advances toward build by its normal lifecycle.
+ *
+ * **The disposition vocabulary is GONE** (task
+ * `agentic-apply-retire-disposition-vocabulary`): the apply rung no longer reads a
+ * per-entry `disposition=` token, no longer runs a most-decisive picker, and has
+ * no `keep`/`triaged:keep` resting state. A sidecar entry is BINARY (no-answer |
+ * answered); what to DO with a fully-answered OBSERVATION is decided by the
+ * AGENTIC apply decision in the advance tick (`advance.ts` `applyRung` over the
+ * shared `decide` engine), which then routes here (re-pause / discharge / via
+ * `promoteObservation` for a mint). A signal is still-open, acted-on, or deleted
+ * — there is no \"retain as resolved\" state.
+ *
+ * The work-item (task/prd) terminal MOVES (`tasks/cancelled`, `prds/dropped`) and
+ * the `needs-attention/` LIFECYCLE state are a SEPARATE lifecycle concern (a
+ * task/prd is dropped by its own lifecycle, not by a question answer) — they are
+ * NOT routed from here any more (they were the removed disposition vocabulary).
+ *
+ * It is the SIBLING of {@link import('./surface-persist.js').persistSurfacedQuestions}:
+ * that is the SURFACE rung's one-commit primitive (append-or-create + set
+ * `needsAnswers`); this is the APPLY rung's (apply answers + resolve / re-pause /
+ * discharge). Kept file-orthogonal so the rung bodies land in different tasks.
+ *
+ * **NEVER invents an answer (US #4).** The apply rung applies ONLY what the human
+ * authored — the recorded `answer:` text. It does NOT fill, guess, or author an
+ * answer; a SUBSET-answered sidecar is not even classified `apply` (the classifier
+ * NO-OPs), so this is only ever called with a fully-answered sidecar. **ALWAYS
+ * allowed (no gate)** — applying a human's answer is never gated, even with every
+ * autonomy flag off (the engine, not this module, enforces the no-gate
+ * sequencing).
+ *
+ * Like the surface persist, this is the LOCAL one-commit primitive over a working
+ * tree (the throwaway-git-repo test pattern). The `advancing` CAS lock that makes
+ * it WINNER-ONLY is held by `performAdvance` BEFORE this is called; this module
+ * does NOT race the arbiter — that is the lock's job.
+ */
+// Re-export the extracted neutral resolver so existing importers of
+// `apply-persist.ts` keep working (the resolver now LIVES in `item-path.ts`, a
+// non-hot module the sibling CLI / gc-sweep tasks import without touching this
+// rewritten file).
+export { APPLY_LIFECYCLE_FOLDERS, resolveItemPathByIdentity };
+/** Marker that opens the applied-answers record in an item body. */
+const APPLIED_HEADING = '## Applied answers';
+/**
+ * The STRUCTURAL fence the templates wrap the transient open-questions block in
+ * — an HTML-comment marker pair, mirroring the existing `<!-- dorfl-…
+ * -->` style in `sidecar.ts`. Apply's reconcile (full-resolution route only)
+ * strips everything between the OPEN and CLOSE markers (inclusive) when it folds
+ * answers in and clears `needsAnswers`, so the resolved item body reads as
+ * resolved (no leftover "these are still open" prose above `## Applied answers`).
+ *
+ * The strip is STRUCTURAL (marker-pair based), NOT a heading-text regex — the
+ * prd's D1 decision: a `## Open questions` heading match would be fragile to
+ * author wording (`## Open questions (clear needsAnswers when resolved)` vs.
+ * `## Open questions`). Items authored WITHOUT the markers are left untouched
+ * (backward compat — no marker ⇒ nothing to strip ⇒ identical bytes).
+ *
+ * The sibling task `templates-mark-transient-open-questions-block` introduces
+ * the markers in the prd/task templates; this task exports the constants so
+ * the two tasks agree on the literal byte sequence.
+ */
+export const OPEN_QUESTIONS_MARKER_OPEN = '<!-- open-questions -->';
+export const OPEN_QUESTIONS_MARKER_CLOSE = '<!-- /open-questions -->';
+/** Raised for usage errors (a missing repo, an unreadable item, a subset apply). */
+export class ApplyPersistError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ApplyPersistError';
+    }
+}
+function gitSoft(args, cwd, env) {
+    return run('git', args, cwd, { env });
+}
+function gitHard(args, cwd, env) {
+    const result = run('git', args, cwd, { env });
+    if (result.status !== 0) {
+        throw new ApplyPersistError(`git ${args.join(' ')} failed (exit ${result.status}): ${result.stderr.trim()}`);
+    }
+    return result;
+}
+function resolveBy(cwd, env) {
+    const name = gitSoft(['config', 'user.name'], cwd, env);
+    if (name.status === 0 && name.stdout.trim() !== '') {
+        return name.stdout.trim();
+    }
+    const e = env ?? process.env;
+    return e.USER ?? e.USERNAME ?? '';
+}
+/** Read the item body from the tree (committed) then the working-tree file. */
+function readItem(itemAbs, cwd, itemPath, env) {
+    const show = gitSoft(['show', `:${itemPath}`], cwd, env);
+    if (show.status === 0) {
+        return show.stdout;
+    }
+    try {
+        return readFileSync(itemAbs, 'utf8');
+    }
+    catch {
+        throw new ApplyPersistError(`cannot read item body for '${itemPath}' (the apply rung needs the item file)`);
+    }
+}
+/** Read + parse the existing sidecar (from the working file). */
+function readSidecar(cwd, item) {
+    const path = sidecarPathFor(item);
+    const abs = join(cwd, path);
+    if (!existsSync(abs)) {
+        throw new ApplyPersistError(`no sidecar at ${path} for ${item} — the apply rung needs an answered sidecar`);
+    }
+    return { model: parseSidecar(readFileSync(abs, 'utf8')), path };
+}
+/**
+ * Render the applied-answers record appended to the item body. PURELY the human's
+ * recorded answers (verbatim) under a dated heading — NEVER an invented or
+ * paraphrased answer. Append-only (a prior record stays); the body is the durable
+ * home of what the human decided.
+ */
+function appliedAnswersBlock(entries) {
+    const date = new Date().toISOString().slice(0, 10);
+    const lines = ['', `${APPLIED_HEADING} ${date}`, ''];
+    for (const entry of entries) {
+        lines.push(`### ${entry.id}: ${entry.question.trim()}`);
+        lines.push('');
+        lines.push(entry.answer.trim());
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/** Append the applied-answers record to an item body (append-only). */
+function withAppliedAnswers(body, entries) {
+    const base = body.replace(/\s*$/, '');
+    return `${base}\n${appliedAnswersBlock(entries)}`;
+}
+/**
+ * Strip ALL marker-fenced open-questions blocks from an item body — the FULL
+ * RESOLUTION reconcile step (prd `apply-reconciles-stale-open-questions`,
+ * decisions D1 / D3). Removes each `<!-- open-questions -->` … `<!--
+ * /open-questions -->` pair (markers included) plus the blank lines that
+ * flanked it, so the answers in `## Applied answers` no longer sit beneath a
+ * stale "these are still open" section.
+ *
+ * Behavioural choices (recorded in the done note):
+ *   - strips EVERY well-formed marker pair, not just the first (an authoring
+ *     template may legitimately fence more than one transient block — e.g.
+ *     open-questions plus an autonomy-note — and partial strips would re-create
+ *     the same drift the reconcile exists to prevent);
+ *   - FAIL-SAFE on a malformed fence (a lone opener with no matching closer):
+ *     the regex simply doesn't match, the body is returned unchanged. A
+ *     fail-loud throw would block the apply commit on a template authoring bug;
+ *     leaving the body intact preserves the answer-application invariant and
+ *     surfaces the stale block to a human reviewer instead;
+ *   - collapses runs of 3+ newlines down to 2 after a strip, so removing a
+ *     block doesn't leave a triple-blank gap between the surrounding paragraphs.
+ *
+ * Called ONLY from the full-resolution path. The re-pause path (follow-up
+ * questions appended, `needsAnswers` stays true) NEVER calls this — the
+ * open-questions block is still legitimately open there (D3).
+ */
+function stripOpenQuestionsBlocks(body) {
+    const escOpen = OPEN_QUESTIONS_MARKER_OPEN.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const escClose = OPEN_QUESTIONS_MARKER_CLOSE.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`\\n*[ \\t]*${escOpen}[\\s\\S]*?${escClose}[ \\t]*\\n*`, 'g');
+    if (!re.test(body))
+        return body;
+    return body.replace(re, '\n\n').replace(/\n{3,}/g, '\n\n');
+}
+/**
+ * Apply a FULLY-ANSWERED sidecar's answers to its item ATOMICALLY, then route it.
+ * The keystone APPLY rung the advance engine dispatches into once the classifier
+ * said `apply` (all entries answered) AND the `advancing` lock was won.
+ *
+ * The decision (the human's recorded intent + the caller's routing — NEVER an
+ * invention):
+ *
+ *   1. **append / re-pause** — `appendQuestions` is non-empty: append `qN+1…`,
+ *      keep `needsAnswers:true`, re-pause (one commit, body + sidecar).
+ *   2. **discharge by deletion** — `discharge` is set (the `delete-source`
+ *      verdict): `git rm` the source + sidecar in a standalone revertible commit,
+ *      the reason in the commit message.
+ *   3. **resolve fully** (the default) — clear `needsAnswers` + delete the sidecar
+ *      in ONE commit; the item advances toward build by its normal lifecycle.
+ */
+export function applyAnsweredQuestions(options) {
+    const { cwd, item, itemPath: capturedItemPath, env } = options;
+    const note = options.note ?? (() => { });
+    if (gitSoft(['rev-parse', '--git-dir'], cwd, env).status !== 0) {
+        throw new ApplyPersistError('not inside a git repository');
+    }
+    const { model, path: sidecarPath } = readSidecar(cwd, item);
+    // FOLDER-AGNOSTIC at WRITE-TIME (F3a, prd
+    // `staging-surface-and-apply-promote-safety`): re-resolve the item's CURRENT
+    // path by IDENTITY, mirroring the sidecar's already-folder-agnostic
+    // resolution. The captured `itemPath` is ADVISORY — a concurrent `promote`
+    // (`tasks/backlog → tasks/ready`, `prds/proposed → prds/ready`) may have
+    // moved the item between capture and now, and we MUST write the post-move
+    // path, never the stale one. If the item has vanished entirely, exit CLEAN
+    // (no commit, no ghost file) — the matching benign skip the surface/triage
+    // rungs already use.
+    const resolvedItemPath = resolveItemPathByIdentity(cwd, item);
+    if (resolvedItemPath === undefined) {
+        const message = `apply ${item}: item file is gone (captured '${capturedItemPath}' is ` +
+            `stale and no current path resolves by identity) — exiting clean (no ` +
+            `commit), the apply rung does not recreate a vanished item.`;
+        note(message);
+        return {
+            outcome: 'vanished',
+            sidecarPath,
+            itemPath: capturedItemPath,
+            message,
+        };
+    }
+    const itemPath = resolvedItemPath;
+    // NEVER invent an answer: the apply only ever runs on a FULLY-answered sidecar
+    // (the classifier NO-OPs a subset). Assert the boundary so a mis-call is loud,
+    // not a silent invention of an answer for an unanswered entry.
+    if (!allAnswered(model)) {
+        throw new ApplyPersistError(`refusing to apply ${item}: the sidecar has unanswered entries — a subset ` +
+            'is a classifier NO-OP, never an apply (the rung NEVER invents an answer)');
+    }
+    const itemAbs = join(cwd, itemPath);
+    const baseBody = readItem(itemAbs, cwd, itemPath, env);
+    const by = options.by || resolveBy(cwd, env);
+    // (1) APPEND / RE-PAUSE: the apply has new questions. Append them (`qN+1…`,
+    // never mutating an answered entry), stay needsAnswers:true, re-pause. Re-pause
+    // WINS over a discharge — you cannot discharge a source you are still asking
+    // about.
+    const followups = options.appendQuestions ?? [];
+    if (followups.length > 0) {
+        const repaused = appendQuestions(model, followups);
+        const result = applyAtomic({
+            cwd,
+            itemPath,
+            itemBody: withAppliedAnswers(baseBody, model.entries),
+            sidecar: repaused,
+            mode: 'repause',
+            by,
+            env,
+            note,
+        });
+        const message = `applied ${item} + appended ${followups.length} new question(s) → re-paused (needsAnswers:true).`;
+        note(message);
+        return {
+            outcome: 'repaused',
+            commit: result.commit,
+            sidecarPath,
+            itemPath,
+            message,
+        };
+    }
+    // (2) DISCHARGE BY DELETION: the caller decided the source should leave by
+    // deletion (the `delete-source` verdict). `git rm` the source + sidecar in a
+    // STANDALONE revertible commit, the reason in the commit message (git history =
+    // archive). DIRECT — no preview/confirm (decision 12); the human's answer is
+    // the source of truth.
+    if (options.discharge !== undefined) {
+        return dischargeByDeletion({
+            cwd,
+            item,
+            itemPath,
+            reason: options.discharge.reason,
+            sidecarPath,
+            by,
+            env,
+            note,
+        });
+    }
+    // (3) RESOLVE FULLY (the default): clear needsAnswers + delete the sidecar in
+    // ONE commit. Full-resolution reconcile (D1): strip the now-stale marker-fenced
+    // open-questions block(s) so the resolved body reads as resolved. Backward
+    // compatible — no marker ⇒ identical bytes. The re-pause path above is
+    // deliberately untouched (D3): its open-questions block is still open.
+    const reconciledBody = stripOpenQuestionsBlocks(baseBody);
+    const resolvedBody = withAppliedAnswers(reconciledBody, model.entries);
+    const result = applyAtomic({
+        cwd,
+        itemPath,
+        itemBody: resolvedBody,
+        sidecar: model,
+        mode: 'resolve',
+        by,
+        env,
+        note,
+    });
+    const message = `applied ${item} → resolved (needsAnswers cleared, sidecar deleted).`;
+    note(message);
+    return {
+        outcome: 'resolved',
+        commit: result.commit,
+        sidecarPath,
+        itemPath,
+        message,
+    };
+}
+/**
+ * DISCHARGE a source by DELETION (the `delete-source` verdict, US #5/#11): `git
+ * rm` the source AND its answered sidecar in ONE STANDALONE commit, the human's
+ * discharge reason recorded in the commit MESSAGE (git history is the archive).
+ * There is no spawned artifact for a discharge, so the deletion is a standalone
+ * commit (a `mint`, by contrast, rides the new artifact's create commit through
+ * `promoteObservation`).
+ *
+ * A discharged item leaves by being GONE — no resting body marker, no `triaged:`
+ * stamp (the resting-state machinery is retired; an item is still-open, acted-on,
+ * or deleted). This is the apply rung applying the human's RATIFIED answer (the
+ * deletion is human-authored), and it is git-recoverable (a single revertible
+ * commit) — a wrong inference is never catastrophic.
+ */
+function dischargeByDeletion(input) {
+    const { cwd, item, itemPath, reason, sidecarPath, by, env, note } = input;
+    // `git rm` the source. The sidecar may not exist in every path; rm it too when
+    // present, so the discharge leaves no answered-sidecar residue. Both ride ONE
+    // commit.
+    const rmPaths = [itemPath];
+    if (existsSync(join(cwd, sidecarPath))) {
+        rmPaths.push(sidecarPath);
+    }
+    gitHard(['rm', '--quiet', '--', ...rmPaths], cwd, env);
+    const reasonLine = reason.trim() === '' ? '(no reason given)' : reason.trim();
+    const subject = `advance: ${item} → deleted (by ${by})`;
+    const messageBody = `Discharged by deletion (the human's ratified answer authors it; ` +
+        `git history is the archive).\n\nreason: ${reasonLine}`;
+    gitHard(['commit', '--quiet', '-m', subject, '-m', messageBody], cwd, env);
+    const commit = gitHard(['rev-parse', 'HEAD'], cwd, env).stdout.trim();
+    const message = `applied ${item} → deleted (source git rm-ed in a standalone commit; reason ` +
+        'in the commit message, git history is the archive).';
+    note(message);
+    return {
+        outcome: 'deleted',
+        commit,
+        sidecarPath,
+        itemPath,
+        message,
+    };
+}
+// Re-export the heading constant the tests assert against, so the byte-level
+// marker stays in one place.
+export { APPLIED_HEADING };
+//# sourceMappingURL=apply-persist.js.map

package/dist/apply-persist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-persist.js","sourceRoot":"","sources":["../src/apply-persist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AACjD,OAAO,EAAC,IAAI,EAAC,MAAM,WAAW,CAAC;AAC/B,OAAO,EAAC,GAAG,EAAiB,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAC,WAAW,EAAyB,MAAM,oBAAoB,CAAC;AACvE,OAAO,EACN,WAAW,EACX,eAAe,EACf,YAAY,EACZ,cAAc,GAId,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,uBAAuB,EACvB,yBAAyB,GACzB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,oEAAoE;AACpE,+EAA+E;AAC/E,+EAA+E;AAC/E,mBAAmB;AACnB,OAAO,EAAC,uBAAuB,EAAE,yBAAyB,EAAC,CAAC;AAE5D,oEAAoE;AACpE,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,yBAAyB,CAAC;AACpE,MAAM,CAAC,MAAM,2BAA2B,GAAG,0BAA0B,CAAC;AA6EtE,oFAAoF;AACpF,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QAC1B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IACjC,CAAC;CACD;AAED,SAAS,OAAO,CACf,IAAc,EACd,GAAW,EACX,GAAkC;IAElC,OAAO,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAC,GAAG,EAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,OAAO,CACf,IAAc,EACd,GAAW,EACX,GAAkC;IAElC,MAAM,MAAM,GAAG,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAC,GAAG,EAAC,CAAC,CAAC;IAC5C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,iBAAiB,CAC1B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,iBAAiB,MAAM,CAAC,MAAM,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAC/E,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AACf,CAAC;AAED,SAAS,SAAS,CAAC,GAAW,EAAE,GAAkC;IACjE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,QAAQ,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3B,CAAC;IACD,MAAM,CAAC,GAAG,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IAC7B,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,IAAI,EAAE,CAAC;AACnC,CAAC;AAED,+EAA+E;AAC/E,SAAS,QAAQ,CAChB,OAAe,EACf,GAAW,EACX,QAAgB,EAChB,GAAkC;IAElC,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACzD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC,MAAM,CAAC;IACpB,CAAC;IACD,IAAI,CAAC;QACJ,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,iBAAiB,CAC1B,8BAA8B,QAAQ,wCAAwC,CAC9E,CAAC;IACH,CAAC;AACF,CAAC;AAED,iEAAiE;AACjE,SAAS,WAAW,CACnB,GAAW,EACX,IAAY;IAEZ,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC5B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,iBAAiB,CAC1B,iBAAiB,IAAI,QAAQ,IAAI,6CAA6C,CAC9E,CAAC;IACH,CAAC;IACD,OAAO,EAAC,KAAK,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,EAAE,IAAI,EAAC,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,SAAS,mBAAmB,CAAC,OAAuB;IACnD,MAAM,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACnD,MAAM,KAAK,GAAa,CAAC,EAAE,EAAE,GAAG,eAAe,IAAI,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC/D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,OAAO,KAAK,CAAC,EAAE,KAAK,KAAK,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACzB,CAAC;AAED,uEAAuE;AACvE,SAAS,kBAAkB,CAAC,IAAY,EAAE,OAAuB;IAChE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACtC,OAAO,GAAG,IAAI,KAAK,mBAAmB,CAAC,OAAO,CAAC,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,SAAS,wBAAwB,CAAC,IAAY;IAC7C,MAAM,OAAO,GAAG,0BAA0B,CAAC,OAAO,CACjD,qBAAqB,EACrB,MAAM,CACN,CAAC;IACF,MAAM,QAAQ,GAAG,2BAA2B,CAAC,OAAO,CACnD,qBAAqB,EACrB,MAAM,CACN,CAAC;IACF,MAAM,EAAE,GAAG,IAAI,MAAM,CACpB,cAAc,OAAO,aAAa,QAAQ,aAAa,EACvD,GAAG,CACH,CAAC;IACF,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CACrC,OAAsC;IAEtC,MAAM,EAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,gBAAgB,EAAE,GAAG,EAAC,GAAG,OAAO,CAAC;IAC7D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAExC,IAAI,OAAO,CAAC,CAAC,WAAW,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,iBAAiB,CAAC,6BAA6B,CAAC,CAAC;IAC5D,CAAC;IAED,MAAM,EAAC,KAAK,EAAE,IAAI,EAAE,WAAW,EAAC,GAAG,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAE1D,0CAA0C;IAC1C,6EAA6E;IAC7E,oEAAoE;IACpE,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,2EAA2E;IAC3E,2EAA2E;IAC3E,qBAAqB;IACrB,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC9D,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,OAAO,GACZ,SAAS,IAAI,kCAAkC,gBAAgB,OAAO;YACtE,sEAAsE;YACtE,4DAA4D,CAAC;QAC9D,IAAI,CAAC,OAAO,CAAC,CAAC;QACd,OAAO;YACN,OAAO,EAAE,UAAU;YACnB,WAAW;YACX,QAAQ,EAAE,gBAAgB;YAC1B,OAAO;SACP,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,gBAAgB,CAAC;IAElC,+EAA+E;IAC/E,+EAA+E;IAC/E,+DAA+D;IAC/D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,iBAAiB,CAC1B,qBAAqB,IAAI,kDAAkD;YAC1E,0EAA0E,CAC3E,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,IAAI,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAE7C,4EAA4E;IAC5E,gFAAgF;IAChF,6EAA6E;IAC7E,SAAS;IACT,MAAM,SAAS,GAAG,OAAO,CAAC,eAAe,IAAI,EAAE,CAAC;IAChD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACnD,MAAM,MAAM,GAAsB,WAAW,CAAC;YAC7C,GAAG;YACH,QAAQ;YACR,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC;YACrD,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,SAAS;YACf,EAAE;YACF,GAAG;YACH,IAAI;SACJ,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,WAAW,IAAI,eAAe,SAAS,CAAC,MAAM,mDAAmD,CAAC;QAClH,IAAI,CAAC,OAAO,CAAC,CAAC;QACd,OAAO;YACN,OAAO,EAAE,UAAU;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW;YACX,QAAQ;YACR,OAAO;SACP,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,6EAA6E;IAC7E,gFAAgF;IAChF,6EAA6E;IAC7E,uBAAuB;IACvB,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,OAAO,mBAAmB,CAAC;YAC1B,GAAG;YACH,IAAI;YACJ,QAAQ;YACR,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,MAAM;YAChC,WAAW;YACX,EAAE;YACF,GAAG;YACH,IAAI;SACJ,CAAC,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,gFAAgF;IAChF,2EAA2E;IAC3E,uEAAuE;IACvE,uEAAuE;IACvE,MAAM,cAAc,GAAG,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,kBAAkB,CAAC,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACvE,MAAM,MAAM,GAAG,WAAW,CAAC;QAC1B,GAAG;QACH,QAAQ;QACR,QAAQ,EAAE,YAAY;QACtB,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,SAAS;QACf,EAAE;QACF,GAAG;QACH,IAAI;KACJ,CAAC,CAAC;IACH,MAAM,OAAO,GAAG,WAAW,IAAI,sDAAsD,CAAC;IACtF,IAAI,CAAC,OAAO,CAAC,CAAC;IACd,OAAO;QACN,OAAO,EAAE,UAAU;QACnB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,WAAW;QACX,QAAQ;QACR,OAAO;KACP,CAAC;AACH,CAAC;AAcD;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAC3B,KAAqB;IAErB,MAAM,EAAC,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAC,GAAG,KAAK,CAAC;IACxE,+EAA+E;IAC/E,8EAA8E;IAC9E,UAAU;IACV,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,EAAE,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC9E,MAAM,OAAO,GAAG,YAAY,IAAI,kBAAkB,EAAE,GAAG,CAAC;IACxD,MAAM,WAAW,GAChB,kEAAkE;QAClE,2CAA2C,UAAU,EAAE,CAAC;IACzD,OAAO,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACtE,MAAM,OAAO,GACZ,WAAW,IAAI,8DAA8D;QAC7E,qDAAqD,CAAC;IACvD,IAAI,CAAC,OAAO,CAAC,CAAC;IACd,OAAO;QACN,OAAO,EAAE,SAAS;QAClB,MAAM;QACN,WAAW;QACX,QAAQ;QACR,OAAO;KACP,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,6BAA6B;AAC7B,OAAO,EAAC,eAAe,EAAC,CAAC"}

package/dist/arbiter.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The **arbiter management** primitive (ADR §7 in
+ * `docs/adr/execution-substrate-decisions.md`): provision and inspect a local
+ * `--bare` arbiter — the offline source of truth the claim/integration
+ * protocols serialize on (`scripts/CLAIM-PROTOCOL.md`).
+ *
+ * An arbiter is **precious DATA**, not state or cache: it is the very thing the
+ * deletion-safety predicate (ADR §4) proves everything else safe *against*. So:
+ *
+ *   - It is provisioned under a visible `~/git/` (config `arbitersDir`),
+ *     hierarchical (`<host>/<org>/<name>.git`), reusing the workspace repo→key
+ *     encoding (`.`→`-` per segment) — NEVER under `~/.dorfl/`, whose
+ *     `gc`/cleanup could nuke the only copy.
+ *   - It is created `git clone --bare`. A non-bare repo with `main` checked out
+ *     CANNOT be an arbiter: it rejects pushes to `main` (CLAIM-PROTOCOL), which
+ *     would silently break every claim. `init` refuses that unsafe case; `status`
+ *     flags it.
+ *
+ * This module only **provisions/locates** the arbiter (`arbiterInit` from an
+ * existing working repo, `arbiterStatus`). It does NOT claim, run, or fetch —
+ * those consume what this provides. It reuses the `repo-mirror` repo→key
+ * encoding (it does NOT duplicate it).
+ */
+/** The conventional default name for the arbiter remote in a working repo. */
+export declare const DEFAULT_ARBITER_REMOTE = "arbiter";
+/**
+ * The on-disk location of the local bare arbiter for `url`:
+ * `<arbitersDir>/<host>/<org>/<name>.git` (hierarchical, reusing the
+ * `repo-mirror` repo→key encoding, with a `.git` suffix). Lives under
+ * `arbitersDir` (default `~/git`), NEVER `~/.dorfl` (ADR §7).
+ */
+export declare function arbiterPath(arbitersDir: string, url: string): string;
+export interface ArbiterInitOptions {
+    /**
+     * The working repo to derive the arbiter FROM (its current contents seed the
+     * bare clone, and its `<remote>` is wired to point at it). Defaults to `cwd`.
+     */
+    repo?: string;
+    /** Working directory `repo` defaults to when omitted. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Override the resolved default path (`<arbitersDir>/<key>.git`) with an
+     * explicit location (`--at`). Still created `--bare`.
+     */
+    at?: string;
+    /** Where to provision the arbiter (config `arbitersDir`, default `~/git`). */
+    arbitersDir?: string;
+    /** Name of the remote to wire in `repo` (`--remote`). Default `arbiter`. */
+    remote?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Sink for human-readable progress notes. */
+    note?: (message: string) => void;
+}
+export interface ArbiterInitResult {
+    /** Absolute path to the (existing or just-created) bare arbiter. */
+    path: string;
+    /** The `file://` URL the repo's remote was wired to. */
+    url: string;
+    /** The remote name wired in the working repo. */
+    remote: string;
+    /** True iff the arbiter did not exist and was just `clone --bare`d. */
+    created: boolean;
+    /** True iff an arbiter already existed at the path (idempotent no-clobber). */
+    alreadyExisted: boolean;
+    /** True iff the arbiter is bare (always true on success — invariant). */
+    bare: boolean;
+}
+/** Raised when `init` cannot safely provision/locate an arbiter. */
+export declare class ArbiterError extends Error {
+}
+/**
+ * Provision (or locate) a local bare arbiter from a working repo and wire the
+ * repo's `<remote>` to it. Idempotent: an existing arbiter is detected and NOT
+ * clobbered (it is only re-pointed by the remote, never re-cloned). Refuses the
+ * unsafe case where the target is a non-bare repo with `main` checked out (which
+ * would reject claim pushes — CLAIM-PROTOCOL).
+ *
+ * The default path is hierarchical under `arbitersDir` (`~/git`), NEVER under
+ * `~/.dorfl` (ADR §7) — overridable via `at`.
+ */
+export declare function arbiterInit(options: ArbiterInitOptions): ArbiterInitResult;
+export interface ArbiterStatusOptions {
+    /** The working repo to inspect. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** The arbiter remote name to report on. Default `arbiter`. */
+    remote?: string;
+    env?: NodeJS.ProcessEnv;
+}
+export interface ArbiterStatusReport {
+    /** The remote name inspected. */
+    remote: string;
+    /** True iff the working repo has a remote with that name. */
+    configured: boolean;
+    /** The remote's URL, if configured. */
+    url?: string;
+    /** The local filesystem path the URL resolves to (for `file://` / local URLs). */
+    path?: string;
+    /** True iff a git repo exists at `path` (or the URL is reachable locally). */
+    exists: boolean;
+    /** True iff the arbiter is a bare repo (the safe shape). */
+    bare: boolean;
+    /** True iff `main` is reachable on the arbiter. */
+    mainReachable: boolean;
+    /**
+     * True iff the arbiter is in the unsafe non-bare-with-main shape: it EXISTS
+     * but is not bare (CLAIM-PROTOCOL warns this rejects claim pushes).
+     */
+    unsafe: boolean;
+}
+/**
+ * Read-only report of the current repo's arbiter: which remote it is, its
+ * URL/path, whether it exists and is bare, and whether `main` is reachable. It
+ * MUTATES NOTHING (no fetch, no checkout) — it reads the local remote config and
+ * inspects the arbiter repo in place. Flags the unsafe non-bare-with-main case
+ * (ADR §7 / CLAIM-PROTOCOL).
+ */
+export declare function arbiterStatus(options: ArbiterStatusOptions): ArbiterStatusReport;
+/** Render an `arbiter status` report for the terminal. */
+export declare function formatArbiterStatus(report: ArbiterStatusReport): string;
+//# sourceMappingURL=arbiter.d.ts.map

package/dist/arbiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arbiter.d.ts","sourceRoot":"","sources":["../src/arbiter.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,MAAM,WAAW,kBAAkB;IAClC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IACjC,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,OAAO,EAAE,OAAO,CAAC;IACjB,+EAA+E;IAC/E,cAAc,EAAE,OAAO,CAAC;IACxB,yEAAyE;IACzE,IAAI,EAAE,OAAO,CAAC;CACd;AAED,oEAAoE;AACpE,qBAAa,YAAa,SAAQ,KAAK;CAAG;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,iBAAiB,CAkD1E;AAED,MAAM,WAAW,oBAAoB;IACpC,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IACnC,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,UAAU,EAAE,OAAO,CAAC;IACpB,uCAAuC;IACvC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,EAAE,OAAO,CAAC;IAChB,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;IACd,mDAAmD;IACnD,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,MAAM,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,oBAAoB,GAC3B,mBAAmB,CAiErB;AAED,0DAA0D;AAC1D,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CA2CvE"}