onto-mcp 0.4.12 → 0.4.13

package/dist/core-runtime/onboard/register.js

@@ -1,5 +1,6 @@
 import { ALL_HOST_IDS, } from "./types.js";
 import { getDefaultHostTargets } from "./host-target.js";
+import { discoverClaudeProfiles } from "./claude-profile-scan.js";
 import { promptMultiSelect, promptYesNo } from "./prompt.js";
 const USAGE = [
     "Usage: onto register [options]",
@@ -20,6 +21,9 @@ const USAGE = [
     "  --command <cmd>    Executable the host launches (default: onto)",
     "  --claude-config-dir <path>  Target a Claude Code profile (sets",
     "                     CLAUDE_CONFIG_DIR; default: ambient env or ~/.claude)",
+    "  --all-claude-profiles  Auto-discover every Claude Code config dir under",
+    "                     home (~/.claude and ~/.claude-*) and register each",
+    "                     (mutually exclusive with --claude-config-dir)",
     "  --help, -h         Show this help",
 ].join("\n");
 export function parseRegisterArgs(argv) {
@@ -33,6 +37,7 @@ export function parseRegisterArgs(argv) {
         name: "onto",
         command: "onto",
         claudeConfigDir: undefined,
+        allClaudeProfiles: false,
         unknownFlags: [],
         invalidHosts: [],
     };
@@ -82,6 +87,9 @@ export function parseRegisterArgs(argv) {
             case "--claude-config-dir":
                 parsed.claudeConfigDir = argv[++i] ?? parsed.claudeConfigDir;
                 break;
+            case "--all-claude-profiles":
+                parsed.allClaudeProfiles = true;
+                break;
             default:
                 parsed.unknownFlags.push(arg);
                 break;
@@ -89,12 +97,20 @@ export function parseRegisterArgs(argv) {
     }
     return parsed;
 }
-function resolveSelection(parsed, targets) {
+/** Unique selection identity for a target (host *instance*, not just kind). */
+function targetKey(target) {
+    return target.key ?? target.id;
+}
+/**
+ * Flag-driven selection by host *kind* (`id`). `--hosts claude-code` therefore
+ * selects every Claude Code profile target when several are expanded.
+ */
+function resolveSelectedTargets(parsed, targets) {
     if (parsed.hosts === "all")
-        return targets.map((t) => t.id);
+        return targets;
     if (Array.isArray(parsed.hosts)) {
         const requested = new Set(parsed.hosts);
-        return targets.map((t) => t.id).filter((id) => requested.has(id));
+        return targets.filter((t) => requested.has(t.id));
     }
     return [];
 }
@@ -123,6 +139,29 @@ function printResults(results) {
         console.log(`  • ${result.displayName}: ${result.outcome} — ${result.detail}`);
     }
 }
+/**
+ * Build the default host targets honoring profile flags. When
+ * `--all-claude-profiles` is set, discover every Claude Code config dir under
+ * home and expand Claude Code into one target per profile; if none are found,
+ * fall back to the single default target with a note.
+ */
+function buildDefaultTargets(parsed, deps) {
+    if (parsed.allClaudeProfiles) {
+        const discover = deps.discoverClaudeProfiles ??
+            (() => {
+                const env = process.env.CLAUDE_CONFIG_DIR;
+                return discoverClaudeProfiles(env ? { configDirEnv: env } : {});
+            });
+        const profiles = discover();
+        if (profiles.length > 0) {
+            return getDefaultHostTargets({ claudeProfiles: profiles });
+        }
+        console.error("[onto register] --all-claude-profiles: no Claude Code config dirs found " +
+            "under home; falling back to the default profile.");
+        return getDefaultHostTargets({});
+    }
+    return getDefaultHostTargets(parsed.claudeConfigDir ? { claudeConfigDir: parsed.claudeConfigDir } : {});
+}
 export async function runRegister(argv, deps = {}) {
     const parsed = parseRegisterArgs(argv);
     if (parsed.help) {
@@ -139,8 +178,12 @@ export async function runRegister(argv, deps = {}) {
             `Valid: ${ALL_HOST_IDS.join(", ")}`);
         return 1;
     }
-    const targets = deps.targets ??
-        getDefaultHostTargets(parsed.claudeConfigDir ? { claudeConfigDir: parsed.claudeConfigDir } : {});
+    if (parsed.allClaudeProfiles && parsed.claudeConfigDir) {
+        console.error("[onto register] Use either --all-claude-profiles or --claude-config-dir, " +
+            "not both.");
+        return 1;
+    }
+    const targets = deps.targets ?? buildDefaultTargets(parsed, deps);
     const isTty = deps.isTty ?? Boolean(process.stdin.isTTY);
     if (parsed.list) {
         console.log("Host detection:");
@@ -155,7 +198,7 @@ export async function runRegister(argv, deps = {}) {
         args: ["mcp"],
     };
     // Determine which hosts to register.
-    let selected = resolveSelection(parsed, targets);
+    let selectedTargets = resolveSelectedTargets(parsed, targets);
     const selectionGivenByFlag = parsed.hosts !== undefined;
     if (!selectionGivenByFlag) {
         if (!isTty) {
@@ -163,19 +206,18 @@ export async function runRegister(argv, deps = {}) {
                 "(interactive selection requires a terminal).");
             return 1;
         }
-        const defaults = targets.filter((t) => t.detect() !== "absent").map((t) => t.id);
+        const defaults = targets.filter((t) => t.detect() !== "absent").map(targetKey);
         const chosen = await promptMultiSelect("Select hosts to register onto with:", targets.map((t) => ({
-            id: t.id,
+            id: targetKey(t),
             label: t.displayName,
             detail: detectionLabel(t.detect()),
-        })), defaults.length > 0 ? defaults : targets.map((t) => t.id));
-        selected = targets.map((t) => t.id).filter((id) => chosen.includes(id));
+        })), defaults.length > 0 ? defaults : targets.map(targetKey));
+        selectedTargets = targets.filter((t) => chosen.includes(targetKey(t)));
     }
-    if (selected.length === 0) {
+    if (selectedTargets.length === 0) {
         console.error("[onto register] No hosts selected. Nothing to do.");
         return 1;
     }
-    const selectedTargets = targets.filter((t) => selected.includes(t.id));
     const options = { force: parsed.force, dryRun: parsed.dryRun };
     const plans = selectedTargets.map((t) => t.plan(entry, options));
     printPlans(plans);

package/dist/core-runtime/pipeline-execution-ledger.js

@@ -41,6 +41,16 @@ export function isTrustedLedgerUnit(unit) {
         unit.trustStatus === "trusted" &&
         hasAllRequiredOutputHashes(unit));
 }
+/**
+ * Trusted output OR terminally resolved (demoted complete-with-failure):
+ * either way the unit owes no further dispatch. Frontier and convergence
+ * consumers use this predicate; artifact-preservation consumers keep using
+ * {@link isTrustedLedgerUnit} — a resolved unit has no trusted output to
+ * preserve or to consume downstream.
+ */
+export function isResolvedLedgerUnit(unit) {
+    return unit.resolution === "demoted" || isTrustedLedgerUnit(unit);
+}
 export function firstUntrustedRequiredUnit(ledger) {
     return ledger.units.find((unit) => !isTrustedLedgerUnit(unit)) ?? null;
 }

package/dist/core-runtime/reconstruct/artifact-types.js

@@ -29,6 +29,16 @@ export const RECONSTRUCT_STAGE_IDS = [
     "source_observation_reentry_validation",
     "source_observation_lineage_index",
     "source_observation_lineage_index_validation",
+    // P1-C2 leaf-read: the first LLM-touch (capture over structure-incomplete spreadsheet regions).
+    // Owns its own telemetry unit so a leaf-read total-failure is recorded, not silently degraded
+    // (the defect this stage id fixes: "leaf-read" had no telemetry unit → callLlmRecorded threw
+    // before the LLM call → R9 swallowed it → zero capture, forever). Runs after the lineage index
+    // exists and before purpose-candidate authoring.
+    "leaf_read",
+    // Layer-2 semantic_map stage (wiring design 20260702 §7-W3): default-off; runs right after
+    // leaf_read; its always-written census is the step's artifact ref (skipped when the author lacks
+    // the synthesizeSemanticMapNode/verifySemanticMapBoundary capability pair).
+    "semantic_map",
     "source_purpose_candidates",
     "source_purpose_candidates_validation",
     "purpose_confirmation",
@@ -39,6 +49,7 @@ export const RECONSTRUCT_STAGE_IDS = [
     "candidate_disposition_validation",
     "seed_authoring_readiness",
     "seed_authoring_readiness_validation",
+    "seed_stage_prompt_source_observations",
     "ontology_seed",
     "ontology_seed_validation",
     "material_admission_validation",
@@ -62,6 +73,14 @@ export const RECONSTRUCT_STAGE_IDS = [
     "maturation_baseline_validation",
     "baseline_actionability_matrix",
     "baseline_actionability_matrix_validation",
+    // Maturation value-read cut: the LLM-touch stage that reads authorized runtime-target
+    // cell values to discharge value-dependent limitations on baseline matrix rows. A single
+    // stage id (leaf_read precedent) — discharge validation is an embedded self-validation
+    // step, so terminal run-manifest validation needs exactly one matching manifest step
+    // (design §13.5 F3). Runs after the baseline matrix is produced and before the question
+    // frontier, so its value-grounded discharge reaches the actionability matrix directly
+    // without waking the empty frontier path.
+    "maturation_value_read",
     "maturation_question_frontier",
     "maturation_question_frontier_validation",
     "maturation_closure_frontier",
@@ -100,3 +119,19 @@ export const RECONSTRUCT_STAGE_IDS = [
     "record_assembly",
     "post_publication_run_manifest_validation",
 ];
+/**
+ * The conditional stages that can legitimately run-but-produce-nothing yet leave no
+ * artifact-ref witness of their own (unlike leaf_read / maturation_value_read, which always
+ * write a census when they run). Canonical single source shared by the graceful-terminal
+ * manifest builder (createRunManifest) and the reachability validator (validateReconstructRunManifest):
+ * on a graceful-terminal manifest these are the only stages permitted `skip_kind:
+ * "legit_conditional"`, and only when the reachability witness (ReconstructSourceObservationLineageCensus)
+ * confirms they ran and legitimately produced nothing. See reachability-manifest design v2 §2–§4.
+ */
+export const WITNESS_LESS_CONDITIONAL_STAGE_IDS = [
+    "source_observation_delta",
+    "source_observation_delta_validation",
+    "source_observation_reentry_validation",
+    "source_observation_lineage_index",
+    "source_observation_lineage_index_validation",
+];

package/dist/core-runtime/reconstruct/claim-projection-validation.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { atomicWriteYamlDocument as writeYamlDocument } from "../artifact-io.js";
+import { assertObligation } from "./obligation-assertion.js";
 const PROJECTION_SURFACES = [
     "status",
     "result",
@@ -389,6 +390,21 @@ function sameJson(left, right) {
 }
 export function validateClaimProjection(args) {
     const violations = [];
+    // G(a) slice 23 — record the obligations this validator FULLY enforces with a complete unconditional
+    // check (RECORD 2/9). claim-projection's other unconditional checks are only PARTIAL — its strong
+    // enforcement is the gated `expectedClaimProjection` derived-match — so 7 stay parked (see obligation-
+    // coverage-ledger.yaml notes): governance-bounding is PARTIAL (rollback_quota_incident_governance
+    // unchecked); two material-kind-support lineage obligations are GATED on optional targetMaterialProfile
+    // +validation args (slice-18/22); and codex R1 parked four more as partial — blocked-recovery keys only
+    // on claim_level==blocked (misses material_kind_support machine_status==blocked), cite-validation-refs
+    // is presence-only without the optional expectedRequiredValidationRefs, surfaces-present is presence-only
+    // (contract design ~1172 wants ONE row per surface), and claim/decision/actionability alignment is
+    // one-directional (a continue+ready row passes). The two RECORDED checks fully enforce their named scope
+    // whenever a material_kind_support row is present (the required surface). Stamped before any per-row
+    // guard so the recorder fires on zero-row input.
+    const assertedObligationIds = [];
+    assertObligation(assertedObligationIds, "reject_unwired_material_kind_support_levels_above_profile_supported");
+    assertObligation(assertedObligationIds, "validate_material_kind_support_row_uses_capability_claim_not_actionability_claim");
     const seenIds = new Set();
     const surfaces = new Set();
     const decisionStateCounts = Object.fromEntries(DECISION_STATES.map((state) => [state, 0]));
@@ -725,6 +741,7 @@ export function validateClaimProjection(args) {
         validation_results: violations.length === 0
             ? ["claim_projection_valid"]
             : ["claim_projection_invalid"],
+        asserted_obligation_ids: assertedObligationIds,
         violations,
     };
 }

package/dist/core-runtime/reconstruct/competency-projection-contract.js

@@ -0,0 +1,63 @@
+/**
+ * Single source of truth for the competency-question assessment prompt-projection
+ * contract: the field set + budget constants that define the host-LLM assessment
+ * prompt surface. The reconstruct runtime (run.ts) imports the contract fn + budgets
+ * from here, and the G(b) parity guard (scripts/check-prompt-projection-parity.ts)
+ * asserts the registry node `prompt_projection_contracts.competency_question_assessment`
+ * declares exactly this surface — so a field/budget change cannot silently drift from
+ * its registry declaration (INV-SCHEMA-1). Side-effect-free.
+ */
+export const COMPETENCY_QUESTION_ASSESSMENT_PROJECTION_CONTRACT_VERSION = 
+// v3 added the cited source-evidence bodies surface (source_evidence); v4 bounded it to a
+// deterministic per-payload SERIALIZED-SIZE budget; v5 (M2) derives that evidence reserve
+// from the WHOLE prompt budget per batch (= prompt_char_limit − measured non-evidence
+// payload − margin) instead of a static budget, so the evidence uses the room actually
+// left under the 50K cap. v6 scopes the claim_realization_map projection to each batch's
+// linked claims (questions' linked_claim_ids) instead of embedding the WHOLE map in every
+// batch — the whole-map fixed overhead grew unbounded with claim count and overflowed the
+// 50K cap before M3 (a claim-count-dependent pre-dispatch hard stop). Each version +
+// contract change rotates the reuse-match hash so resume mode cannot reuse an assessment
+// authored under a different (or content-blind, pre-v3) evidence projection of the same
+// sources — in particular a v5 assessment authored under the unscoped whole-map projection.
+"competency_question_assessment_compact_projection:v6";
+export const COMPETENCY_QUESTION_ASSESSMENT_PROMPT_CHAR_LIMIT = 50_000;
+// Per-observation excerpt budget for the cited source-evidence bodies projected
+// into the assessment prompt, so answer_status is judged on evidence content
+// rather than observation-id labels alone.
+// Per-observation excerpt budget on each cited evidence body, kept as a real pre-cap so one
+// huge observation (e.g. a streaming spreadsheet) cannot eat the whole evidence reserve.
+export const COMPETENCY_QUESTION_ASSESSMENT_EVIDENCE_EXCERPT_LIMIT = 4_000;
+// Margin held back from the prompt cap when deriving the per-batch evidence reserve and when
+// building batches, so the projection metadata that grows as evidence is added still fits.
+export const COMPETENCY_QUESTION_ASSESSMENT_BATCH_BUILD_BUDGET_RESERVE_CHARS = 1000;
+export function competencyQuestionAssessmentProjectionContract() {
+    return {
+        projection_kind: "competency_question_assessment_compact_projection",
+        projection_contract_version: COMPETENCY_QUESTION_ASSESSMENT_PROJECTION_CONTRACT_VERSION,
+        semantic_authority: "host_llm_assesses_answer_status_and_explanation_fields",
+        prompt_char_limit: COMPETENCY_QUESTION_ASSESSMENT_PROMPT_CHAR_LIMIT,
+        question_projection: "full question text is included without truncation; runtime keeps the full artifact authority",
+        evidence_projection: "evidence_observation_ids and evidence_source_basenames are prompt-visible; full evidence_refs remain runtime authority",
+        source_evidence_projection: "cited evidence observation bodies (from linked claim realizations, question evidence_refs, and domain competency semantic assessment evidence_refs) are projected as source_evidence, bounded greedily by serialized payload size to the per-batch evidence reserve, so answer_status is judged on content not id labels alone",
+        // The per-observation excerpt budget and the evidence-reserve derivation are part of the
+        // contract: tuning either changes the assessment prompt surface, so they rotate the
+        // reuse-match sha.
+        source_evidence_excerpt_char_limit: COMPETENCY_QUESTION_ASSESSMENT_EVIDENCE_EXCERPT_LIMIT,
+        source_evidence_reserve_derivation: "per batch = prompt_char_limit − measured non-evidence payload (system prompt + questions + claim map + validation + policy, empty evidence) − build budget reserve, clamped >= 0; a budget stub (evidence_body_omitted_for_budget) carries no body and is counted as omitted",
+        validation_projection: "validation status, counts, required evidence scope count, validation results, and invalid prompt-visible violations are prompt-visible",
+        claim_realization_projection: "claim_id, stance, evidence observation ids, evidence source basenames, and compact rationale are prompt-visible, SCOPED to the batch's linked claims (union of the batch questions' linked_claim_ids); claim_realization_count retains the full map count and scoped_claim_realization_count surfaces the in-batch count, so a batch of zero-link (domain-competency) questions honestly shows an empty scoped list against the full count",
+        runtime_derivations: [
+            "required_seed_refs",
+            "linked_claim_ids",
+            "evidence_refs",
+            "downstream_effect",
+        ],
+        batching_policy: {
+            mode: "deterministic_prompt_budget",
+            order: "canonical_competency_question_order",
+            build_budget_reserve_chars: COMPETENCY_QUESTION_ASSESSMENT_BATCH_BUILD_BUDGET_RESERVE_CHARS,
+            single_question_overflow: "fail_loud_before_dispatch",
+        },
+        fail_loud_policy: "runtime fails before provider dispatch when any final batch exceeds prompt_char_limit",
+    };
+}

package/dist/core-runtime/reconstruct/comprehension-artifact.js

@@ -0,0 +1,321 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ComprehensionArtifact (§5.7) — the governance contract that guarantees every
+// consumer receives the SAME complete set of dimensions, so a consumer can never
+// silently drop a capped status, a lower-bound flag, a boundary witness, or a safety
+// tier. Completeness is fail-closed: a silently-missing baseline field is a contract
+// violation, never "empty = safe" (§5.7 2nd issue-002).
+//
+// Two editions share this one contract (P1-C2-A §11 R1):
+//  - DETERMINISTIC (P1-C1): the COMPANION embedded in the source observation; LLM-free,
+//    rebuilt from the inventory every run (Layer 1). producer_kind='deterministic',
+//    leaf_read_attempt='not_attempted', every LLM-touch field not_applicable.
+//  - LLM (P1-C2-A): a SEPARATE Layer-2 authored artifact carrying the provisional label
+//    read for low-confidence regions (§3.2). producer_kind='llm', leaf_read_attempt='produced',
+//    leaf-read-owned fields PRESENT, persisted+reused under llm_touch_fingerprint.
+//
+// A failed/empty leaf-read attempt NEVER masquerades as an 'llm' producer with all
+// fields deferred (the gate's convergent loophole — onto issue-001/003/004 / ultracode
+// T4/T6): content provenance (producer_kind) is split from attempt provenance
+// (leaf_read_attempt), an 'llm' producer MUST carry produced leaf-read content, and
+// `deferred` is allowed ONLY for engine-not-yet fields on a stage-scoped allowlist.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Edited whenever the baseline field SET or its semantics change; folded into the reconstruct
+ *  reuse digest (§12 T2) so a seed authored under an older/weaker contract fails the resume
+ *  provenance check rather than being silently reused. Bumped 1→2 for the P1-C2-A LLM edition
+ *  (leaf_read_attempt provenance + provisional label fields). */
+export const COMPREHENSION_ARTIFACT_CONTRACT_VERSION = 2;
+export const LEAF_SEMANTIC_ROLES = [
+    "category",
+    "measure",
+    "identifier",
+    "free_text",
+    "reference",
+];
+/** Deterministic baseline fields: PRESENT (or explicit absence with lineage) in both editions. */
+const DETERMINISTIC_BASELINE_FIELDS = [
+    "region_identity",
+    "value_signature_tile_witness",
+    "capped_or_frontier_state",
+    "is_lower_bound_by_claim",
+    "evidence_quality",
+    "examples",
+];
+/** Leaf-read-owned LLM-touch fields: PRESENT when producer_kind='llm' (§11 R4 required-PRESENT
+ *  guard); never `deferred`. not_applicable only for a deterministic producer. */
+const LEAF_READ_OWNED_FIELDS = [
+    "spine_claims",
+    "confidence_by_claim",
+    "limiting_witness",
+];
+/** Engine-not-yet LLM-touch fields: the ONLY fields allowed to be `deferred` in P1-C2-A
+ *  (the stage-scoped deferred allowlist — onto issue-003 / §11 R4c). triage·reduce = next cut. */
+const ENGINE_DEFERRABLE_FIELDS = [
+    "semantic_depth",
+    "consumer_handoff_notes",
+    "relation_obligation_lifecycle_state",
+    "downstream_blocking_semantics",
+    "trigger_provenance",
+    "triage_audit_status",
+];
+const LLM_TOUCH_BASELINE_FIELDS = [
+    ...LEAF_READ_OWNED_FIELDS,
+    ...ENGINE_DEFERRABLE_FIELDS,
+];
+const ENGINE_DEFERRABLE_SET = new Set(ENGINE_DEFERRABLE_FIELDS);
+/** Stable descriptor of the contract SHAPE (version + baseline field sets). Folded into the source-
+ *  observations reuse digest (§12 T2) so editing the baseline set rotates the resume key
+ *  tautologically — a seed authored under an older/weaker contract then fails the provenance check. */
+export const COMPREHENSION_ARTIFACT_CONTRACT_DESCRIPTOR = {
+    version: COMPREHENSION_ARTIFACT_CONTRACT_VERSION,
+    deterministic_fields: [...DETERMINISTIC_BASELINE_FIELDS],
+    leaf_read_owned_fields: [...LEAF_READ_OWNED_FIELDS],
+    engine_deferrable_fields: [...ENGINE_DEFERRABLE_FIELDS],
+};
+const VALID_ABSENCE_STATUS = new Set(["unknown", "deferred", "not_applicable"]);
+const VALID_ATTEMPT_STATUS = new Set([
+    "not_attempted",
+    "produced",
+    "unread",
+    "failed",
+]);
+const VALID_SAFETY_TIERS = new Set([
+    "consumption_allowed",
+    "internal_only",
+    "no_prompt_use",
+    "no_replay_use",
+]);
+function isAbsence(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        "status" in value &&
+        "lineage" in value);
+}
+/**
+ * Completeness + honesty validator (§5.7; §12 T3/T4; §11 R4). Fail-closed. Beyond the P1-C1
+ * completeness rules it enforces the gate's convergent anti-loophole contract:
+ *  - leaf_read_attempt (content↔attempt provenance split) is present, valid, and COUPLED to
+ *    producer_kind: an 'llm' producer requires attempt='produced'; an unread/failed attempt must
+ *    degrade to 'deterministic'; a 'produced' attempt requires an 'llm' producer.
+ *  - when producer_kind='llm', every leaf-read-owned field is PRESENT (never absent) — a failed
+ *    read cannot pass as a successful production with deferred placeholders.
+ *  - `deferred` is allowed ONLY for engine-not-yet fields on the stage allowlist.
+ * Pushes onto `violations` (mirrors validateSpreadsheetObservationHonesty); empty = valid.
+ */
+export function validateComprehensionArtifact(artifact, violations) {
+    if (artifact.contract_version !== COMPREHENSION_ARTIFACT_CONTRACT_VERSION) {
+        violations.push(`comprehension_artifact.contract_version must be ${COMPREHENSION_ARTIFACT_CONTRACT_VERSION}`);
+    }
+    if (!artifact.observation_id || !artifact.observation_id.trim()) {
+        violations.push("comprehension_artifact.observation_id is required");
+    }
+    if (!VALID_SAFETY_TIERS.has(artifact.safety_visibility_tier)) {
+        violations.push("comprehension_artifact.safety_visibility_tier is invalid");
+    }
+    const producerKind = artifact.provenance?.producer_kind;
+    if (producerKind !== "deterministic" &&
+        producerKind !== "llm" &&
+        producerKind !== "vision-assist") {
+        violations.push("comprehension_artifact.provenance.producer_kind is invalid");
+    }
+    // ── attempt provenance + coupling to content provenance (§11 R4) ──
+    const attempt = artifact.provenance?.leaf_read_attempt;
+    if (!attempt || !VALID_ATTEMPT_STATUS.has(attempt.status)) {
+        violations.push("comprehension_artifact.provenance.leaf_read_attempt.status is invalid");
+    }
+    else {
+        if (typeof attempt.lineage !== "string" || attempt.lineage.trim() === "") {
+            violations.push("comprehension_artifact.provenance.leaf_read_attempt.lineage must not be blank");
+        }
+        if (producerKind === "llm" && attempt.status !== "produced") {
+            violations.push("comprehension_artifact: producer_kind='llm' requires leaf_read_attempt.status='produced' (an attempted-but-unread/failed read must degrade to a deterministic producer)");
+        }
+        if ((attempt.status === "unread" || attempt.status === "failed") && producerKind !== "deterministic") {
+            violations.push("comprehension_artifact: an unread/failed leaf_read_attempt must degrade to producer_kind='deterministic'");
+        }
+        if (attempt.status === "produced" && producerKind === "deterministic") {
+            violations.push("comprehension_artifact: leaf_read_attempt.status='produced' requires an llm producer_kind");
+        }
+    }
+    const checkBaseline = (name, value, isLlmTouch) => {
+        if (value === undefined || value === null) {
+            violations.push(`comprehension_artifact.${name} is silently absent (must be present or explicit)`);
+            return;
+        }
+        if (isAbsence(value)) {
+            if (!VALID_ABSENCE_STATUS.has(value.status)) {
+                violations.push(`comprehension_artifact.${name} absence status is invalid`);
+            }
+            if (typeof value.lineage !== "string" || value.lineage.trim() === "") {
+                violations.push(`comprehension_artifact.${name} absence lineage must not be blank`);
+            }
+            // T4: an LLM-touch field may be `not_applicable` ONLY for a deterministic producer.
+            if (isLlmTouch && value.status === "not_applicable" && producerKind !== "deterministic") {
+                violations.push(`comprehension_artifact.${name} not_applicable is only allowed when producer_kind is deterministic`);
+            }
+            // §11 R4c: `deferred` is allowed ONLY for engine-not-yet fields on the stage allowlist —
+            // a leaf-read-owned field may never be quietly deferred (loophole: onto issue-003).
+            if (isLlmTouch && value.status === "deferred" && !ENGINE_DEFERRABLE_SET.has(name)) {
+                violations.push(`comprehension_artifact.${name} may not be 'deferred' (not on the P1-C2-A deferred allowlist; a leaf-read-owned field must be produced or the region must degrade to deterministic)`);
+            }
+        }
+        // a PRESENT value satisfies completeness; field-shape checks live in the producers/types.
+    };
+    for (const name of DETERMINISTIC_BASELINE_FIELDS) {
+        checkBaseline(name, artifact[name], false);
+    }
+    for (const name of LLM_TOUCH_BASELINE_FIELDS) {
+        checkBaseline(name, artifact[name], true);
+    }
+    // §11 R4 required-PRESENT guard: a successful llm production must actually carry leaf-read
+    // content — the loophole both families flagged (producer='llm' + all-deferred passing as success).
+    if (producerKind === "llm") {
+        for (const name of LEAF_READ_OWNED_FIELDS) {
+            const value = artifact[name];
+            if (isAbsence(value)) {
+                violations.push(`comprehension_artifact.${name} must be PRESENT when producer_kind='llm' (leaf-read-owned field cannot be '${value.status}')`);
+            }
+        }
+    }
+}
+const NOT_APPLICABLE_LINEAGE = "no semantic reading for this region; deterministic value-tile sidecar only (LLM leaf-read = P1-C2-A llm edition)";
+const ENGINE_DEFERRED_LINEAGE = "triage·reduce engine not built yet (P1-C2-B/C); this cut reads leaf labels only";
+function notApplicable() {
+    return { status: "not_applicable", lineage: NOT_APPLICABLE_LINEAGE };
+}
+function engineDeferred() {
+    return { status: "deferred", lineage: ENGINE_DEFERRED_LINEAGE };
+}
+function deriveDeterministicBaseline(inventory) {
+    const tiles = inventory.segmented_value_tiles ?? [];
+    const boundaries = tiles.flatMap((sheet) => sheet.columns.flatMap((col) => col.intra_tile_notes.map((note) => ({
+        sheet: sheet.sheet,
+        column_index: col.column_index,
+        boundary_kind: note.boundary_kind,
+        prev_shape: note.prev_shape,
+        new_shape: note.new_shape,
+        last_prev_format_row: note.last_prev_format_row,
+        first_new_format_row: note.first_new_format_row,
+    }))));
+    const segmentsCapped = tiles.some((sheet) => sheet.columns.some((col) => col.segments_capped));
+    const distinctIsLowerBound = tiles.some((sheet) => sheet.columns.some((col) => col.segments.some((seg) => seg.distinct_is_lower_bound)));
+    const sheets = inventory.sheets.map((s) => s.name);
+    const rowExtents = inventory.sheets.map((s) => s.dimensions.rows).filter((r) => r > 0);
+    const rowSpan = rowExtents.length > 0 ? { min: 1, max: Math.max(...rowExtents) } : null;
+    // examples = canonical value-tile witnesses (a bounded rendering of "where the shape/format
+    // changes"). The downstream LLM names what each change MEANS; the code never names it.
+    const examples = boundaries
+        .slice(0, 16)
+        .map((b) => `${b.sheet}!col${b.column_index} ${b.boundary_kind} ${b.prev_shape}→${b.new_shape} @row${b.first_new_format_row}`);
+    return {
+        region_identity: { sheets, row_span: rowSpan },
+        value_signature_tile_witness: { boundaries, boundaries_are_lower_bound: segmentsCapped },
+        capped_or_frontier_state: { segments_capped: segmentsCapped, distinct_is_lower_bound: distinctIsLowerBound },
+        is_lower_bound_by_claim: segmentsCapped || distinctIsLowerBound,
+        examples,
+    };
+}
+/**
+ * Build the DETERMINISTIC-edition ComprehensionArtifact embedded in the source observation
+ * (§4; P1-C1). Pure + LLM-free — the COMPANION that stays Layer-1 (its reuse stays content-hash
+ * gated; §11 R1 keeps the LLM leaf-read in a SEPARATE artifact). `leafReadAttempt` defaults to
+ * 'not_attempted'; pass 'unread'/'failed' to record an attempted-but-degraded read (§11 R9).
+ */
+export function buildDeterministicComprehensionArtifact(args) {
+    const base = deriveDeterministicBaseline(args.inventory);
+    return {
+        contract_version: COMPREHENSION_ARTIFACT_CONTRACT_VERSION,
+        observation_id: args.observationId,
+        region_identity: base.region_identity,
+        value_signature_tile_witness: base.value_signature_tile_witness,
+        provenance: {
+            producer_kind: "deterministic",
+            epoch_fingerprint_contribution: null,
+            leaf_read_attempt: args.leafReadAttempt ?? {
+                status: "not_attempted",
+                lineage: "deterministic companion; no LLM leaf-read run for this observation",
+            },
+        },
+        safety_visibility_tier: "consumption_allowed",
+        capped_or_frontier_state: base.capped_or_frontier_state,
+        is_lower_bound_by_claim: base.is_lower_bound_by_claim,
+        evidence_quality: "structural_only",
+        examples: base.examples,
+        spine_claims: notApplicable(),
+        confidence_by_claim: notApplicable(),
+        limiting_witness: notApplicable(),
+        semantic_depth: notApplicable(),
+        consumer_handoff_notes: notApplicable(),
+        relation_obligation_lifecycle_state: notApplicable(),
+        downstream_blocking_semantics: notApplicable(),
+        trigger_provenance: notApplicable(),
+        triage_audit_status: notApplicable(),
+    };
+}
+/**
+ * Build the LLM-edition ComprehensionArtifact — the SEPARATE Layer-2 authored artifact carrying the
+ * provisional label read for low-confidence regions (§11 R1/R4/R5/R7/R11). producer_kind='llm',
+ * leaf_read_attempt='produced', leaf-read-owned fields PRESENT, engine fields explicitly deferred.
+ * `fingerprint` = the llm_touch_fingerprint (ⓐ+ⓑ) gating this artifact's reuse (provenance only).
+ * Deterministic baseline fields are still inventory-derived (LLM-free); the artifact is producer_kind
+ * 'llm' because it CARRIES llm content.
+ */
+export function buildLlmComprehensionArtifact(args) {
+    if (args.leafRead.labels.length === 0) {
+        // Guard: an empty read is NOT a production — callers must route it to the degraded
+        // deterministic builder (status='unread'). Fail loud rather than emit an llm artifact
+        // with no content (which the validator would reject anyway).
+        throw new Error("buildLlmComprehensionArtifact requires ≥1 produced label; route an empty read to buildDeterministicComprehensionArtifact({leafReadAttempt:{status:'unread'}})");
+    }
+    const base = deriveDeterministicBaseline(args.inventory);
+    const spineClaims = args.leafRead.labels.map((label) => {
+        const claim = {
+            claim_kind: "provisional_label_read",
+            authority: "non_authoritative",
+            sheet: label.sheet,
+            column_index: label.column_index,
+            tentative_label: label.tentative_label,
+        };
+        if (label.semantic_role)
+            claim.semantic_role = label.semantic_role;
+        if (label.captured_note)
+            claim.captured_note = label.captured_note;
+        return claim;
+    });
+    const confidenceByClaim = args.leafRead.labels.map((label) => ({
+        claim_ref: `${label.sheet}!col${label.column_index}`,
+        confidence: label.confidence,
+        is_lower_bound: label.is_lower_bound,
+    }));
+    return {
+        contract_version: COMPREHENSION_ARTIFACT_CONTRACT_VERSION,
+        observation_id: args.observationId,
+        region_identity: base.region_identity,
+        value_signature_tile_witness: base.value_signature_tile_witness,
+        provenance: {
+            producer_kind: "llm",
+            epoch_fingerprint_contribution: args.fingerprint,
+            leaf_read_attempt: {
+                status: "produced",
+                lineage: `leaf-read produced ${args.leafRead.labels.length} provisional label(s) for low-confidence region(s)`,
+            },
+        },
+        safety_visibility_tier: "consumption_allowed",
+        capped_or_frontier_state: base.capped_or_frontier_state,
+        is_lower_bound_by_claim: base.is_lower_bound_by_claim, // DETERMINISTIC; leaf bound lives in confidence_by_claim.
+        evidence_quality: "structural_plus_provisional_label",
+        examples: base.examples,
+        spine_claims: spineClaims,
+        confidence_by_claim: confidenceByClaim,
+        limiting_witness: {
+            region_ref: args.leafRead.limiting_region_ref,
+            reason: args.leafRead.limiting_reason,
+        },
+        semantic_depth: engineDeferred(),
+        consumer_handoff_notes: engineDeferred(),
+        relation_obligation_lifecycle_state: engineDeferred(),
+        downstream_blocking_semantics: engineDeferred(),
+        trigger_provenance: engineDeferred(),
+        triage_audit_status: engineDeferred(),
+    };
+}