@cleocode/core 2026.10.21 → 2026.10.22

package/dist/memory/evidence-graph-links.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Graph links from accepted verification evidence (T13950).
+ *
+ * When `cleo verify` accepts evidence atoms it has already validated them
+ * against git, the filesystem or GitHub. Those atoms are the most reliable
+ * statement of what a task touched, so they become graph edges:
+ *
+ * | atom        | graph write                                                    |
+ * |-------------|----------------------------------------------------------------|
+ * | `commit`    | `task:<id> --touches_code--> commit:<sha>` (`ensureCommitNode`) |
+ * | `pr`        | the same, for the PR's merge commit                            |
+ * | `files`     | `task:<id> --touches_code--> file:<path>`                      |
+ * | `decision`  | `decision:<id> --applies_to--> task:<id>`                      |
+ *
+ * Other atoms (tool runs, test runs, notes, `satisfies` bindings that already
+ * live in the tasks store) add no edge. Writes are explicit (they do not depend
+ * on `brain.autoCapture`) and idempotent: nodes are created when absent and an
+ * existing edge is left unchanged, so re-verifying adds nothing.
+ *
+ * Node ids are permanent and sync between devices, so a file node is keyed by
+ * its POSIX path relative to the checkout that holds it. A path outside both
+ * the evidence repository and the store root gets no node and is reported in
+ * `skipped`. File and commit ids of every repository but the store's primary
+ * one carry a repository key (`file:<repo>::<path>`, `commit:<repo>::<sha>`;
+ * T14012, {@link createEvidenceRepoResolver}), so same-named files in two child
+ * repositories stay separate nodes.
+ *
+ * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
+ *
+ * @module memory/evidence-graph-links
+ * @task T13950
+ */
+import type { EvidenceAtom } from '@cleocode/contracts';
+/** Provenance stamped on every edge this module writes. */
+export declare const EVIDENCE_EDGE_PROVENANCE = "evidence:verify";
+/** Graph writes from one accepted verification. */
+export interface EvidenceLinkResult {
+    /** Commits linked (from `commit` and `pr` atoms). */
+    commits: number;
+    /** Files linked. */
+    files: number;
+    /** Decisions linked. */
+    decisions: number;
+    /** `files:` paths given no node because they lie outside the evidence repository. */
+    skipped: string[];
+}
+/** A file's node key: its repository (`null` = the store's own) and repo-relative path. */
+export interface EvidenceFileKey {
+    /** Repository key, or `null` for the store's own repository. */
+    repo: string | null;
+    /** POSIX path relative to the checkout holding the file. */
+    path: string;
+}
+/**
+ * Resolves which repository an evidence file or commit belongs to (T14012),
+ * caching every git probe by directory for the resolver's lifetime (one link
+ * call or one migration run).
+ */
+export interface EvidenceRepoResolver {
+    /**
+     * Node key of an evidence file, or `null` when it lies outside both the
+     * execution and the store root, or its path contains the id separator.
+     */
+    file(path: string, executionRoot: string): EvidenceFileKey | null;
+    /**
+     * Repository key of the checkout holding `dir`: `null` for the primary
+     * repository, for a directory in no checkout, and for an outer repository
+     * that tracks nothing under the store root.
+     */
+    repoOf(dir: string): string | null;
+    /**
+     * Repository of a commit, by the same rule as files: the key of the
+     * checkout that contains it (`repo: null` for the primary repository), or
+     * `null` when no known checkout, or checkouts of more than one repository,
+     * contain it.
+     */
+    commit(sha: string): {
+        repo: string | null;
+    } | null;
+    /** The checkouts the store knows: primary, its children, and their submodules. */
+    checkouts(): readonly string[];
+}
+/**
+ * Repository key of an `origin` URL, the same on every device for the same
+ * repository: `github.com/<owner>/<repo>` through the github.com-anchored
+ * {@link extractRepoOwnerAndName} the PR evidence uses, else `<host>/<path>`.
+ * Scheme, user, port (only a `scheme://` URL has one; in scp form the digits
+ * after the colon are an owner) and `.git` are dropped and the key is
+ * lowercased, so `git@github.com:O/R.git`, `https://github.com/o/r` and
+ * `ssh://git@github.com:22/o/r` agree. A local-path remote has no key.
+ *
+ * @param url - Raw `origin` URL.
+ * @returns The key, or `null`.
+ * @example
+ * ```ts
+ * originRepoKey('ssh://git@github.com:22/O/R.git'); // 'github.com/o/r'
+ * ```
+ * @task T14012
+ */
+export declare function originRepoKey(url: string): string | null;
+/**
+ * Create an {@link EvidenceRepoResolver} for one CLEO store.
+ *
+ * The primary repository is the store root's own: the checkout whose toplevel
+ * is the store root, or an outer repository that tracks files under it (a
+ * store inside a monorepo); failing that, the declared evidence git root
+ * (`evidence.gitRoot` or `CLEO_EVIDENCE_GIT_ROOT`). Its files and commits, in
+ * any of its worktrees, keep unqualified ids, so single-repo stores never
+ * change. Without either, nothing is primary: the id of a child repository
+ * never depends on how many repositories the store holds, so adding one later
+ * moves nothing. Every other checkout (a child repository, a submodule) is
+ * keyed by {@link originRepoKey}; without a usable origin, by its main
+ * checkout's directory relative to the store root. An outer repository that
+ * tracks nothing under the store root (a dotfiles repository at `~`) is
+ * ignored: files under the store root are keyed against the store root.
+ *
+ * @param storeRoot - CLEO store root.
+ * @returns The resolver.
+ * @example
+ * ```ts
+ * const repos = createEvidenceRepoResolver('/work');
+ * repos.file('api/src/x.ts', '/work'); // { repo: 'github.com/o/api', path: 'src/x.ts' }
+ * ```
+ * @task T14012
+ */
+export declare function createEvidenceRepoResolver(storeRoot: string): EvidenceRepoResolver;
+/**
+ * The POSIX path of an evidence file relative to the checkout that holds it,
+ * or `null` when it lies outside both the execution and the store root.
+ *
+ * The file is located as `validateFiles` located it: the execution root when it
+ * exists there, else the store root, else (validated at a commit only) the
+ * execution root. Keying by the holding checkout makes a file verified from a
+ * worktree, from the main checkout, or through a store that parents several
+ * repositories (T14005) one node with the commit-anchored form; the repository
+ * itself is {@link EvidenceRepoResolver.file}'s `repo` (T14012).
+ *
+ * @param path - Path as the `files:` atom stored it.
+ * @param executionRoot - Root of the repository the evidence is about.
+ * @param storeRoot - CLEO store root.
+ * @returns The normalised path, or `null`.
+ * @example
+ * ```ts
+ * repoRelativeEvidencePath('./src/a.ts', '/repo', '/repo'); // 'src/a.ts'
+ * ```
+ */
+export declare function repoRelativeEvidencePath(path: string, executionRoot: string, storeRoot: string): string | null;
+/**
+ * Link a task to the commits, files and decisions its accepted evidence names.
+ *
+ * @param projectRoot - Project whose brain graph is written.
+ * @param taskId - Task the evidence was accepted for.
+ * @param atoms - Validated atoms the verification stored.
+ * @returns Counts of linked targets (repeat links count again; writes are
+ *   idempotent) and the paths skipped as outside the repository.
+ * @example
+ * ```ts
+ * await linkVerifiedEvidence(root, 'T123', evidenceStored);
+ * ```
+ */
+export declare function linkVerifiedEvidence(projectRoot: string, taskId: string, atoms: readonly EvidenceAtom[]): Promise<EvidenceLinkResult>;
+/** One evidence edge re-pointed by {@link migrateEvidenceRepoIds}. */
+export interface EvidenceRepoMove {
+    /** Source node of the edge (`task:<id>`). */
+    from: string;
+    /** Unqualified node id the edge pointed at. */
+    oldTarget: string;
+    /** Repo-qualified node id it points at now. */
+    newTarget: string;
+}
+/** What {@link migrateEvidenceRepoIds} moved and left. */
+export interface EvidenceRepoMigrationResult {
+    /** True when nothing was written (the default; `apply` writes). */
+    dryRun: boolean;
+    /** Receipt an apply wrote before its first write, or `null` for a dry run. */
+    receiptPath: string | null;
+    /** Evidence edges re-pointed (or, in a dry run, that would be). */
+    moved: EvidenceRepoMove[];
+    /** Repo-qualified nodes created, each from the old node it copies. */
+    nodes: Array<{
+        oldId: string;
+        newId: string;
+    }>;
+    /** Evidence edges left unchanged because their repository cannot be told. */
+    unresolved: Array<{
+        from: string;
+        target: string;
+        reason: string;
+    }>;
+}
+/** Receipt of an applied {@link migrateEvidenceRepoIds} run: every old id → new id. */
+export interface EvidenceRepoMigrationReceipt {
+    /** Receipt format version. */
+    version: 1;
+    /** ISO timestamp of the apply. */
+    migratedAt: string;
+    /** `started` before the first write; `complete` once the transaction committed. */
+    status: 'started' | 'complete';
+    /** Edges re-pointed, old target → new target. */
+    moved: EvidenceRepoMove[];
+    /** Nodes created, old id → new id. Old nodes are kept for a later prune. */
+    nodes: Array<{
+        oldId: string;
+        newId: string;
+    }>;
+    /** Edges left unchanged. */
+    unresolved: EvidenceRepoMigrationResult['unresolved'];
+}
+/**
+ * Default receipt path of an applied evidence repo-id migration.
+ *
+ * @param projectRoot - Project root.
+ * @param migratedAt - ISO timestamp of the apply.
+ * @returns Absolute receipt path under `.cleo/backups/migrations/`.
+ * @example
+ * ```ts
+ * defaultEvidenceRepoReceiptPath(root, '2026-10-24T00:00:00.000Z');
+ * ```
+ * @task T14012
+ */
+export declare function defaultEvidenceRepoReceiptPath(projectRoot: string, migratedAt: string): string;
+/**
+ * Forward migration of evidence file and commit node ids to repo-qualified ids
+ * (T14012), by the rule {@link createEvidenceRepoResolver} applies to new links.
+ *
+ * Only `evidence:verify` edges move. A commit belongs to the repository whose
+ * checkout contains it. A file belongs to the one repository whose checkout has
+ * its path, or, when several do, to the one the same task's commits belong to.
+ * Anything still ambiguous or absent everywhere is reported in `unresolved`
+ * and left as it is. Old nodes are never deleted here (other tables and
+ * writers may still reference them; a later prune owns that); a copied commit
+ * node records its `repo` in its metadata. Re-running is a no-op.
+ *
+ * A dry run is the default; only `apply` writes, after recording a receipt
+ * (status `started`, every old id → new id) and completing it once the single
+ * transaction commits. It never runs automatically.
+ *
+ * @param projectRoot - CLEO store root.
+ * @param options - `apply` writes; `receiptPath` overrides the default; `now` for tests.
+ * @returns The moves, the created nodes, the unresolved edges and the receipt path.
+ * @example
+ * ```ts
+ * const plan = await migrateEvidenceRepoIds(root);
+ * const done = await migrateEvidenceRepoIds(root, { apply: true });
+ * ```
+ * @task T14012
+ */
+export declare function migrateEvidenceRepoIds(projectRoot: string, options?: {
+    apply?: boolean;
+    receiptPath?: string;
+    now?: Date;
+}): Promise<EvidenceRepoMigrationResult>;
+//# sourceMappingURL=evidence-graph-links.d.ts.map

package/dist/memory/evidence-graph-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-graph-links.d.ts","sourceRoot":"","sources":["../../src/memory/evidence-graph-links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAyBxD,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAE1D,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qFAAqF;IACrF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA+BD,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IAClE;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACnC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACpD,kFAAkF;IAClF,SAAS,IAAI,SAAS,MAAM,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAexD;AAKD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CAAC,SAAS,EAAE,MAAM,GAAG,oBAAoB,CAqHlF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAEf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAoF7B;AAED,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,2BAA2B;IAC1C,mEAAmE;IACnE,MAAM,EAAE,OAAO,CAAC;IAChB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mEAAmE;IACnE,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,sEAAsE;IACtE,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,6EAA6E;IAC7E,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrE;AAED,uFAAuF;AACvF,MAAM,WAAW,4BAA4B;IAC3C,8BAA8B;IAC9B,OAAO,EAAE,CAAC,CAAC;IACX,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC;IAC/B,iDAAiD;IACjD,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,4EAA4E;IAC5E,KAAK,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,4BAA4B;IAC5B,UAAU,EAAE,2BAA2B,CAAC,YAAY,CAAC,CAAC;CACvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAQ9F;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CAAO,GAClE,OAAO,CAAC,2BAA2B,CAAC,CA2ItC"}