@haaaiawd/second-nature 0.2.9 → 0.2.13

package/runtime/observability/services/lived-experience-audit.d.ts

@@ -1,5 +1,5 @@
 import { AppendOnlyAuditStore } from "../audit/append-only-audit-store.js";
-import type { SourceRef } from "../../storage/life-evidence/types.js";
+import type { LifeEvidenceSourceRef } from "../../storage/life-evidence/types.js";
 import type { DreamTrace } from "../../dream/types.js";
 export type RuntimeScope = "rhythm" | "user_task" | "user_reply";
 export type HeartbeatOutcome = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
@@ -18,8 +18,8 @@ export interface DecisionTracePayload {
     outreachVerdict?: "allow" | "deny" | "defer";
     deliveryAuditId?: string;
     reasonCodes: string[];
-    sourceRefs: SourceRef[];
-    snapshotRef?: SourceRef;
+    sourceRefs: LifeEvidenceSourceRef[];
+    snapshotRef?: LifeEvidenceSourceRef;
     createdAt: string;
 }
 export interface DeliveryAuditPayload {
@@ -31,7 +31,7 @@ export interface DeliveryAuditPayload {
     recipientRef?: string;
     status: DeliveryAuditStatus;
     messageId?: string;
-    hostProofRef?: SourceRef;
+    hostProofRef?: LifeEvidenceSourceRef;
     fallbackRef?: string;
     ackDropMatched?: boolean;
     hostVersion?: string;
@@ -45,8 +45,8 @@ export interface SourceCoverageAuditPayload {
     decisionId?: string;
     subjectType: "quiet_artifact" | "outreach_draft" | "guidance_payload" | "decision_trace" | "host_report";
     subjectRef: string;
-    usedSourceRefs: SourceRef[];
-    unresolvedRefs: SourceRef[];
+    usedSourceRefs: LifeEvidenceSourceRef[];
+    unresolvedRefs: LifeEvidenceSourceRef[];
     coverageRatio: number;
     unsupportedClaims: string[];
     status: GroundingStatus;
@@ -61,7 +61,7 @@ export interface GuidanceGroundingAuditPayload {
     draftId?: string;
     sceneType: "outreach" | "quiet_reflection" | "social" | "explain" | "user_reply_continuity" | "fallback_candidate";
     groundingStatus: GroundingStatus;
-    usedSourceRefs: SourceRef[];
+    usedSourceRefs: LifeEvidenceSourceRef[];
     unsupportedClaims: string[];
     guardViolations: string[];
     deliveryWording?: "sendable" | "not_sent_fallback_candidate";

package/runtime/shared/degraded-status-classifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Degraded Status Classifier (T-OBS.R.8)
+ *
+ * Core logic: map canonical V8ReasonCode values to precise operational states
+ * so that stage-level diagnostics never use the aggregate "degraded" string.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §4.1`
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js`
+ * Boundary: pure function; no I/O.
+ * Test coverage: tests/unit/shared/degraded-status-classifier.test.ts
+ */
+import type { DegradedOperationResult, V8ReasonCode } from "./types/v8-contracts.js";
+export type PreciseDegradedStatus = DegradedOperationResult["status"];
+export declare function classifyDegradedStatus(reason: V8ReasonCode): PreciseDegradedStatus;

package/runtime/shared/degraded-status-classifier.js

@@ -0,0 +1,68 @@
+/**
+ * Degraded Status Classifier (T-OBS.R.8)
+ *
+ * Core logic: map canonical V8ReasonCode values to precise operational states
+ * so that stage-level diagnostics never use the aggregate "degraded" string.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §4.1`
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js`
+ * Boundary: pure function; no I/O.
+ * Test coverage: tests/unit/shared/degraded-status-classifier.test.ts
+ */
+const EMPTY_REASONS = new Set([
+    "evidence_batch_empty",
+    "evidence_content_missing",
+    "ingestion_empty",
+    "ingestion_no_data",
+    "quiet_empty_input",
+]);
+const BLOCKED_REASONS = new Set([
+    "source_refs_unresolved",
+    "proposal_missing_source_refs",
+    "judgment_missing_source_refs",
+    "quiet_redaction_blocked",
+    "dream_blocked_redaction",
+    "dream_blocked_no_content",
+    "dream_blocked_private_redacted",
+    "dream_blocked_credential",
+    "dream_blocked_validation_failed",
+    "dream_interval_active",
+]);
+const UNSAFE_REASONS = new Set([
+    "policy_denied_high_risk",
+    "policy_denied_breaker_open",
+    "closure_idempotency_conflict",
+]);
+const PARTIAL_REASONS = new Set([
+    "evidence_batch_truncated",
+    "perception_rules_only",
+    "dream_rules_only",
+    "dream_model_timeout",
+    "quiet_validation_failed",
+    "closure_downgraded_without_draft",
+]);
+const UNAVAILABLE_REASONS = new Set([
+    "state_unreadable",
+    "quiet_state_unreadable",
+    "ingestion_state_unreadable",
+    "stage_event_missing",
+    "execution_unavailable",
+    "guidance_unavailable",
+    "dream_scheduler_unavailable",
+    "policy_denied_missing_permission",
+    "closure_failed",
+    "closure_unavailable",
+]);
+export function classifyDegradedStatus(reason) {
+    if (EMPTY_REASONS.has(reason))
+        return "empty";
+    if (BLOCKED_REASONS.has(reason))
+        return "blocked";
+    if (UNSAFE_REASONS.has(reason))
+        return "unsafe";
+    if (PARTIAL_REASONS.has(reason))
+        return "partial";
+    return "unavailable";
+}

package/runtime/shared/evidence-level-classifier.d.ts

@@ -0,0 +1,61 @@
+/**
+ * EvidenceLevelClassifier — Monotonic evidence-level taxonomy for operator-facing surfaces.
+ *
+ * Core logic: classify how strongly a command/response is backed by runtime proof.
+ * Levels are ordered from weakest (carrier_ack) to strongest (durable_verified).
+ * A level may only stay the same or increase within one command; synthetic/carrier
+ * proofs can never be promoted to real_runtime or durable_verified.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §4.2, §4.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §2, §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §6.1`
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js` (EvidenceLevel)
+ * Boundary: Pure classification functions; no storage or side effects.
+ * Test coverage: tests/unit/shared/evidence-level-classifier.test.ts
+ */
+import type { EvidenceLevel } from "./types/v8-contracts.js";
+export type { EvidenceLevel };
+export declare const EVIDENCE_LEVEL_ORDER: Record<EvidenceLevel, number>;
+export interface EvidenceLevelProofInput {
+    /** Host/plugin/CLI produced an envelope but no Second Nature contract path ran. */
+    hasCarrierEnvelope?: boolean;
+    /** Static/fixture contract path ran without proving live state mutation. */
+    hasContractSmoke?: boolean;
+    /** Durable state was read or existing rows were observed. */
+    hasStatePresent?: boolean;
+    /** Current v8 living-loop command executed and produced stage + closure proof. */
+    hasCycleExecution?: boolean;
+    /** real_runtime proof was persisted and read back through normal read model. */
+    hasReadbackVerification?: boolean;
+}
+/**
+ * Classify evidence level from observed proof flags.
+ * Returns the strongest level whose required proof is present.
+ */
+export declare function classifyEvidenceLevel(input: EvidenceLevelProofInput): EvidenceLevel;
+/**
+ * Cap a candidate level by a maximum allowed level.
+ * Used to prevent carrier/smoke proofs from masquerading as real runtime health.
+ */
+export declare function capEvidenceLevel(candidate: EvidenceLevel, cap: EvidenceLevel): EvidenceLevel;
+/**
+ * Promote a current level to a target level only if target is strictly stronger
+ * and promotion is supported by supplied proof.
+ */
+export declare function promoteEvidenceLevel(current: EvidenceLevel, target: EvidenceLevel, proof: EvidenceLevelProofInput): EvidenceLevel;
+/**
+ * Aggregate multiple stage evidence levels into the minimum (weakest) level.
+ * A chain is only as strong as its weakest proven stage.
+ */
+export declare function minEvidenceLevel(levels: EvidenceLevel[]): EvidenceLevel;
+/**
+ * Convenience: the strongest level achievable from the input proof set,
+ * but never exceeding a hard cap.
+ */
+export declare function classifyAndCapEvidenceLevel(input: EvidenceLevelProofInput, cap: EvidenceLevel): EvidenceLevel;
+/**
+ * Map an evidence level to a human-readable operator note.
+ */
+export declare function evidenceLevelDescription(level: EvidenceLevel): string;

package/runtime/shared/evidence-level-classifier.js

@@ -0,0 +1,116 @@
+/**
+ * EvidenceLevelClassifier — Monotonic evidence-level taxonomy for operator-facing surfaces.
+ *
+ * Core logic: classify how strongly a command/response is backed by runtime proof.
+ * Levels are ordered from weakest (carrier_ack) to strongest (durable_verified).
+ * A level may only stay the same or increase within one command; synthetic/carrier
+ * proofs can never be promoted to real_runtime or durable_verified.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §4.2, §4.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §2, §3.3`
+ * - `.anws/v8/04_SYSTEM_DESIGN/observability-health-system.md §6.1`
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js` (EvidenceLevel)
+ * Boundary: Pure classification functions; no storage or side effects.
+ * Test coverage: tests/unit/shared/evidence-level-classifier.test.ts
+ */
+export const EVIDENCE_LEVEL_ORDER = {
+    carrier_ack: 0,
+    contract_smoke: 1,
+    state_present: 2,
+    real_runtime: 3,
+    durable_verified: 4,
+};
+const LEVELS_BY_ORDER = [
+    "carrier_ack",
+    "contract_smoke",
+    "state_present",
+    "real_runtime",
+    "durable_verified",
+];
+/**
+ * Classify evidence level from observed proof flags.
+ * Returns the strongest level whose required proof is present.
+ */
+export function classifyEvidenceLevel(input) {
+    if (input.hasReadbackVerification && input.hasCycleExecution) {
+        return "durable_verified";
+    }
+    if (input.hasCycleExecution) {
+        return "real_runtime";
+    }
+    if (input.hasStatePresent) {
+        return "state_present";
+    }
+    if (input.hasContractSmoke) {
+        return "contract_smoke";
+    }
+    if (input.hasCarrierEnvelope) {
+        return "carrier_ack";
+    }
+    // Default: carrier_ack when an envelope exists but no stronger proof was supplied.
+    return "carrier_ack";
+}
+/**
+ * Cap a candidate level by a maximum allowed level.
+ * Used to prevent carrier/smoke proofs from masquerading as real runtime health.
+ */
+export function capEvidenceLevel(candidate, cap) {
+    if (EVIDENCE_LEVEL_ORDER[candidate] <= EVIDENCE_LEVEL_ORDER[cap]) {
+        return candidate;
+    }
+    return cap;
+}
+/**
+ * Promote a current level to a target level only if target is strictly stronger
+ * and promotion is supported by supplied proof.
+ */
+export function promoteEvidenceLevel(current, target, proof) {
+    const classified = classifyEvidenceLevel(proof);
+    if (EVIDENCE_LEVEL_ORDER[classified] >= EVIDENCE_LEVEL_ORDER[target]) {
+        return capEvidenceLevel(target, classified);
+    }
+    return current;
+}
+/**
+ * Aggregate multiple stage evidence levels into the minimum (weakest) level.
+ * A chain is only as strong as its weakest proven stage.
+ */
+export function minEvidenceLevel(levels) {
+    if (levels.length === 0)
+        return "carrier_ack";
+    let min = levels[0];
+    for (const level of levels) {
+        if (EVIDENCE_LEVEL_ORDER[level] < EVIDENCE_LEVEL_ORDER[min]) {
+            min = level;
+        }
+    }
+    return min;
+}
+/**
+ * Convenience: the strongest level achievable from the input proof set,
+ * but never exceeding a hard cap.
+ */
+export function classifyAndCapEvidenceLevel(input, cap) {
+    return capEvidenceLevel(classifyEvidenceLevel(input), cap);
+}
+/**
+ * Map an evidence level to a human-readable operator note.
+ */
+export function evidenceLevelDescription(level) {
+    switch (level) {
+        case "carrier_ack":
+            return "Host/plugin returned an envelope but no Second Nature contract path ran.";
+        case "contract_smoke":
+            return "Static or fixture contract path passed without live state mutation.";
+        case "state_present":
+            return "Durable state exists or was read, but no current cycle executed.";
+        case "real_runtime":
+            return "Current v8 living-loop command executed and produced stage/closure proof.";
+        case "durable_verified":
+            return "Real runtime proof persisted and read back through the normal read model.";
+        default:
+            return "Unknown evidence level.";
+    }
+}

package/runtime/shared/provenance-tier.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Provenance Tier Validator (T-SH.R.6)
+ *
+ * Core logic: enforce that real domain evidence lives in `sourceRefs`,
+ * runtime/policy/setup/host/packaging proofs live in `proofRefs`, and
+ * observability/audit/stage-event traces live in `traceRefs`.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §2.2`
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js`
+ * Boundary: pure functions; no I/O.
+ * Test coverage: tests/unit/shared/provenance-tier.test.ts
+ */
+import type { SourceRef, ProvenanceBundle } from "./types/v8-contracts.js";
+export interface ProvenanceValidationError {
+    ok: false;
+    field: "sourceRefs" | "proofRefs" | "traceRefs";
+    ref: SourceRef;
+    reason: string;
+}
+export type ProvenanceValidationResult = {
+    ok: true;
+    bundle: ProvenanceBundle;
+} | {
+    ok: false;
+    errors: ProvenanceValidationError[];
+};
+export declare function validateProvenanceTiers(bundle: ProvenanceBundle): ProvenanceValidationResult;
+export declare function buildClosureProvenance(input: {
+    sourceRefs?: SourceRef[];
+    proofRefs?: SourceRef[];
+    traceRefs?: SourceRef[];
+}): ProvenanceBundle;
+export declare function cycleTraceRef(cycleId: string): SourceRef;
+export declare function closureTraceRef(closureId: string): SourceRef;
+export declare function decisionProofRef(decisionId: string): SourceRef;

package/runtime/shared/provenance-tier.js

@@ -0,0 +1,97 @@
+/**
+ * Provenance Tier Validator (T-SH.R.6)
+ *
+ * Core logic: enforce that real domain evidence lives in `sourceRefs`,
+ * runtime/policy/setup/host/packaging proofs live in `proofRefs`, and
+ * observability/audit/stage-event traces live in `traceRefs`.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/shared-v8-contracts.md §2.2`
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js`
+ * Boundary: pure functions; no I/O.
+ * Test coverage: tests/unit/shared/provenance-tier.test.ts
+ */
+const PROOF_FAMILIES = new Set([
+    "action_closure",
+    "audit",
+    "connector_result",
+]);
+const TRACE_FAMILIES = new Set([
+    "audit",
+]);
+function isSyntheticProof(ref) {
+    return (ref.uri.startsWith("sn://closure/") ||
+        ref.uri.startsWith("sn://decision/") ||
+        ref.uri.startsWith("sn://policy/") ||
+        ref.uri.startsWith("sn://execution/") ||
+        ref.uri.startsWith("sn://cycle/") ||
+        ref.uri.startsWith("sn://host/") ||
+        ref.uri.startsWith("sn://setup/") ||
+        PROOF_FAMILIES.has(ref.family));
+}
+function isTraceRef(ref) {
+    return (ref.uri.startsWith("sn://cycle/") ||
+        ref.uri.startsWith("sn://event/") ||
+        TRACE_FAMILIES.has(ref.family));
+}
+export function validateProvenanceTiers(bundle) {
+    const errors = [];
+    for (const ref of bundle.sourceRefs) {
+        if (isSyntheticProof(ref)) {
+            errors.push({
+                ok: false,
+                field: "sourceRefs",
+                ref,
+                reason: "Synthetic proof/trace ref must not live in sourceRefs",
+            });
+        }
+    }
+    for (const ref of bundle.proofRefs) {
+        if (isTraceRef(ref)) {
+            errors.push({
+                ok: false,
+                field: "proofRefs",
+                ref,
+                reason: "Trace ref must live in traceRefs, not proofRefs",
+            });
+        }
+    }
+    return errors.length === 0
+        ? { ok: true, bundle }
+        : { ok: false, errors };
+}
+export function buildClosureProvenance(input) {
+    return {
+        sourceRefs: input.sourceRefs ?? [],
+        proofRefs: input.proofRefs ?? [],
+        traceRefs: input.traceRefs ?? [],
+    };
+}
+export function cycleTraceRef(cycleId) {
+    return {
+        uri: `sn://cycle/${cycleId}`,
+        family: "audit",
+        id: cycleId,
+        redactionClass: "none",
+        resolveStatus: "resolvable",
+    };
+}
+export function closureTraceRef(closureId) {
+    return {
+        uri: `sn://closure/${closureId}`,
+        family: "action_closure",
+        id: closureId,
+        redactionClass: "none",
+        resolveStatus: "resolvable",
+    };
+}
+export function decisionProofRef(decisionId) {
+    return {
+        uri: `sn://decision/${decisionId}`,
+        family: "action_closure",
+        id: decisionId,
+        redactionClass: "none",
+        resolveStatus: "resolvable",
+    };
+}

package/runtime/shared/serialization.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared serialization helpers for cross-system value types.
+ *
+ * Core logic:
+ * - `parseSourceRefs` / `serializeSourceRefs` provide the single round-trip
+ *   implementation for `sourceRefsJson` / `source_refs_json` columns.
+ * - Failures are silent on read (return empty array) because malformed JSON
+ *   in persisted state must not crash downstream consumers; callers that need
+ *   to distinguish malformed rows should validate separately.
+ *
+ * Dependencies: `src/shared/types/v8-contracts.js` (SourceRef)
+ * Boundary: Pure functions; no storage or business logic.
+ * Test coverage: `tests/unit/shared/source-ref-serialization.test.ts`
+ */
+import type { SourceRef } from "./types/v8-contracts.js";
+export declare function serializeSourceRefs(refs: SourceRef[]): string;
+export declare function parseSourceRefs(json: string | null | undefined): SourceRef[];

package/runtime/shared/serialization.js

@@ -0,0 +1,27 @@
+export function serializeSourceRefs(refs) {
+    return JSON.stringify(refs);
+}
+function isSourceRef(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (typeof candidate.uri === "string" &&
+        typeof candidate.family === "string" &&
+        typeof candidate.id === "string" &&
+        typeof candidate.redactionClass === "string" &&
+        (candidate.sensitivityClass === undefined ||
+            typeof candidate.sensitivityClass === "string"));
+}
+export function parseSourceRefs(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        if (Array.isArray(parsed) && parsed.every(isSourceRef))
+            return parsed;
+        return [];
+    }
+    catch {
+        return [];
+    }
+}

package/runtime/shared/setup-ack.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Setup Ack Truth Contract (T-ROS.R.8)
+ *
+ * Core logic: define the canonical SetupAck schema and a validator that rejects
+ * `placedIn: "unspecified"`, missing fields, unknown writers, and hand-written
+ * files that do not satisfy the schema.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §3.2`
+ *
+ * Dependencies: none (plain validation to keep plugin load lightweight)
+ * Boundary: Pure validation; no I/O.
+ * Test coverage: tests/unit/shared/setup-ack-validator.test.ts
+ */
+export declare const SETUP_ACK_SCHEMA_VERSION = 1;
+export type SetupAckPlacement = "workspace_guide" | "host_skill_registry" | "agent_profile" | "manual_operator_instruction";
+export type SetupAckWriter = "setup_ack_command" | "host_setup_bridge";
+export interface SetupAck {
+    schemaVersion: typeof SETUP_ACK_SCHEMA_VERSION;
+    acknowledgedAt: string;
+    placedIn: SetupAckPlacement;
+    placementProofRef: string;
+    writer: SetupAckWriter;
+    hostName?: string;
+    hostVersion?: string;
+    acceptedBy?: string;
+    note?: string;
+}
+export interface SetupAckValidationResult {
+    ok: true;
+    ack: SetupAck;
+}
+export interface SetupAckValidationError {
+    ok: false;
+    field: string;
+    reason: string;
+    repairAction: string;
+}
+export type ValidateSetupAckResult = SetupAckValidationResult | {
+    ok: false;
+    errors: SetupAckValidationError[];
+};
+export declare function validateSetupAck(raw: Record<string, unknown>): ValidateSetupAckResult;
+/**
+ * Check whether a raw marker object can be considered a complete ack.
+ * Hand-written files are treated as incomplete until verified.
+ */
+export declare function isSetupAckComplete(raw: Record<string, unknown>): {
+    complete: true;
+    ack: SetupAck;
+} | {
+    complete: false;
+    errors: SetupAckValidationError[];
+};

package/runtime/shared/setup-ack.js

@@ -0,0 +1,108 @@
+/**
+ * Setup Ack Truth Contract (T-ROS.R.8)
+ *
+ * Core logic: define the canonical SetupAck schema and a validator that rejects
+ * `placedIn: "unspecified"`, missing fields, unknown writers, and hand-written
+ * files that do not satisfy the schema.
+ *
+ * Design authority:
+ * - `.anws/v8/04_SYSTEM_DESIGN/runtime-ops-system.md §3.2`
+ *
+ * Dependencies: none (plain validation to keep plugin load lightweight)
+ * Boundary: Pure validation; no I/O.
+ * Test coverage: tests/unit/shared/setup-ack-validator.test.ts
+ */
+export const SETUP_ACK_SCHEMA_VERSION = 1;
+const VALID_PLACEMENTS = new Set([
+    "workspace_guide",
+    "host_skill_registry",
+    "agent_profile",
+    "manual_operator_instruction",
+]);
+const VALID_WRITERS = new Set([
+    "setup_ack_command",
+    "host_setup_bridge",
+]);
+export function validateSetupAck(raw) {
+    const errors = [];
+    if (raw.schemaVersion !== SETUP_ACK_SCHEMA_VERSION) {
+        errors.push({
+            ok: false,
+            field: "schemaVersion",
+            reason: `schemaVersion must be ${SETUP_ACK_SCHEMA_VERSION}`,
+            repairAction: "Re-run setup_ack with a current client that writes schemaVersion=1.",
+        });
+    }
+    const placedIn = typeof raw.placedIn === "string" ? raw.placedIn : undefined;
+    if (!placedIn || placedIn === "unspecified") {
+        errors.push({
+            ok: false,
+            field: "placedIn",
+            reason: "placedIn is missing or 'unspecified'",
+            repairAction: "Provide a concrete placement target such as 'workspace_guide' or 'host_skill_registry'.",
+        });
+    }
+    else if (!VALID_PLACEMENTS.has(placedIn)) {
+        errors.push({
+            ok: false,
+            field: "placedIn",
+            reason: `placedIn '${placedIn}' is not a recognized placement target`,
+            repairAction: `Use one of: ${Array.from(VALID_PLACEMENTS).join(", ")}.`,
+        });
+    }
+    const placementProofRef = typeof raw.placementProofRef === "string" ? raw.placementProofRef : undefined;
+    if (!placementProofRef || placementProofRef.trim().length === 0) {
+        errors.push({
+            ok: false,
+            field: "placementProofRef",
+            reason: "placementProofRef is missing or empty",
+            repairAction: "Provide a proof reference such as a host skill registry id, file path, or anchor URI.",
+        });
+    }
+    const writer = typeof raw.writer === "string" ? raw.writer : undefined;
+    if (!writer || !VALID_WRITERS.has(writer)) {
+        errors.push({
+            ok: false,
+            field: "writer",
+            reason: `writer '${writer ?? "missing"}' is not authorized`,
+            repairAction: `Writer must be one of: ${Array.from(VALID_WRITERS).join(", ")}.`,
+        });
+    }
+    const acknowledgedAt = typeof raw.acknowledgedAt === "string" ? raw.acknowledgedAt : undefined;
+    if (!acknowledgedAt || Number.isNaN(Date.parse(acknowledgedAt))) {
+        errors.push({
+            ok: false,
+            field: "acknowledgedAt",
+            reason: "acknowledgedAt is missing or not a valid ISO timestamp",
+            repairAction: "Re-run setup_ack so the client can write a fresh timestamp.",
+        });
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    return {
+        ok: true,
+        ack: {
+            schemaVersion: SETUP_ACK_SCHEMA_VERSION,
+            acknowledgedAt: acknowledgedAt,
+            placedIn: placedIn,
+            placementProofRef: placementProofRef,
+            writer: writer,
+            hostName: typeof raw.hostName === "string" ? raw.hostName : undefined,
+            hostVersion: typeof raw.hostVersion === "string" ? raw.hostVersion : undefined,
+            acceptedBy: typeof raw.acceptedBy === "string" ? raw.acceptedBy : undefined,
+            note: typeof raw.note === "string" ? raw.note : undefined,
+        },
+    };
+}
+/**
+ * Check whether a raw marker object can be considered a complete ack.
+ * Hand-written files are treated as incomplete until verified.
+ */
+export function isSetupAckComplete(raw) {
+    const result = validateSetupAck(raw);
+    if (result.ok) {
+        return { complete: true, ack: result.ack };
+    }
+    return { complete: false, errors: result.errors };
+}

package/runtime/shared/source-ref-compat.d.ts

@@ -0,0 +1,26 @@
+/**
+ * SourceRef compatibility adapters.
+ *
+ * Core logic: convert legacy v5/v7 source-ref shapes that used `kind` into
+ * the v8 canonical `SourceRef` shape (`family` + `redactionClass`).
+ * Dependencies: shared v8 contracts only.
+ * Boundary: compatibility at old/new system seams; canonical v8 modules should
+ * pass `SourceRef` directly without reintroducing local clones.
+ * Test coverage: Wave 113 typecheck and affected control-plane/host/life-evidence tests.
+ */
+import type { SourceRef, SourceRefFamily } from "./types/v8-contracts.js";
+export type LegacySourceRefKind = "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+export interface LegacySourceRefLike {
+    id: string;
+    kind?: LegacySourceRefKind | string;
+    uri: string;
+}
+export declare function sourceRefFamilyFromLegacyKind(kind: LegacySourceRefKind | string | undefined): SourceRefFamily;
+export declare function legacyKindFromSourceRef(ref: SourceRef): LegacySourceRefKind;
+export declare function toCanonicalSourceRef(ref: LegacySourceRefLike): SourceRef;
+export declare function makeCanonicalSourceRef(input: {
+    id: string;
+    family: SourceRefFamily;
+    uri: string;
+    redactionClass?: SourceRef["redactionClass"];
+}): SourceRef;