create-principles-disciple 1.144.11 → 1.144.13

package/core/dist/runtime-v2/candidate-intake-service.d.ts

@@ -4,12 +4,20 @@
  * Workflow:
  *   1. Validate input
  *   2. Check idempotency (existsForCandidate) — O(1) lookup
+ *   2b. Check durable reuse resolution replay (PRI-917 PR3B Phase 2) —
+ *       a candidate already resolved into an existing Principle returns that
+ *       resolution; no decision is re-asked, no Principle is created
  *   3. Load candidate from DB (RuntimeStateManager)
  *   3b. ★ Principle Ledger write boundary (Phase 1 / PR1) — see below
  *   4. Load artifact from DB and parse recommendation
  *   5. Build 11-field LedgerPrincipleEntry
  *   6. Write via adapter.writeProbationEntry()
  *
+ * 4d (PRI-917 Slice 2 + PR3B Phase 2) — the reuse gate sits between 4c and 5:
+ * a credible proposal + a `reuse` verdict is materialised as durable evidence
+ * on the selected Principle (appendReuseEvidence) and reported as a
+ * `reuse_selected` refusal; a `create` verdict proceeds exactly as before.
+ *
  * ── Principle Ledger write boundary (Phase 1 / PR1) ─────────────────────────
  * This service is the single shared chokepoint through which EVERY
  * candidate-origin write to the Principle Ledger flows (pd-cli `candidate
@@ -33,8 +41,13 @@
  *   - No promotion to active principle (M8+)
  *   - No pain signal bridge
  */
-import type { LedgerAdapter, LedgerPrincipleEntry } from './candidate-intake.js';
+import type { LedgerAdapter, LedgerPrincipleEntry, Recommendation } from './candidate-intake.js';
+import { CandidateIntakeError } from './candidate-intake.js';
 import type { RuntimeStateManager } from './store/runtime-state-manager.js';
+import type { ReuseDecision, ReuseProposal } from './principle-reuse/reuse-proposal.js';
+import type { ReuseEvaluationOutputV1 } from './principle-reuse/reuse-evaluation-output.js';
+import type { ReuseCandidateInput } from './principle-reuse/reuse-domain.js';
+import type { ReuseEvidenceEntry } from './types/principle-schema.js';
 /**
  * Why the Principle Ledger write boundary refused a candidate (Phase 1 / PR1).
  *
@@ -43,8 +56,33 @@ import type { RuntimeStateManager } from './store/runtime-state-manager.js';
  *   candidate keeps flowing through its existing route / defer handling.
  * - `unknown_kind` — no usable kind at all (missing / non-string / not in the
  *   known set). This is the case that previously FAILED OPEN into a principle.
+ * - `reuse_selected` (PRI-917 Slice 2) — the reuse gate produced a credible
+ *   proposal and the injected decision function answered `reuse`, so no new
+ *   Principle was written. Encoded as a refusal rather than a new result
+ *   variant, which keeps the result-union shape stable for every consumer.
+ *   PRI-917 PR3B Phase 2: the verdict is now ALSO materialised as durable
+ *   evidence on the selected Principle (`reuseEvidence[]`) before this
+ *   disposition is returned, and this reason doubles as the replay
+ *   disposition when a candidate's resolution already exists (no new decision
+ *   is asked, no Principle is created — INV-R07).
+ *
+ *   ⚠ That is shape compatibility ONLY, not message compatibility. Known
+ *   counter-example (verified, not fixed here): `pd candidate` presents ANY
+ *   refusal as "this candidate kind does not target the Principle Ledger" and
+ *   re-throws it as INPUT_INVALID — both wrong for a reuse decision, which
+ *   DOES target the Ledger. No production caller injects `reuseDecision`
+ *   yet, so this cannot surface today; but any consumer that renders
+ *   refusal-specific operator messages MUST branch on
+ *   `reason === 'reuse_selected'` BEFORE production reuse is enabled.
+ * - `reuse_pending_owner` (PRI-917 v0.3.3, OD-PRI917-05) — the Reuse Review
+ *   Gate ran the semantic evaluation on the AUTO path (no Owner decision
+ *   function present) and the recommendation was `reuse` with a selection
+ *   inside the proposal. No Principle is created, NO evidence is written, and
+ *   the candidate stays PENDING for the Owner. Consumers MUST branch on this
+ *   reason: unlike every other refusal, the candidate is intentionally kept
+ *   pending — do not mark it consumed and do not seed internalization for it.
  */
-export type LedgerRefusalReason = 'non_principle_kind' | 'unknown_kind';
+export type LedgerRefusalReason = 'non_principle_kind' | 'unknown_kind' | 'reuse_selected' | 'reuse_pending_owner';
 /**
  * Explicit disposition returned by {@link CandidateIntakeService.intake}.
  *
@@ -57,18 +95,125 @@ export type CandidateIntakeResult = {
     /** `true` when THIS call wrote a new entry; `false` for the idempotent no-op. */
     readonly written: boolean;
     readonly entry: LedgerPrincipleEntry;
+    /**
+     * PRI-917 Slice 2 — what the reuse gate did, for observability.
+     * Optional so every existing producer of this variant stays valid.
+     */
+    readonly reuseCheck?: ReuseCheckOutcome;
 } | {
     readonly outcome: 'refused';
     readonly reason: LedgerRefusalReason;
     readonly candidateId: string;
-    /** The raw persisted kind, or `null` when it was absent / not a string. */
+    /** The raw persisted kind, or `null` when it was absent / not a string / not loaded. */
     readonly rawRecommendationKind: string | null;
     readonly message: string;
+    /** PRI-917 Slice 2 — present only when `reason === 'reuse_selected'`. */
+    readonly reuseProposal?: ReuseProposal;
+    /** The Principle the decision function selected, when it chose reuse. */
+    readonly selectedPrincipleId?: string;
+    /**
+     * PRI-917 PR3B Phase 2 — present only when `reason === 'reuse_selected'`:
+     * the evidence entry just written (fresh decision), or the pre-existing
+     * resolution (replay). This is the durable record that the candidate was
+     * resolved into `selectedPrincipleId` instead of creating a Principle.
+     */
+    readonly reuseEvidence?: ReuseEvidenceEntry;
+    /**
+     * PRI-917 v0.3.3 — present only when `reason === 'reuse_pending_owner'`:
+     * the semantic recommendation that triggered the park. NEVER persisted —
+     * the Owner re-evaluates via `pd candidate review` (T7: proposal output
+     * cannot mutate ledger/evidence; the park itself writes nothing).
+     */
+    readonly reuseRecommendation?: ReuseRecommendationOutcome;
+};
+/**
+ * PRI-917 v0.3.3 — outcome of the auto-path Reuse Review Gate's evaluation
+ * hook. `recommended` wraps the validated `reuse-evaluation-output-v1` payload
+ * (a RECOMMENDATION — never a decision); `unavailable` is the observable
+ * degradation that lets CREATE proceed (SPEC v0.3.3 Rule 4: evaluation failure
+ * must never block learning).
+ */
+export type ReuseRecommendationOutcome = ({
+    status: 'recommended';
+} & ReuseEvaluationOutputV1) | {
+    status: 'unavailable';
+    reason: string;
 };
+/**
+ * PRI-917 Slice 2 — what the reuse gate did before a ledger write.
+ *
+ * - `not_configured` — no decision function was injected, so no gate ran. This
+ *   is the current production shape; it is reported rather than assumed, so a
+ *   caller can never mistake "gate absent" for "gate found nothing".
+ * - `no_candidates` — the gate ran and found nothing credible.
+ * - `create_decided` — the gate found candidates and the decision function
+ *   answered `create`; the write proceeded exactly as before.
+ * - `recommended_create` (PRI-917 v0.3.3) — the auto-path recommendation hook
+ *   ran and did NOT answer reuse (create / uncertain / unavailable / selection
+ *   outside the proposal); the write proceeded per Rules 2-4. Never emitted
+ *   when only an Owner decision function is configured.
+ */
+export type ReuseCheckOutcome = 'not_configured' | 'no_candidates' | 'create_decided' | 'recommended_create';
 export interface CandidateIntakeServiceOptions {
     stateManager: RuntimeStateManager;
     ledgerAdapter: LedgerAdapter;
+    /**
+     * PRI-917 Slice 2 — optional reuse decision function.
+     *
+     * When omitted (the current production shape) the reuse gate does not run
+     * and intake behaves exactly as before; the result still reports
+     * `reuseCheck: 'not_configured'` so "no gate" is never mistaken for "no
+     * duplicate found".
+     *
+     * Mutually exclusive with reuseRecommendation; supplying both fails at construction.
+     * When provided, it receives the bounded proposal and MUST answer `reuse`
+     * or `create` — there is no automatic option and no default.
+     */
+    reuseDecision?: (proposal: ReuseProposal) => ReuseDecision;
+    /** Workspace state dir used for read-only reuse retrieval. */
+    reuseStateDir?: string;
+    /**
+     * PRI-917 v0.3.3 (OD-PRI917-05) — optional auto-path Reuse Review Gate
+     * recommendation hook. When injected (WITHOUT `reuseDecision`), the gate
+     * runs the semantic evaluation for every candidate with a credible proposal
+     * and parks the candidate (`refused/reuse_pending_owner`) when the
+     * recommendation is `reuse` with a selection inside the proposal. Any other
+     * outcome (create / uncertain / unavailable / throw) degrades to CREATE —
+     * evaluation failure must never block learning (Rule 4). The hook is a
+     * RECOMMENDATION channel only: it can never write, and it is never injected
+     * together with an Owner decision function by production callers.
+     */
+    reuseRecommendation?: (claim: ReuseCandidateInput, proposal: ReuseProposal) => Promise<ReuseRecommendationOutcome>;
 }
+/**
+ * PRI-917 PR3A (surface audit C4): the candidate-semantics extraction shared
+ * by BOTH the intake flow (steps 4b/4c) and the `pd candidate review`
+ * surface — one implementation, so the retrieval input shown to the Owner can
+ * never drift from what intake actually consumes.
+ *
+ * Resolution order (identical to intake steps 4b→4c):
+ *   1. candidate.sourceRecommendationJson — validated directly, then via the
+ *      diagnostician description→text normalization; malformed JSON warns and
+ *      falls through (rc-9 observable degradation);
+ *   2. artifact.contentJson — the three historical shapes.
+ *
+ * Pure apart from the rc-9 warn; never throws — failures come back as
+ * `{ ok: false, error }` carrying the exact CandidateIntakeError intake
+ * itself would throw.
+ */
+export type CandidateRecommendationExtraction = {
+    ok: true;
+    recommendation: Recommendation;
+} | {
+    ok: false;
+    error: CandidateIntakeError;
+};
+export declare function extractIntakeRecommendation(candidate: {
+    candidateId: string;
+    sourceRecommendationJson?: string | null;
+}, artifact: {
+    contentJson: string;
+} | null): CandidateRecommendationExtraction;
 export declare class CandidateIntakeService {
     #private;
     constructor(opts: CandidateIntakeServiceOptions);
@@ -90,5 +235,9 @@ export declare class CandidateIntakeService {
      *   - LEDGER_WRITE_FAILED when ledger write fails
      */
     intake(candidateId: string): Promise<CandidateIntakeResult>;
+    /** Whether the automatic recommendation channel is configured for read-only review. */
+    get reuseReviewEnabled(): boolean;
+    /** Uses the same input validation and gate as intake, but never writes. */
+    reviewReuse(candidateId: string): Promise<CandidateIntakeResult | null>;
 }
 //# sourceMappingURL=candidate-intake-service.d.ts.map

package/core/dist/runtime-v2/candidate-intake-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-intake-service.d.ts","sourceRoot":"","sources":["../../src/runtime-v2/candidate-intake-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAkB,MAAM,uBAAuB,CAAC;AAEjG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAM5E;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,cAAc,CAAC;AAExE;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAC7B;IACE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAGN,MAAM,WAAW,6BAA6B;IAC5C,YAAY,EAAE,mBAAmB,CAAC;IAClC,aAAa,EAAE,aAAa,CAAC;CAC9B;AAyDD,qBAAa,sBAAsB;;IAIjC,YAAY,IAAI,EAAE,6BAA6B,EAG9C;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA2JhE;CACF"}
+{"version":3,"file":"candidate-intake-service.d.ts","sourceRoot":"","sources":["../../src/runtime-v2/candidate-intake-service.ts"],"names":[],"mappings":"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"}