@isaacriehm/cairn-core 0.4.2 → 0.5.0

package/dist/init/source-comments/ingest.d.ts

@@ -1,20 +1,40 @@
 /**
- * Phase 7b orchestrator — walker → classifier → persist.
+ * Phase 7b orchestrator (v0.5.0 SoT model) — walker → classifier →
+ * topic-index lookup → emit-or-cite → strip-replace.
  *
- * Output:
- *   - DEC drafts (one per "rationale" classification with non-empty title)
- *     written to `.cairn/ground/decisions/_inbox/<id>.draft.md`
- *   - Invariant files (one per "constraint" classification with non-empty
- *     suggestedInvariant) written directly to
- *     `.cairn/ground/invariants/INV-<NNNN>.md` with `status: active`. Auto-
- *     promote — the operator can edit / supersede via cairn-attention or
- *     direct edit. Invariants don't go through an `_inbox/` review queue
- *     because the classifier emits hard rules, not policy decisions.
- *   - Canonical-map citations appended to
- *     `.cairn/baseline/canonical-citations-<ISO>.yaml`
- *   - Full audit (every block + classification) at
- *     `.cairn/baseline/source-comments-<ISO>.yaml` — consumed by the
- *     strip-replace stage so it doesn't have to re-walk.
+ * Plan §5.3 algorithm:
+ *   1. Walk source files for prose-bearing comments (existing logic).
+ *   2. Classify via Haiku, kind only — `rationale` / `constraint` /
+ *      `citation` / `license` / `other`. No paraphrased title, no rewritten
+ *      invariant body, no canonical-topic suggestion.
+ *   3. Build a content-fingerprint slug for every rationale + constraint
+ *      block. Look it up in the existing topic-index:
+ *        a. **Cite-existing** — slug already owned by a docs/CLAUDE.md/
+ *           AGENTS.md/rule entry that has been emitted. Strip-replace
+ *           inserts `// §DEC-<existing>` (or `§INV-<existing>`) at the
+ *           comment's offset. No new ground-state file is written.
+ *        b. **Novel** — slug not in the topic-index, or owned by an
+ *           un-emitted entry. Add the block to the topic-index as a
+ *           new source-comment SoT entry; emit a verbatim DEC/INV via
+ *           `emitFromTopicIndex` with `sot_kind: "ledger"`. After emit,
+ *           strip-replace inserts `§DEC-<new>` / `§INV-<new>`.
+ *   4. Auto-promote — every newly-emitted entity ships with
+ *      `status: accepted` (no `_inbox/` draft queue). Plan §1's pivot:
+ *      the inbox-as-blocker was the bug; verbatim bodies + auto-promote
+ *      remove the manual review step.
+ *   5. License + citation + other classifications → no-op (no DEC, no
+ *      strip-replace). License blocks stay verbatim in source.
+ *
+ * Output side-effects (all relative to repoRoot):
+ *   - `.cairn/ground/decisions/<DEC-id>.md`        (one per novel rationale)
+ *   - `.cairn/ground/invariants/<INV-id>.md`       (one per novel constraint)
+ *   - `.cairn/ground/topic-index.yaml`             (extended with source-comment SoT entries)
+ *   - `.cairn/ground/anchor-map.yaml`              (one anchor per novel slug)
+ *   - `.cairn/ground/sot-bindings.yaml`            (forward+reverse for new ids)
+ *   - `.cairn/ground/sot-cache.yaml`               (token cache for Layer A)
+ *   - `.cairn/ground/scope-index.yaml`             (file → ids that landed in source)
+ *   - `.cairn/baseline/source-comments-<ISO>.yaml` (full audit — every block + verdict)
+ *   - source files                                 (stripped & cited per replacement)
  */
 import type { ProjectGlobs } from "../../sensors/types.js";
 import type { ClassifyArgs, CommentClassification, CommentClassKind } from "./classify.js";
@@ -32,77 +52,81 @@ export interface IngestSourceCommentsArgs {
     /** When set, override `Date.now()` for deterministic test outputs. */
     nowIso?: string;
     /**
-     * Project globs from `.cairn/config.yaml` (or the mapper output). When
-     * provided, every DEC draft + invariant gets `capture_confidence` scored
-     * and stamped at write time so `cairn attention bulk-accept` becomes an
-     * O(1) file move instead of re-scoring every draft on disk.
+     * Project globs from `.cairn/config.yaml`. Carried through for
+     * compatibility with the parallel-678 caller; phase 7b under v0.5.0
+     * doesn't gate behavior on these (every novel rationale/constraint
+     * auto-promotes without scoring).
      */
     globs?: ProjectGlobs;
-    /** Pilot module path (workflow.md `pilot_module`) for scoring bias. */
+    /** Pilot module path (workflow.md `pilot_module`). Same compat note. */
     pilotModule?: string;
     /**
-     * Caller-supplied DEC id Set, threaded by the parallel orchestrator
-     * across phases 6 / 7b / 7c so concurrent allocations don't collide.
+     * Caller-supplied DEC id Set — kept for symmetry with phases 6 / 7c.
+     * Plan §3.2.1 derives content-addressed ids; collisions across phases
+     * are vanishingly unlikely so the Set is informational.
      */
     existingDecIds?: Set<string>;
-    /**
-     * Caller-supplied INV id Set. Only 7b allocates invariant ids today,
-     * but the optional arg matches the DEC pattern for symmetry and lets
-     * future phases share the allocator.
-     */
+    /** Caller-supplied INV id Set. Same compat note. */
     existingInvIds?: Set<string>;
 }
+interface IngestEmittedRecord {
+    id: string;
+    path: string;
+    sourceFile: string;
+    slug: string;
+    status: "accepted";
+}
+interface IngestCiteRecord {
+    /** Pre-existing DEC/INV id the source comment was bound to. */
+    id: string;
+    /** Source file the cite landed in. */
+    sourceFile: string;
+    /** 1-indexed inclusive line range of the original source comment. */
+    lineRange: [number, number];
+    /** Slug that resolved the topic-index lookup. */
+    slug: string;
+}
+interface IngestSkipRecord {
+    blockId: string;
+    reason: string;
+}
+interface StripOutcomePersisted {
+    file: string;
+    applied: number;
+    skipped: {
+        blockId: string;
+        reason: string;
+    }[];
+    fileSkipReason: string | null;
+}
 export interface IngestSourceCommentsResult {
     walk: WalkResult;
     classifications: CommentClassification[];
-    decDraftsWritten: {
-        id: string;
-        path: string;
-        sourceFile: string;
-    }[];
-    /**
-     * INV-<NNNN>.md files written directly to `.cairn/ground/invariants/`
-     * with `status: active`. The cairn-adopt summary surfaces the count.
-     */
-    invariantsWritten: {
-        id: string;
-        path: string;
-        sourceFile: string;
-    }[];
-    /** Files where the source comment was successfully replaced with `// §INV-NNNN`. */
-    invariantStripFilesModified: number;
-    /** Number of strip items that landed (one per invariant comment). */
-    invariantStripItemsApplied: number;
-    /** Number of strip items that skipped (range-mismatch, dirty, missing, etc.). */
-    invariantStripItemsSkipped: number;
-    /** Per-file strip outcomes — debug surface for "wrote ground state but not source". */
-    invariantStripOutcomes: {
-        file: string;
-        applied: number;
-        skipped: {
-            blockId: string;
-            reason: string;
-        }[];
-        fileSkipReason: string | null;
-    }[];
-    /** Set when applyStripReplace threw — null on the happy path. */
-    invariantStripError: string | null;
+    /** Verbatim DEC files written under `.cairn/ground/decisions/`. */
+    decsWritten: IngestEmittedRecord[];
+    /** Verbatim INV files written under `.cairn/ground/invariants/`. */
+    invsWritten: IngestEmittedRecord[];
     /**
-     * Count of "constraint" classifications regardless of whether they
-     * produced a non-empty suggestedInvariant. Always equals
-     * invariantsWritten.length when no proposals had empty bodies.
+     * Source comments that resolved to an already-emitted DEC/INV via the
+     * topic-index lookup. Strip-replace still fires for these — the source
+     * file gets the existing `§DEC-<hash>` / `§INV-<hash>` token.
      */
-    invariantProposalsAdded: number;
-    canonicalCitationsAdded: number;
+    citesEmitted: IngestCiteRecord[];
+    /** Blocks the ingest stage skipped (license, citation, other, errors). */
+    skipped: IngestSkipRecord[];
+    stripFilesModified: number;
+    stripItemsApplied: number;
+    stripItemsSkipped: number;
+    stripOutcomes: StripOutcomePersisted[];
+    stripError: string | null;
     auditPath: string;
     auditRelPath: string;
-    invariantProposalsPath: string | null;
-    canonicalCitationsPath: string | null;
     inputTokens: number;
     outputTokens: number;
     batchesRun: number;
     batchesFailed: number;
-    /** Distribution by classifier kind. */
+    /** Distribution by classifier kind (rationale / constraint / etc.). */
     kindCounts: Record<CommentClassKind, number>;
 }
 export declare function runSourceCommentsIngestion(args: IngestSourceCommentsArgs): Promise<IngestSourceCommentsResult>;
+export {};