@principles/core 1.73.0

package/dist/runtime-v2/candidate-intake-service.js

@@ -0,0 +1,117 @@
+/**
+ * CandidateIntakeService — consumes pending candidates and writes ledger entries.
+ *
+ * Workflow:
+ *   1. Validate input
+ *   2. Check idempotency (existsForCandidate) — O(1) lookup
+ *   3. Load candidate from DB (RuntimeStateManager)
+ *   4. Load artifact from DB and parse recommendation
+ *   5. Build 11-field LedgerPrincipleEntry
+ *   6. Write via adapter.writeProbationEntry()
+ *
+ * On error: candidate stays `pending`, throws CandidateIntakeError.
+ * Idempotent: if adapter already has entry for candidate, returns it (no-op).
+ *
+ * Non-goals (M7):
+ *   - No DB status update to 'consumed' (m7-04 CLI handler does that)
+ *   - No promotion to active principle (M8+)
+ *   - No pain signal bridge
+ */
+import { randomUUID } from 'crypto';
+import { CandidateIntakeError, INTAKE_ERROR_CODES } from './candidate-intake.js';
+export class CandidateIntakeService {
+    #stateManager;
+    #ledgerAdapter;
+    constructor(opts) {
+        this.#stateManager = opts.stateManager;
+        this.#ledgerAdapter = opts.ledgerAdapter;
+    }
+    /**
+     * Consume a pending candidate: load it and its artifact, build a
+     * LedgerPrincipleEntry, and write it to the ledger via the adapter.
+     *
+     * @param candidateId - The candidate ID to intake.
+     * @returns The written (or existing) LedgerPrincipleEntry.
+     * @throws CandidateIntakeError with code:
+     *   - INPUT_INVALID when candidateId is empty/invalid
+     *   - CANDIDATE_NOT_FOUND when candidate does not exist
+     *   - ARTIFACT_NOT_FOUND when artifact is missing or unreadable
+     *   - LEDGER_WRITE_FAILED when ledger write fails
+     */
+    async intake(candidateId) {
+        // 1. Input validation (E-01)
+        if (!candidateId || typeof candidateId !== 'string' || candidateId.trim() === '') {
+            throw new CandidateIntakeError(INTAKE_ERROR_CODES.INPUT_INVALID, 'candidateId must be a non-empty string', { candidateId });
+        }
+        // 2. Idempotency check FIRST (E-02, D-10)
+        const existing = this.#ledgerAdapter.existsForCandidate(candidateId);
+        if (existing) {
+            return existing;
+        }
+        // 3. Load candidate from DB
+        const candidate = await this.#stateManager.getCandidate(candidateId);
+        if (!candidate) {
+            throw new CandidateIntakeError(INTAKE_ERROR_CODES.CANDIDATE_NOT_FOUND, `Candidate ${candidateId} not found`, { candidateId });
+        }
+        // 4. Load artifact (E-04)
+        const artifact = await this.#stateManager.getArtifact(candidate.artifactId);
+        if (!artifact) {
+            throw new CandidateIntakeError(INTAKE_ERROR_CODES.ARTIFACT_NOT_FOUND, `Artifact ${candidate.artifactId} not found for candidate ${candidateId}`, { candidateId, artifactId: candidate.artifactId });
+        }
+        // 4b. Parse recommendation from candidate.sourceRecommendationJson FIRST (canonical source)
+        // Fall back to artifact.contentJson for backwards-compatibility with legacy/manual inserts.
+        // eslint-disable-next-line @typescript-eslint/init-declarations
+        let recommendation;
+        const sourceRecJson = candidate.sourceRecommendationJson;
+        try {
+            if (sourceRecJson && sourceRecJson.trim() !== '') {
+                const fromCandidate = JSON.parse(sourceRecJson);
+                if (fromCandidate && typeof fromCandidate === 'object') {
+                    recommendation = fromCandidate;
+                }
+            }
+        }
+        catch (err) {
+            // sourceRecommendationJson is non-empty but malformed — warn and fall through
+            const detail = err instanceof Error ? err.message : String(err);
+            console.warn(`[CandidateIntakeService] sourceRecommendationJson parse failed for candidate ${candidateId}: ${detail}. Falling back to artifact.contentJson.`);
+        }
+        // 4c. Fall back to artifact.contentJson if no valid sourceRecommendationJson
+        if (!recommendation) {
+            try {
+                const parsed = JSON.parse(artifact.contentJson);
+                // DiagnosticianRunner stores raw DiagnosticianOutputV1 (no wrapper)
+                // Manual E2E tests store { recommendation: {...} } wrapper
+                recommendation = parsed.recommendation ?? parsed;
+            }
+            catch (err) {
+                throw new CandidateIntakeError(INTAKE_ERROR_CODES.INPUT_INVALID, `Failed to parse artifact content for candidate ${candidateId}: ${err instanceof Error ? err.message : String(err)}`, { candidateId, cause: err });
+            }
+        }
+        // 5. Build 11-field LedgerPrincipleEntry (E-06)
+        const entry = {
+            id: randomUUID(),
+            title: candidate.title,
+            text: recommendation.text || candidate.description || '',
+            triggerPattern: recommendation.triggerPattern,
+            action: recommendation.action,
+            status: 'probation',
+            evaluability: 'weak_heuristic',
+            sourceRef: `candidate://${candidateId}`,
+            artifactRef: `artifact://${candidate.artifactId}`,
+            taskRef: candidate.taskId ? `task://${candidate.taskId}` : undefined,
+            createdAt: new Date().toISOString(),
+        };
+        // 6. Write to ledger via adapter (E-01, D-09)
+        try {
+            return this.#ledgerAdapter.writeProbationEntry(entry);
+        }
+        catch (err) {
+            if (err instanceof CandidateIntakeError) {
+                throw err;
+            }
+            throw new CandidateIntakeError(INTAKE_ERROR_CODES.LEDGER_WRITE_FAILED, `Failed to write ledger entry for candidate ${candidateId}`, { candidateId, cause: err });
+        }
+    }
+}
+//# sourceMappingURL=candidate-intake-service.js.map

package/dist/runtime-v2/candidate-intake-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-intake-service.js","sourceRoot":"","sources":["../../src/runtime-v2/candidate-intake-service.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,219 @@
+/**
+ * Candidate Intake Contract — M7 schema and interface definitions.
+ *
+ * Defines the intake boundary: input/output schemas, the ledger entry
+ * contract, the LedgerAdapter interface, and intake error codes.
+ *
+ * Implementation logic (CandidateIntakeService) lives in m7-03.
+ *
+ * Non-goals (M7):
+ * - No pain signal auto-trigger (M8)
+ * - No legacy evolution-worker deletion (M9)
+ * - No promote to active principle
+ * - No direct ledger write from SqliteDiagnosticianCommitter
+ *
+ * =============================================================================
+ * FIELD PROVENANCE MAP
+ * =============================================================================
+ *
+ * Every field in LedgerPrincipleEntry flows from exactly one origin:
+ *
+ * │ Field             │ Origin                          │ Reliability │
+ * │-------------------|----------------------------------|-------------│
+ * │ id                │ Service-generated (UUID v4)      │ Always      │
+ * │ title             │ Extracted from artifact          │ Always      │
+ * │ text              │ Extracted from artifact          │ Always      │
+ * │ triggerPattern    │ Extracted from artifact          │ Optional    │
+ * │ action            │ Extracted from artifact          │ Optional    │
+ * │ status            │ Fixed: 'probation'              │ Always      │
+ * │ evaluability      │ Fixed: 'weak_heuristic'          │ Always      │
+ * │ sourceRef         │ Constructed: candidate://<id>   │ Always      │
+ * │ artifactRef       │ Constructed: artifact://<id>    │ Optional    │
+ * │ taskRef           │ Constructed: task://<id>        │ Optional    │
+ * │ createdAt         │ Service-generated (ISO 8601)   │ Always      │
+ *
+ * =============================================================================
+ * LEDGER PRINCIPLE ENTRY — 18 FIELD DEFAULT VALUES
+ * =============================================================================
+ *
+ * When the intake service expands a LedgerPrincipleEntry into a full
+ * LedgerPrinciple, it applies these defaults (m7-03):
+ *
+ *   id:               Generated UUID v4
+ *   title:            From artifact extraction
+ *   text:             From artifact extraction
+ *   triggerPattern:   null (absent if not extracted)
+ *   action:           null (absent if not extracted)
+ *   status:           'probation'
+ *   evaluability:     'weak_heuristic'
+ *   sourceRef:        'candidate://<candidateId>'
+ *   artifactRef:      'artifact://<artifactId>' (if artifactId known)
+ *   taskRef:          null (absent in M7; M8+ may populate)
+ *   createdAt:        new Date().toISOString()
+ *
+ *   -- M7 does NOT set (M8/M9 concerns):
+ *   promotedAt:       undefined
+ *   promotedBy:       undefined
+ *   archivedAt:       undefined
+ *   archivedBy:       undefined
+ *   archivedReason:   undefined
+ *   experimentTags:   undefined
+ *   principleNotes:   undefined
+ *   reviewCycle:      undefined
+ */
+import { type Static } from '@sinclair/typebox';
+export declare const CandidateIntakeInputSchema: import("@sinclair/typebox").TObject<{
+    candidateId: import("@sinclair/typebox").TString;
+    workspaceDir: import("@sinclair/typebox").TString;
+}>;
+export type CandidateIntakeInput = Static<typeof CandidateIntakeInputSchema>;
+export declare const CandidateIntakeOutputSchema: import("@sinclair/typebox").TObject<{
+    candidateId: import("@sinclair/typebox").TString;
+    artifactId: import("@sinclair/typebox").TString;
+    ledgerRef: import("@sinclair/typebox").TString;
+    status: import("@sinclair/typebox").TLiteral<"consumed">;
+}>;
+export type CandidateIntakeOutput = Static<typeof CandidateIntakeOutputSchema>;
+/**
+ * Ledger principle entry written during candidate intake.
+ *
+ * Provenance annotations (@provenance):
+ *
+ * @provenance id               — Service-generated UUID v4. Never from artifact.
+ *                               Generated by: CandidateIntakeService (m7-03).
+ *
+ * @provenance title            — Extracted from artifact by CandidateIntakeService.
+ *                               Sourced from: artifact principle text/title.
+ *
+ * @provenance text             — Extracted from artifact by CandidateIntakeService.
+ *                               Sourced from: artifact principle body content.
+ *
+ * @provenance triggerPattern    — Extracted from artifact (optional).
+ *                               @nullable null when artifact provides no trigger.
+ *
+ * @provenance action            — Extracted from artifact (optional).
+ *                               @nullable null when artifact provides no action.
+ *
+ * @provenance status            — Fixed value. Always 'probation' on intake.
+ *                               Never from artifact. Governed by promotion gate (M8).
+ *
+ * @provenance evaluability      — Fixed value. Always 'weak_heuristic' on intake.
+ *                               Never from artifact. Governed by evaluation strategy (M8).
+ *
+ * @provenance sourceRef         — Constructed by service. Idempotency key.
+ *                               Format: `candidate://<candidateId>`
+ *                               @provenance Always constructed from input candidateId.
+ *                               NOT derived from artifact artifactId (D-11).
+ *
+ * @provenance artifactRef       — Constructed by service, only if artifactId known.
+ *                               Format: `artifact://<artifactId>`
+ *                               @provenance Derived from artifactId in intake input.
+ *                               @nullable Omit from entry when artifactId is not available.
+ *                               @tag traceability — NOT an idempotency key.
+ *
+ * @provenance taskRef           — Constructed by service (optional, M7 not populated).
+ *                               Format: `task://<taskId>`
+ *                               @provenance Reserved for M8+ task linking.
+ *                               @nullable Omit from entry in M7.
+ *                               @tag traceability — NOT an idempotency key.
+ *
+ * @provenance createdAt         — Service-generated ISO 8601 timestamp.
+ *                               Generated by: CandidateIntakeService (m7-03).
+ *                               NOT from artifact.
+ */
+export declare const LedgerPrincipleEntrySchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    title: import("@sinclair/typebox").TString;
+    text: import("@sinclair/typebox").TString;
+    triggerPattern: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    action: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    status: import("@sinclair/typebox").TLiteral<"probation">;
+    evaluability: import("@sinclair/typebox").TLiteral<"weak_heuristic">;
+    sourceRef: import("@sinclair/typebox").TString;
+    artifactRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    taskRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    createdAt: import("@sinclair/typebox").TString;
+}>;
+export type LedgerPrincipleEntry = Static<typeof LedgerPrincipleEntrySchema>;
+/**
+ * Error codes for candidate intake operations.
+ *
+ * @error INPUT_INVALID           — Input validation failed (missing/invalid fields).
+ * @error CANDIDATE_NOT_FOUND    — Candidate ID does not exist in workspace.
+ * @error ARTIFACT_NOT_FOUND     — Artifact ID does not exist in workspace.
+ * @error CANDIDATE_ALREADY_CONSUMED — Ledger entry exists for this candidate;
+ *                                  returned as idempotent success (D-10),
+ *                                  NOT an error. This code is reserved for
+ *                                  data-corruption detection: DB claims
+ *                                  consumed but no ledger entry found.
+ * @error LEDGER_WRITE_FAILED     — Ledger write operation failed.
+ */
+export declare const INTAKE_ERROR_CODES: {
+    readonly CANDIDATE_NOT_FOUND: "candidate_not_found";
+    readonly CANDIDATE_ALREADY_CONSUMED: "candidate_already_consumed";
+    readonly ARTIFACT_NOT_FOUND: "artifact_not_found";
+    readonly LEDGER_WRITE_FAILED: "ledger_write_failed";
+    readonly INPUT_INVALID: "input_invalid";
+};
+/**
+ * Candidate intake error with structured code and optional context.
+ *
+ * Use INTAKE_ERROR_CODES for the code value.
+ *
+ * @example
+ * throw new CandidateIntakeError(INTAKE_ERROR_CODES.CANDIDATE_NOT_FOUND, 'Candidate cand-1 not found');
+ *
+ * @example
+ * throw new CandidateIntakeError(INTAKE_ERROR_CODES.LEDGER_WRITE_FAILED, 'Ledger write failed', { cause: err });
+ */
+export declare class CandidateIntakeError extends Error {
+    readonly code: (typeof INTAKE_ERROR_CODES)[keyof typeof INTAKE_ERROR_CODES];
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(code: (typeof INTAKE_ERROR_CODES)[keyof typeof INTAKE_ERROR_CODES], message: string, context?: Record<string, unknown> | undefined);
+}
+/**
+ * Abstraction for writing probation principles to the ledger.
+ * Implementations write to file-based ledger (openclaw-plugin) or test doubles.
+ *
+ * Design notes:
+ * - LedgerAdapter is defined in principles-core (shared contract).
+ * - Implementations live in openclaw-plugin (principle-tree-ledger adapter).
+ * - The interface uses LedgerPrincipleEntry (11-field contract), NOT the
+ *   full LedgerPrinciple (18+ fields). Full expansion happens inside
+ *   the adapter's writeProbationEntry implementation (m7-02).
+ */
+export interface LedgerAdapter {
+    /**
+     * Write a probation principle entry to the ledger.
+     *
+     * Implementation requirements (m7-02):
+     * 1. Expand the 11-field LedgerPrincipleEntry into a full LedgerPrinciple
+     *    by applying the documented default values (see LedgerPrincipleEntrySchema
+     *    block above and the 18-field default values list).
+     * 2. Call addPrincipleToLedger(stateDir, ledgerPrinciple).
+     * 3. Return the LedgerPrincipleEntry as-is (passthrough for idempotency tracking).
+     *
+     * @param entry — Full LedgerPrincipleEntry with id and createdAt already populated
+     *                by the intake service. The adapter does NOT generate these fields.
+     * @returns The same entry (passthrough) for ledgerRef construction by the caller.
+     * @throws CandidateIntakeError with code LEDGER_WRITE_FAILED if the write fails.
+     */
+    writeProbationEntry(entry: LedgerPrincipleEntry): LedgerPrincipleEntry;
+    /**
+     * Check if a ledger entry already exists for a given candidate.
+     *
+     * **Matching rule (D-11):** Scan `tree.principles` for an entry whose
+     * `sourceRef` field matches `'candidate://<candidateId>'`.
+     *
+     * NOT artifact-based: one artifact can produce multiple candidates (M5).
+     * Each candidate must have its own unique ledger entry retrievable by this method.
+     * Using artifactRef as the key would cause collisions when a single artifact
+     * generates N candidates — all N entries would share the same artifactRef,
+     * making existsForCandidate ambiguous.
+     *
+     * @param candidateId — The candidate ID to check for existing ledger entries.
+     * @returns The existing LedgerPrincipleEntry if found, null otherwise.
+     */
+    existsForCandidate(candidateId: string): LedgerPrincipleEntry | null;
+}
+//# sourceMappingURL=candidate-intake.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-intake.d.ts","sourceRoot":"","sources":["../../src/runtime-v2/candidate-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAItD,eAAO,MAAM,0BAA0B;;;EAGrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE7E,eAAO,MAAM,2BAA2B;;;;;EAKtC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;EAYrC,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAI7E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,kBAAkB;;;;;;CAMrB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;aAE3B,IAAI,EAAE,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC;aAElE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBAFjC,IAAI,EAAE,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,EAClF,OAAO,EAAE,MAAM,EACC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAA;CAKpD;AAID;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;IAEvE;;;;;;;;;;;;;;OAcG;IACH,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAAC;CACtE"}

package/dist/runtime-v2/candidate-intake.js

@@ -0,0 +1,178 @@
+/**
+ * Candidate Intake Contract — M7 schema and interface definitions.
+ *
+ * Defines the intake boundary: input/output schemas, the ledger entry
+ * contract, the LedgerAdapter interface, and intake error codes.
+ *
+ * Implementation logic (CandidateIntakeService) lives in m7-03.
+ *
+ * Non-goals (M7):
+ * - No pain signal auto-trigger (M8)
+ * - No legacy evolution-worker deletion (M9)
+ * - No promote to active principle
+ * - No direct ledger write from SqliteDiagnosticianCommitter
+ *
+ * =============================================================================
+ * FIELD PROVENANCE MAP
+ * =============================================================================
+ *
+ * Every field in LedgerPrincipleEntry flows from exactly one origin:
+ *
+ * │ Field             │ Origin                          │ Reliability │
+ * │-------------------|----------------------------------|-------------│
+ * │ id                │ Service-generated (UUID v4)      │ Always      │
+ * │ title             │ Extracted from artifact          │ Always      │
+ * │ text              │ Extracted from artifact          │ Always      │
+ * │ triggerPattern    │ Extracted from artifact          │ Optional    │
+ * │ action            │ Extracted from artifact          │ Optional    │
+ * │ status            │ Fixed: 'probation'              │ Always      │
+ * │ evaluability      │ Fixed: 'weak_heuristic'          │ Always      │
+ * │ sourceRef         │ Constructed: candidate://<id>   │ Always      │
+ * │ artifactRef       │ Constructed: artifact://<id>    │ Optional    │
+ * │ taskRef           │ Constructed: task://<id>        │ Optional    │
+ * │ createdAt         │ Service-generated (ISO 8601)   │ Always      │
+ *
+ * =============================================================================
+ * LEDGER PRINCIPLE ENTRY — 18 FIELD DEFAULT VALUES
+ * =============================================================================
+ *
+ * When the intake service expands a LedgerPrincipleEntry into a full
+ * LedgerPrinciple, it applies these defaults (m7-03):
+ *
+ *   id:               Generated UUID v4
+ *   title:            From artifact extraction
+ *   text:             From artifact extraction
+ *   triggerPattern:   null (absent if not extracted)
+ *   action:           null (absent if not extracted)
+ *   status:           'probation'
+ *   evaluability:     'weak_heuristic'
+ *   sourceRef:        'candidate://<candidateId>'
+ *   artifactRef:      'artifact://<artifactId>' (if artifactId known)
+ *   taskRef:          null (absent in M7; M8+ may populate)
+ *   createdAt:        new Date().toISOString()
+ *
+ *   -- M7 does NOT set (M8/M9 concerns):
+ *   promotedAt:       undefined
+ *   promotedBy:       undefined
+ *   archivedAt:       undefined
+ *   archivedBy:       undefined
+ *   archivedReason:   undefined
+ *   experimentTags:   undefined
+ *   principleNotes:   undefined
+ *   reviewCycle:      undefined
+ */
+import { Type } from '@sinclair/typebox';
+// ── Schema ────────────────────────────────────────────────────────────────
+export const CandidateIntakeInputSchema = Type.Object({
+    candidateId: Type.String({ minLength: 1 }),
+    workspaceDir: Type.String({ minLength: 1 }),
+});
+export const CandidateIntakeOutputSchema = Type.Object({
+    candidateId: Type.String(),
+    artifactId: Type.String(),
+    ledgerRef: Type.String(),
+    status: Type.Literal('consumed'),
+});
+/**
+ * Ledger principle entry written during candidate intake.
+ *
+ * Provenance annotations (@provenance):
+ *
+ * @provenance id               — Service-generated UUID v4. Never from artifact.
+ *                               Generated by: CandidateIntakeService (m7-03).
+ *
+ * @provenance title            — Extracted from artifact by CandidateIntakeService.
+ *                               Sourced from: artifact principle text/title.
+ *
+ * @provenance text             — Extracted from artifact by CandidateIntakeService.
+ *                               Sourced from: artifact principle body content.
+ *
+ * @provenance triggerPattern    — Extracted from artifact (optional).
+ *                               @nullable null when artifact provides no trigger.
+ *
+ * @provenance action            — Extracted from artifact (optional).
+ *                               @nullable null when artifact provides no action.
+ *
+ * @provenance status            — Fixed value. Always 'probation' on intake.
+ *                               Never from artifact. Governed by promotion gate (M8).
+ *
+ * @provenance evaluability      — Fixed value. Always 'weak_heuristic' on intake.
+ *                               Never from artifact. Governed by evaluation strategy (M8).
+ *
+ * @provenance sourceRef         — Constructed by service. Idempotency key.
+ *                               Format: `candidate://<candidateId>`
+ *                               @provenance Always constructed from input candidateId.
+ *                               NOT derived from artifact artifactId (D-11).
+ *
+ * @provenance artifactRef       — Constructed by service, only if artifactId known.
+ *                               Format: `artifact://<artifactId>`
+ *                               @provenance Derived from artifactId in intake input.
+ *                               @nullable Omit from entry when artifactId is not available.
+ *                               @tag traceability — NOT an idempotency key.
+ *
+ * @provenance taskRef           — Constructed by service (optional, M7 not populated).
+ *                               Format: `task://<taskId>`
+ *                               @provenance Reserved for M8+ task linking.
+ *                               @nullable Omit from entry in M7.
+ *                               @tag traceability — NOT an idempotency key.
+ *
+ * @provenance createdAt         — Service-generated ISO 8601 timestamp.
+ *                               Generated by: CandidateIntakeService (m7-03).
+ *                               NOT from artifact.
+ */
+export const LedgerPrincipleEntrySchema = Type.Object({
+    id: Type.String(),
+    title: Type.String(),
+    text: Type.String(),
+    triggerPattern: Type.Optional(Type.String()),
+    action: Type.Optional(Type.String()),
+    status: Type.Literal('probation'),
+    evaluability: Type.Literal('weak_heuristic'),
+    sourceRef: Type.String(), // candidate://<candidateId> — idempotency key
+    artifactRef: Type.Optional(Type.String()), // artifact://<artifactId> — traceability only
+    taskRef: Type.Optional(Type.String()), // task://<taskId> — traceability only
+    createdAt: Type.String(),
+});
+// ── Errors ───────────────────────────────────────────────────────────────
+/**
+ * Error codes for candidate intake operations.
+ *
+ * @error INPUT_INVALID           — Input validation failed (missing/invalid fields).
+ * @error CANDIDATE_NOT_FOUND    — Candidate ID does not exist in workspace.
+ * @error ARTIFACT_NOT_FOUND     — Artifact ID does not exist in workspace.
+ * @error CANDIDATE_ALREADY_CONSUMED — Ledger entry exists for this candidate;
+ *                                  returned as idempotent success (D-10),
+ *                                  NOT an error. This code is reserved for
+ *                                  data-corruption detection: DB claims
+ *                                  consumed but no ledger entry found.
+ * @error LEDGER_WRITE_FAILED     — Ledger write operation failed.
+ */
+export const INTAKE_ERROR_CODES = {
+    CANDIDATE_NOT_FOUND: 'candidate_not_found',
+    CANDIDATE_ALREADY_CONSUMED: 'candidate_already_consumed',
+    ARTIFACT_NOT_FOUND: 'artifact_not_found',
+    LEDGER_WRITE_FAILED: 'ledger_write_failed',
+    INPUT_INVALID: 'input_invalid',
+};
+/**
+ * Candidate intake error with structured code and optional context.
+ *
+ * Use INTAKE_ERROR_CODES for the code value.
+ *
+ * @example
+ * throw new CandidateIntakeError(INTAKE_ERROR_CODES.CANDIDATE_NOT_FOUND, 'Candidate cand-1 not found');
+ *
+ * @example
+ * throw new CandidateIntakeError(INTAKE_ERROR_CODES.LEDGER_WRITE_FAILED, 'Ledger write failed', { cause: err });
+ */
+export class CandidateIntakeError extends Error {
+    code;
+    context;
+    constructor(code, message, context) {
+        super(message);
+        this.code = code;
+        this.context = context;
+        this.name = 'CandidateIntakeError';
+    }
+}
+//# sourceMappingURL=candidate-intake.js.map

package/dist/runtime-v2/candidate-intake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-intake.js","sourceRoot":"","sources":["../../src/runtime-v2/candidate-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,OAAO,EAAE,IAAI,EAAe,MAAM,mBAAmB,CAAC;AAEtD,6EAA6E;AAE7E,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,MAAM,CAAC;IACpD,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IAC1C,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;CAC5C,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC,MAAM,CAAC;IACrD,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE;IAC1B,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE;IACzB,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;IACxB,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;CACjC,CAAC,CAAC;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC,MAAM,CAAC;IACpD,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE;IACjB,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE;IACpB,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE;IACnB,cAAc,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC5C,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IACpC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC;IACjC,YAAY,EAAE,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC;IAC5C,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE,EAA2B,8CAA8C;IACjG,WAAW,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAY,8CAA8C;IACnG,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAe,sCAAsC;IAC1F,SAAS,EAAE,IAAI,CAAC,MAAM,EAAE;CACzB,CAAC,CAAC;AAIH,4EAA4E;AAE5E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,mBAAmB,EAAE,qBAAqB;IAC1C,0BAA0B,EAAE,4BAA4B;IACxD,kBAAkB,EAAE,oBAAoB;IACxC,mBAAmB,EAAE,qBAAqB;IAC1C,aAAa,EAAE,eAAe;CACtB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAE3B;IAEA;IAHlB,YACkB,IAAkE,EAClF,OAAe,EACC,OAAiC;QAEjD,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAA8D;QAElE,YAAO,GAAP,OAAO,CAA0B;QAGjD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF"}

package/dist/runtime-v2/cli/diagnose.d.ts

@@ -0,0 +1,127 @@
+/**
+ * CLI surface for diagnostician execution.
+ *
+ * Per D-02: Library function exports, no bin scripts, no CLI framework dependency.
+ * External code (e.g., OpenClaw plugin) imports and calls these functions.
+ *
+ * Per D-03: status() returns TaskRecord key fields only (taskId, status, attemptCount, maxAttempts, lastError).
+ * No Run history.
+ */
+import type { RuntimeStateManager, CandidateRecord } from '../store/runtime-state-manager.js';
+import type { DiagnosticianRunner } from '../runner/diagnostician-runner.js';
+import type { RunnerResult } from '../runner/runner-result.js';
+import type { TaskRecord } from '../task-status.js';
+import type { LedgerAdapter } from '../candidate-intake.js';
+/** Options for pd candidate list */
+export interface CandidateListOptions {
+    taskId: string;
+    stateManager: RuntimeStateManager;
+}
+/** Result for pd candidate list */
+export interface CandidateListResult {
+    readonly taskId: string;
+    readonly candidates: readonly CandidateRecord[];
+}
+/** Options for pd candidate show */
+export interface CandidateShowOptions {
+    candidateId: string;
+    stateManager: RuntimeStateManager;
+}
+/** Result for pd candidate show */
+export interface CandidateShowResult {
+    readonly candidateId: string;
+    readonly artifactId: string;
+    readonly taskId: string;
+    readonly title: string;
+    readonly description: string;
+    readonly confidence: number | null;
+    readonly sourceRunId: string;
+    readonly status: 'pending' | 'consumed' | 'expired';
+    readonly createdAt: string;
+    readonly ledgerEntryId: string | null;
+}
+/** Options for pd artifact show */
+export interface ArtifactShowOptions {
+    artifactId: string;
+    stateManager: RuntimeStateManager;
+}
+/** Result for pd artifact show */
+export interface ArtifactShowResult {
+    readonly artifactId: string;
+    readonly runId: string;
+    readonly taskId: string;
+    readonly artifactKind: string;
+    readonly contentJson: string;
+    readonly createdAt: string;
+    readonly candidates: readonly CandidateRecord[];
+}
+/** Options for the run() CLI function. */
+export interface DiagnoseRunOptions {
+    /** Task ID to execute diagnostician for. */
+    taskId: string;
+    /** Initialized RuntimeStateManager instance. */
+    stateManager: RuntimeStateManager;
+    /** DiagnosticianRunner instance (already configured with deps). */
+    runner: DiagnosticianRunner;
+}
+/** Options for the status() CLI function. */
+export interface DiagnoseStatusOptions {
+    /** Task ID to inspect. */
+    taskId: string;
+    /** Initialized RuntimeStateManager instance. */
+    stateManager: RuntimeStateManager;
+}
+/** Structured status result per D-03, extended per CLIV-04 for commit/candidate info. */
+export interface DiagnoseStatusResult {
+    readonly taskId: string;
+    readonly status: TaskRecord['status'];
+    readonly attemptCount: number;
+    readonly maxAttempts: number;
+    readonly lastError: TaskRecord['lastError'];
+    /** Populated only when status is 'succeeded' — the committed commit ID */
+    readonly commitId: string | null;
+    /** Populated only when status is 'succeeded' — the committed artifact ID */
+    readonly artifactId: string | null;
+    /** Populated only when status is 'succeeded' — number of candidates registered */
+    readonly candidateCount: number | null;
+}
+/**
+ * Execute the diagnostician runner for a task.
+ *
+ * Thin wrapper over DiagnosticianRunner.run().
+ * Returns the raw RunnerResult for full visibility.
+ */
+export declare function run(options: DiagnoseRunOptions): Promise<RunnerResult>;
+/**
+ * Inspect diagnostician task status.
+ *
+ * Per D-03: Returns key TaskRecord fields only.
+ * Returns null if the task does not exist.
+ */
+export declare function status(options: DiagnoseStatusOptions): Promise<DiagnoseStatusResult | null>;
+/**
+ * List principle candidates for a task.
+ *
+ * Per CLIV-01: pd candidate list --task-id <taskId>
+ * Per D-05: joins through tasks→runs→commits→principle_candidates
+ */
+export declare function candidateList(options: CandidateListOptions): Promise<CandidateListResult>;
+/**
+ * Show detail for a single candidate.
+ *
+ * Per CLIV-02: pd candidate show <candidateId>
+ * Returns title, description, confidence, source (runId), status
+ * Returns null if candidate not found.
+ */
+export declare function candidateShow(options: CandidateShowOptions & {
+    ledgerAdapter?: LedgerAdapter;
+}): Promise<CandidateShowResult | null>;
+/**
+ * Show artifact content and its associated candidates.
+ *
+ * Per CLIV-03: pd artifact show <artifactId>
+ * Per D-06: single query with JOIN, returns artifact + inline candidates array
+ * Returns null if artifact not found.
+ */
+export declare function artifactShow(options: ArtifactShowOptions): Promise<ArtifactShowResult | null>;
+//# sourceMappingURL=diagnose.d.ts.map