@aperant/framework 0.19.0 → 0.20.0

package/dist/cli/features/reconcile.d.mts

@@ -0,0 +1,236 @@
+/** The exact repair command surfaced in every coverage failure. */
+export function draftRepairCommand(taskId: any): string;
+/**
+ * Resolve the diff base COMMIT. An explicit ref is normalized through
+ * `git merge-base HEAD <ref>` — NOT used verbatim — for two reasons:
+ *   (1) the ship gate / apt-ship pass a base BRANCH (`base_branch: 'main'`);
+ *       once main advances past the fork point, `git diff main..HEAD`
+ *       compares SNAPSHOTS and reports main-side changes reversed (phantom
+ *       modifications/deletions the task never made) → false-red coverage
+ *       findings on every stale branch. merge-base pins the fork point.
+ *   (2) a garbage/unresolvable ref previously flowed into diffNameStatus,
+ *       whose catch returned [] — an EMPTY diff → clause (a) vacuously green
+ *       (fail-open). merge-base fails → null → callers fail CLOSED.
+ * merge-base(HEAD, X) === X whenever X is already an ancestor of HEAD, so the
+ * CI workflow's precomputed merge-base and sha-based callers are byte-identical.
+ * No explicit ref → merge-base HEAD origin/main (local main fallback).
+ */
+export function resolveBase(root: any, baseFlag: any): string | null;
+/** Parse `git diff --name-status -z base..HEAD` preserving rename pairs. */
+export function diffNameStatus(root: any, base: any): ({
+    status: string;
+    from: string;
+    to: string;
+    path?: undefined;
+} | {
+    status: string;
+    path: string;
+    from?: undefined;
+    to?: undefined;
+})[];
+/**
+ * Structural receipt validator (N1): clause (a) coverage and clause (c)
+ * integrity TRUST receipt contents, so a malformed receipt must be EXCLUDED
+ * from trust rather than silently consumed.
+ */
+export function validateReceiptShape(data: any): boolean;
+/**
+ * Scaffold (or idempotently re-scaffold) a per-writer delta from
+ * `git diff --name-status <base>..HEAD`.
+ *
+ * - renames preserved (`change: "renamed"` + previous_path/previous_blob_sha)
+ * - deletions pre-filled `remove` with the BASE blob fingerprint
+ * - additions pre-filled `upsert` + a minimal upsert operation
+ * - modifications marked `needs-disposition` (draft-only sentinel)
+ * - re-runs refresh fingerprints but PRESERVE agent-authored dispositions,
+ *   areas, reasons, and all operations[].
+ *
+ * @param {{root: string, base?: string, taskId?: string, subtaskId?: string, dryRun?: boolean}} opts
+ * @returns {{ ok: boolean, deltaPath?: string, delta?: Record<string, any>, wrote?: boolean,
+ *             qualifying?: number, base?: string, error?: string }}
+ */
+export function draftDelta({ root: rootIn, base: baseFlag, taskId, subtaskId, dryRun }: {
+    root: string;
+    base?: string;
+    taskId?: string;
+    subtaskId?: string;
+    dryRun?: boolean;
+}): {
+    ok: boolean;
+    deltaPath?: string;
+    delta?: Record<string, any>;
+    wrote?: boolean;
+    qualifying?: number;
+    base?: string;
+    error?: string;
+};
+/**
+ * materialize — the single ordered idempotent writer (ID-03 / AC5):
+ *   (1) parse all deltas → (2) post-images in memory → (3) validate every
+ *   post-image → (4) atomic tmp+rename area replace → (5) write receipt →
+ *   (6) delete ONLY consumed deltas → (7) regenerate REGISTRY.md wholly from
+ *   the JSONs.
+ *
+ * Crash-after-receipt recovery: a re-run detects deltas whose sha256 appears
+ * in an in-tree receipt's consumed_delta_hashes with matching area_hashes and
+ * completes the cleanup without rewriting.
+ *
+ * @returns envelope-ready object; never throws for expected failure classes.
+ */
+export function materialize({ root: rootIn, taskId, now }: {
+    root: any;
+    taskId: any;
+    now?: Date | undefined;
+}): {
+    status: string;
+    reason: string;
+    policy: string;
+    kind?: undefined;
+    invalid?: undefined;
+    repair?: undefined;
+    materialized?: undefined;
+    receipt?: undefined;
+    consumed_deltas?: undefined;
+    cleaned_up?: undefined;
+    registry_regenerated?: undefined;
+    changed_paths?: undefined;
+    conflicts?: undefined;
+    areas?: undefined;
+} | {
+    status: string;
+    kind: string;
+    invalid: {
+        path: any;
+        errors: string[];
+    }[];
+    repair: string;
+    reason?: undefined;
+    policy?: undefined;
+    materialized?: undefined;
+    receipt?: undefined;
+    consumed_deltas?: undefined;
+    cleaned_up?: undefined;
+    registry_regenerated?: undefined;
+    changed_paths?: undefined;
+    conflicts?: undefined;
+    areas?: undefined;
+} | {
+    status: string;
+    materialized: number;
+    receipt: null;
+    consumed_deltas: never[];
+    cleaned_up: any[];
+    registry_regenerated: boolean;
+    changed_paths: any[];
+    reason?: undefined;
+    policy?: undefined;
+    kind?: undefined;
+    invalid?: undefined;
+    repair?: undefined;
+    conflicts?: undefined;
+    areas?: undefined;
+} | {
+    status: string;
+    kind: string;
+    conflicts: {
+        kind: string;
+        message: string;
+        sources: any[];
+    }[];
+    repair: string;
+    reason?: undefined;
+    policy?: undefined;
+    invalid?: undefined;
+    materialized?: undefined;
+    receipt?: undefined;
+    consumed_deltas?: undefined;
+    cleaned_up?: undefined;
+    registry_regenerated?: undefined;
+    changed_paths?: undefined;
+    areas?: undefined;
+} | {
+    status: string;
+    kind: string;
+    invalid: {
+        area: any;
+        errors: string[];
+    }[];
+    reason?: undefined;
+    policy?: undefined;
+    repair?: undefined;
+    materialized?: undefined;
+    receipt?: undefined;
+    consumed_deltas?: undefined;
+    cleaned_up?: undefined;
+    registry_regenerated?: undefined;
+    changed_paths?: undefined;
+    conflicts?: undefined;
+    areas?: undefined;
+} | {
+    status: string;
+    materialized: number;
+    areas: any[];
+    receipt: any;
+    consumed_deltas: any[];
+    cleaned_up: any[];
+    registry_regenerated: boolean;
+    changed_paths: any[];
+    reason?: undefined;
+    policy?: undefined;
+    kind?: undefined;
+    invalid?: undefined;
+    repair?: undefined;
+    conflicts?: undefined;
+};
+/**
+ * Regenerate REGISTRY.md WHOLLY from the area JSONs (never patched in place).
+ * Non-conforming files are listed loudly — never silently skipped.
+ *
+ * @returns {{ path: string, changed: boolean }} — `changed:false` when the
+ *   regeneration was content-identical (timestamp line ignored) and the
+ *   existing file was kept byte-for-byte (N2).
+ */
+export function regenerateRegistryMd(root: any, now?: Date): {
+    path: string;
+    changed: boolean;
+};
+/**
+ * checkReconciled — four read-only clauses (AC7/AC8). Judges ONLY base..HEAD
+ * deltas — never absolute registry completeness. Trust = in-tree presence +
+ * blob-fingerprint matching (squash-safe; NO git ancestry calls anywhere).
+ *
+ * @returns {Record<string, any>} envelope-ready result: status ('ok'|'fail'|
+ *   'warn'|'skip'), findings[], coverage_ok, schema_valid, integrity_ok,
+ *   orphans_ok, base, qualifying_files, pending_deltas, receipts.
+ */
+export function checkReconciled({ root: rootIn, base: baseFlag, warnOnly, taskId }: {
+    root: any;
+    base: any;
+    warnOnly?: boolean | undefined;
+    taskId: any;
+}): Record<string, any>;
+/**
+ * gcReceipts — prune ONLY receipts that (1) exist on origin/main AND (2) are
+ * older than maxAgeDays by created_at. A fetch failure degrades to a warned
+ * NO-OP — never a deletion.
+ */
+export function gcReceipts({ root: rootIn, maxAgeDays, now }: {
+    root: any;
+    maxAgeDays?: number | undefined;
+    now?: Date | undefined;
+}): {
+    status: string;
+    pruned: never[];
+    kept: number;
+    warning: string;
+} | {
+    status: string;
+    pruned: any[];
+    kept: number;
+    warning?: undefined;
+};
+export const FEATURES_DIR: ".aperant/features";
+export const DELTAS_DIR: ".aperant/features/deltas";
+export const RECEIPTS_DIR: ".aperant/features/receipts";
+export const MATERIALIZER_VERSION: 1;
+//# sourceMappingURL=reconcile.d.mts.map

package/dist/cli/features/reconcile.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.mts","sourceRoot":"","sources":["../../../src/cli/features/reconcile.mjs"],"names":[],"mappings":"AAmDA,mEAAmE;AACnE,wDAEC;AAoDD;;;;;;;;;;;;;;GAcG;AACH,qEASC;AAOD,4EAA4E;AAC5E;;;;;;;;;;KAwBC;AAqCD;;;;GAIG;AACH,yDA8BC;AAsDD;;;;;;;;;;;;;;GAcG;AACH,wFAJW;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAC,GAClF;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAkKlE;AAyHD;;;;;;;;;;;;GAYG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqMC;AAqBD;;;;;;;GAOG;AACH,6DAJa;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAiF9C;AAMD;;;;;;;;GAQG;AACH;;;;;IAJa,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CA4M/B;AAMD;;;;GAIG;AACH;;;;;;;;;;;;;;EA0CC;AAlmCD,2BAA4B,mBAAmB,CAAA;AAC/C,oDAAkD;AAClD,wDAAsD;AACtD,mCAAoC,CAAC,CAAA"}