@cleocode/core 2026.10.27 → 2026.11.1-canary.3

package/dist/doctor/type-matrix-repair.d.ts

@@ -0,0 +1,194 @@
+/**
+ * `cleo doctor type-matrix`: repair the parent/child pairs that break the
+ * type matrix (`PARENT_TYPE_MATRIX`: saga→epic, epic→task, task→subtask).
+ *
+ * The writers refuse new violations (T12883 R4); this repairs the rows written
+ * before they did (T14096). A dry run by default:
+ *
+ * - {@link planTypeMatrixRepair} lists every parented violation with the
+ *   operations that would fix it. A pair with exactly one valid operation (a
+ *   leaf `subtask` under an epic becomes a `task`; a leaf `task` under a task
+ *   becomes a `subtask`) carries it as its `proposal`. A pair with none or
+ *   several is ambiguous: its `options` are listed and nothing is applied
+ *   until the calling agent names one in a resolution.
+ * - {@link applyTypeMatrixRepair} applies the proposals plus the agent's
+ *   resolutions through the task accessor, in one transaction, guarded on each
+ *   row being unchanged since it was read (or since the reviewed plan read
+ *   it), and writes one receipt (before and after image of every touched row,
+ *   with the version it wrote and its children) to the task audit log. A
+ *   reparent is held to the reparent core's checks (no cancelled or archived
+ *   target, no cycle, depth and sibling limits) and reopens done ancestors.
+ * - {@link rollbackTypeMatrixRepair} restores the before image, refused when a
+ *   row changed after the repair (its version moved), and never for a row
+ *   whose restore would break a child filed under it since. A row whose before image the type-matrix
+ *   trigger now forbids (a legacy task under a task, say) is not restored; the
+ *   result names it and why (owner decision, T14096).
+ *
+ * The contracts matrix is the authority (owner decision, T14096): a subtask
+ * belongs under a task, even though the trigger still accepts one under an
+ * epic until T14131 tightens it.
+ *
+ * A violation at the root (a parentless task) is outside this repair.
+ *
+ * @module
+ * @task T14096
+ */
+import type { TaskType } from '@cleocode/contracts';
+/** Audit-log action of an applied repair (its row id is the receipt id). */
+export declare const TYPE_MATRIX_REPAIR_ACTION = "doctor.type-matrix.repair";
+/** Audit-log action of a rollback. */
+export declare const TYPE_MATRIX_ROLLBACK_ACTION = "doctor.type-matrix.rollback";
+/** One repair operation: re-type a task, or move it under another parent. */
+export type TypeMatrixRepairOp = {
+    readonly kind: 'retype';
+    readonly taskId: string;
+    readonly to: TaskType;
+} | {
+    readonly kind: 'reparent';
+    readonly taskId: string;
+    readonly toParentId: string;
+};
+/** A parent/child pair that breaks the matrix, and how it can be repaired. */
+export interface TypeMatrixViolationPlan {
+    readonly taskId: string;
+    readonly taskType: TaskType;
+    readonly parentId: string;
+    readonly parentType: TaskType;
+    /** The one valid operation, or null when the pair is ambiguous. */
+    readonly proposal: TypeMatrixRepairOp | null;
+    /** Every valid re-type of the child or the parent (reparenting is the agent's to name). */
+    readonly options: readonly TypeMatrixRepairOp[];
+}
+/** One touched row: its type and parent before and after, and the row version after. */
+export interface TypeMatrixRowImage {
+    readonly id: string;
+    readonly before: {
+        readonly type: TaskType;
+        readonly parentId: string | null;
+    };
+    readonly after: {
+        readonly type: TaskType;
+        readonly parentId: string | null;
+    };
+    /** `updatedAt` the repair wrote: a rollback refuses the row once it moved. */
+    readonly updatedAt: string;
+    /** The row's children right after the repair: a rollback never breaks a child filed later. */
+    readonly children: readonly string[];
+}
+/** What `cleo doctor type-matrix` reports. */
+export interface TypeMatrixRepairReport {
+    readonly dryRun: boolean;
+    /** Parented violations found. */
+    readonly violations: number;
+    /** Count per `parent → child` type pair. */
+    readonly byPair: Readonly<Record<string, number>>;
+    /** Every violation with its proposal or options. */
+    readonly plans: readonly TypeMatrixViolationPlan[];
+    /** The operations applied (or, in a dry run, that would be). */
+    readonly operations: readonly TypeMatrixRepairOp[];
+    /** Violations no operation covers: ambiguous pairs without a resolution. */
+    readonly unresolved: readonly string[];
+    /** The receipt of an applied repair. */
+    readonly receiptId?: string;
+    /** The command that undoes it. */
+    readonly rollback?: string;
+    /** Touched rows of an applied repair. */
+    readonly rows?: readonly TypeMatrixRowImage[];
+    /** Done ancestors a reparent reopened, as `cleo update --parent` does. */
+    readonly reopened?: readonly string[];
+    /**
+     * The version (`updatedAt`, else `createdAt`) of each row the operations
+     * write, as the plan read it. Pass the plan to {@link applyTypeMatrixRepair}
+     * to apply exactly what was reviewed: a row written since is `E_CONFLICT`.
+     */
+    readonly rowVersions: Readonly<Record<string, string>>;
+}
+/**
+ * Parse a `--resolutions` file: a JSON array of `retype` and `reparent`
+ * operations.
+ *
+ * @param text - The file's contents.
+ * @returns The operations, or why the file was refused.
+ * @example
+ * ```ts
+ * parseTypeMatrixResolutions('[{"kind":"retype","taskId":"T1","to":"epic"}]');
+ * ```
+ */
+export declare function parseTypeMatrixResolutions(text: string): {
+    ok: true;
+    operations: TypeMatrixRepairOp[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Plan the repair of the store's type-matrix violations without writing.
+ *
+ * @param projectRoot - Project root.
+ * @param resolutions - Operations the calling agent chose for ambiguous pairs.
+ * @returns Every violation, its options, and the operations an apply would run.
+ * @example
+ * ```ts
+ * const plan = await planTypeMatrixRepair(root);
+ * console.log(plan.byPair, plan.unresolved.length);
+ * ```
+ */
+export declare function planTypeMatrixRepair(projectRoot: string, resolutions?: readonly TypeMatrixRepairOp[]): Promise<TypeMatrixRepairReport>;
+/** Options for {@link applyTypeMatrixRepair}. */
+export interface TypeMatrixApplyOptions {
+    /**
+     * The reviewed dry run. Its operations must be the ones decided now, and
+     * each row is written only at the version the plan read, so a write made
+     * after the review is `E_CONFLICT` with nothing changed.
+     */
+    readonly plan?: TypeMatrixRepairReport;
+}
+/**
+ * Apply the proposals and the agent's resolutions in one transaction, and
+ * record the receipt. Each row is written only at the version it was read at
+ * (by this call, or by the reviewed `plan`): otherwise `E_CONFLICT`, and the
+ * transaction writes nothing. A reparent reopens the done ancestors of its old
+ * and new parent, as `cleo update --parent` does.
+ *
+ * @param projectRoot - Project root.
+ * @param resolutions - Operations the calling agent chose for ambiguous pairs.
+ * @param opts - The reviewed plan to hold the apply to.
+ * @returns The report with the receipt id and the rollback command.
+ * @example
+ * ```ts
+ * const done = await applyTypeMatrixRepair(root, [{ kind: 'retype', taskId: 'T9', to: 'saga' }]);
+ * console.log(done.rollback);
+ * ```
+ */
+export declare function applyTypeMatrixRepair(projectRoot: string, resolutions?: readonly TypeMatrixRepairOp[], opts?: TypeMatrixApplyOptions): Promise<TypeMatrixRepairReport>;
+/** What a rollback restored. */
+export interface TypeMatrixRollbackResult {
+    /** The repair receipt rolled back. */
+    readonly receiptId: string;
+    /** The rollback's own audit row. */
+    readonly rollbackReceiptId: string;
+    /** Rows restored to their before image. */
+    readonly restored: readonly string[];
+    /** Rows left as the repair set them: the type-matrix trigger forbids their before image. */
+    readonly refused: readonly {
+        readonly id: string;
+        readonly reason: string;
+    }[];
+}
+/**
+ * Restore the rows a repair changed to their before image. Refused when the
+ * receipt is unknown or already rolled back, or when any row no longer
+ * matches the repair's after image (a later edit is never overwritten). Only
+ * the rows the type-matrix trigger allows are restored; the rest are listed
+ * in `refused` with the reason, and refused outright when none can be.
+ *
+ * @param projectRoot - Project root.
+ * @param receiptId - `receiptId` of {@link applyTypeMatrixRepair}.
+ * @returns The restored rows and the rollback's audit row id.
+ * @example
+ * ```ts
+ * await rollbackTypeMatrixRepair(root, done.receiptId!);
+ * ```
+ */
+export declare function rollbackTypeMatrixRepair(projectRoot: string, receiptId: string): Promise<TypeMatrixRollbackResult>;
+//# sourceMappingURL=type-matrix-repair.d.ts.map

package/dist/doctor/type-matrix-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-matrix-repair.d.ts","sourceRoot":"","sources":["../../src/doctor/type-matrix-repair.ts"],"names":[],"mappings":"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"}