create-principles-disciple 1.145.3 → 1.145.4

package/host-runtime/dist/behavior-example-pack-assembler.js

@@ -0,0 +1,243 @@
+/**
+ * Shared Owner-labelled BehaviorExamplePack assembly (PRI-484 / PRI-992).
+ *
+ * Reads pain lineage + trajectory rows from TrajectoryDatabase and assembles
+ * a validated BehaviorExamplePack for the Artificer. Fail loud on any gap
+ * (missing pain, empty trajectory, invalid pack) — no silent fallback.
+ *
+ * Err-prevention:
+ *   - ERR-001: every DB row field validated as `unknown` (no `as` bypass on
+ *     parsed params_json or row casts).
+ *   - ERR-069: Artificer shared schema — invalid pack must fail loud.
+ *   - ERR-026: reuses production TrajectoryDatabase (no hand-written DDL).
+ *   - rc-2: structural type guards, no `as T` on parsed input.
+ *   - rc-5: Object.hasOwn over `in`.
+ *   - rc-9: every failure path throws a structured Error with a clear reason.
+ *   - PRI-980 review P2-1: trajectory STORE I/O failures throw the typed
+ *     `evidence_source_error` (readTrajectoryStore) so the readiness contract
+ *     preserves them as storage faults, not Owner evidence faults (§6.2).
+ *
+ * Spec: docs/superpowers/specs/2026-06-27-rulecode-context-vision-design.md §7.2
+ *
+ * Boundary: this module is I/O. Pure logic (type + validator) lives in
+ * `@principles/core/runtime-v2` → `behavior-example-pack.ts`.
+ */
+import { buildRuleHostAction } from '@principles/core/runtime-v2/internalization/rule-host-input-builder';
+import { computeBehaviorFacts } from '@principles/core/runtime-v2/internalization/rule-context-v2';
+import { validateBehaviorExamplePack } from '@principles/core/runtime-v2/internalization/behavior-example-pack';
+// Factory lives in evidence-readiness.ts (the classification authority); it is
+// consumed through its registered LEAF subpath. A VALUE import of the
+// runtime-v2 barrel on this satellite path re-pulls the whole LLM graph and
+// fails the satellite-purity guard (OPT-002, scripts/build/check-satellite-purity.mjs) —
+// the leaf is on core's exports allowlist for exactly this consumer.
+import { createOwnerEvidenceScopeError } from '@principles/core/runtime-v2/internalization/evidence-readiness';
+import { assembleBehaviorHistory } from './behavior-history.js';
+// ── internal constants ─────────────────────────────────────────────────────
+const MAX_POSITIVES = 3;
+const MAX_EVIDENCE_REFS = 5;
+const HISTORY_LIMIT = 100;
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * PRI-980 review P2-1 (SPEC-PD-IAER-001 §6.2 case 3): the trajectory STORE
+ * throwing is an I/O/storage failure of the evidence source itself — it must
+ * surface as the typed `evidence_source_error` kind so the readiness contract
+ * preserves it as a storage fault instead of misreporting "Owner labelled bad
+ * evidence". Structural, never message sniffing: the store RETURNING no row
+ * is a data gap (the typed scope kinds below); the store THROWING is the I/O
+ * failure signal. Assembler-owned data-shape validation errors stay plain
+ * Errors (→ `invalid`), unchanged.
+ */
+function readTrajectoryStore(what, op) {
+    try {
+        return op();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw createOwnerEvidenceScopeError('evidence_source_error', `[BehaviorExamplePackAssembler] trajectory store ${what} failed (evidence source error, SPEC-PD-IAER-001 §6.2): ${message}`);
+    }
+}
+// ── type guards (rc-2: no `as` bypass) ─────────────────────────────────────
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasNoProtoKeys(value) {
+    for (const key of Object.keys(value)) {
+        if (PROTO_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+// ── BehaviorExamplePackAssembler ───────────────────────────────────────────
+/**
+ * Host-neutral assembler: pain lineage + trajectory → validated BehaviorExamplePack.
+ *
+ * The caller owns source lifecycle and supplies the real host vocabulary.
+ */
+function validateOwnerSelection(input) {
+    if (!Number.isSafeInteger(input.sourceNegativeToolCallId) || input.sourceNegativeToolCallId <= 0) {
+        throw new Error('[BehaviorExamplePackAssembler] sourceNegativeToolCallId must be a positive integer');
+    }
+    if (!Array.isArray(input.positiveToolCallIds) || input.positiveToolCallIds.length === 0 || input.positiveToolCallIds.length > MAX_POSITIVES) {
+        throw new Error('[BehaviorExamplePackAssembler] positiveToolCallIds must contain 1 to at most 3 IDs');
+    }
+    const allIds = [input.sourceNegativeToolCallId, ...input.positiveToolCallIds];
+    if (allIds.some((id) => !Number.isSafeInteger(id) || id <= 0) || new Set(allIds).size !== allIds.length) {
+        throw new Error('[BehaviorExamplePackAssembler] selected tool call IDs must be unique positive integers');
+    }
+}
+function requireSelectedRow(row, id) {
+    if (!row) {
+        // PRI-983: typed scope classification → stable `owner_behavior_examples_stale`
+        // at the readiness contract (the referenced trajectory row does not exist).
+        throw createOwnerEvidenceScopeError('tool_call_not_found', `[BehaviorExamplePackAssembler] selected tool call id=${id} not found`);
+    }
+    return row;
+}
+// ── internal: case builder ─────────────────────────────────────────────────
+/**
+ * Build a GoldenTraceCaseInput from a trajectory tool_call row.
+ *
+ * ERR-001: parses params_json as unknown and structurally validates (must be
+ * a plain object without proto-pollution keys). Throws on malformed input
+ * (rc-9: no silent fallback).
+ */
+function buildCaseFromRow(row, kind, expectedDecision) {
+    if (typeof row.toolName !== 'string' || row.toolName.length === 0) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: toolName must be a non-empty string (rc-9 fail loud)`);
+    }
+    if (typeof row.paramsJson !== 'string') {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must be a string (rc-9 fail loud)`);
+    }
+    let parsedParams;
+    try {
+        parsedParams = JSON.parse(row.paramsJson);
+    }
+    catch {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson is not valid JSON (rc-9 fail loud)`);
+    }
+    if (!isPlainObject(parsedParams)) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must parse to a non-array object (rc-9 fail loud)`);
+    }
+    if (!hasNoProtoKeys(parsedParams)) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must not carry prototype-pollution keys (ERR-076, rc-9 fail loud)`);
+    }
+    return {
+        caseId: `case-${kind}-${row.id}`,
+        kind,
+        toolName: row.toolName,
+        params: parsedParams,
+        expectedDecision,
+    };
+}
+/**
+ * Redact sensitive fields from tool call params before they enter the pack.
+ *
+ * First-version policy:
+ *   - Absolute paths outside the project tree → replaced with `<redacted:absolute-path>`
+ *   - String values that look like secrets (long base64 / AKIA-style keys / etc.)
+ *     → replaced with `<redacted:secret>`
+ *
+ * Records each redaction in `notes` so the Artificer and the owner can see
+ * what was stripped (spec §7.2: redactionNotes is part of the pack contract).
+ */
+function looksLikeAbsolutePath(value) {
+    // POSIX absolute path or Windows drive path
+    return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
+}
+const SECRET_PATTERNS = [
+    /AKIA[0-9A-Z]{16}/, // AWS access key ID
+    /[A-Za-z0-9+/]{40,}/, // long base64-ish token (≥40 chars, no spaces)
+];
+function looksLikeSecret(value) {
+    if (value.length < 20)
+        return false; // too short to be a real secret
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.test(value))
+            return true;
+    }
+    return false;
+}
+function redactParams(params, projectDir) {
+    const notes = [];
+    const redacted = {};
+    for (const key of Object.keys(params)) {
+        if (PROTO_KEYS.has(key))
+            continue; // defense in depth (ERR-076)
+        const value = params[key];
+        if (typeof value !== 'string') {
+            redacted[key] = value;
+            continue;
+        }
+        // Path-like values
+        if (looksLikeAbsolutePath(value) && !value.startsWith(projectDir)) {
+            redacted[key] = '<redacted:absolute-path>';
+            notes.push(`redacted absolute path in field "${key}" (outside project tree)`);
+            continue;
+        }
+        // Secret-like values (AWS keys, long base64 tokens, etc.)
+        if (looksLikeSecret(value)) {
+            redacted[key] = '<redacted:secret>';
+            notes.push(`redacted possible secret in field "${key}"`);
+            continue;
+        }
+        redacted[key] = value;
+    }
+    return { redacted, notes };
+}
+export class BehaviorExamplePackAssembler {
+    db;
+    toolSemantics;
+    constructor(opts) {
+        this.db = opts.source;
+        this.toolSemantics = opts.toolSemantics;
+    }
+    /** Assemble only from explicit Owner labels; execution outcome is not a label. */
+    assemble(input) {
+        const pain = readTrajectoryStore(`pain lineage read for canonical_pain_id="${input.sourcePainId}"`, () => this.db.getPainEventByCanonicalId(input.sourcePainId));
+        if (!pain) {
+            // PRI-983: typed scope classification (structural marker — the readiness
+            // contract maps this to the stable `owner_behavior_examples_stale`
+            // code; FR-03: an unresolvable pain reference must never be silently
+            // reused). Message text unchanged (historical audit signature).
+            throw createOwnerEvidenceScopeError('pain_not_found', `[BehaviorExamplePackAssembler] pain event not found for canonical_pain_id="${input.sourcePainId}" (ERR-069 fail loud)`);
+        }
+        validateOwnerSelection(input);
+        const negativeRow = requireSelectedRow(readTrajectoryStore(`evidence row read for id=${input.sourceNegativeToolCallId}`, () => this.db.getRuleHostEvidenceRow(input.sourceNegativeToolCallId)), input.sourceNegativeToolCallId);
+        const positiveRows = input.positiveToolCallIds.map((id) => requireSelectedRow(readTrajectoryStore(`evidence row read for id=${id}`, () => this.db.getRuleHostEvidenceRow(id)), id));
+        for (const row of [negativeRow, ...positiveRows]) {
+            if (row.sessionId !== pain.sessionId) {
+                // PRI-983: cross pain/session selection → typed scope error → stable
+                // `owner_behavior_examples_scope_mismatch` at the readiness contract.
+                throw createOwnerEvidenceScopeError('session_mismatch', `[BehaviorExamplePackAssembler] selected tool call ${row.id} session mismatch; all examples must belong to pain session ${pain.sessionId}`);
+            }
+        }
+        const redactionNotes = [];
+        const buildCtx = { projectDir: input.projectDir, redactionNotes };
+        const sourceNegativeCase = this.buildSelectedCase(negativeRow, 'negative', buildCtx);
+        const positiveCounterexamples = positiveRows.map((row) => this.buildSelectedCase(row, 'positive', buildCtx));
+        const pack = {
+            sourceNegativeCase,
+            ownerDesiredOutcome: input.ownerDesiredOutcome,
+            positiveCounterexamples,
+            evidenceRefs: [`pain:${pain.id}`, `tool_call:${negativeRow.id}`, ...positiveRows.map((row) => `tool_call:${row.id}`)].slice(0, MAX_EVIDENCE_REFS),
+            redactionNotes,
+        };
+        // ── 9. Validate — fail loud (ERR-069) ──
+        const validation = validateBehaviorExamplePack(pack);
+        if (!validation.valid) {
+            throw new Error(`[BehaviorExamplePackAssembler] assembled pack failed validateBehaviorExamplePack: ${validation.errors.join('; ')} (ERR-069 fail loud)`);
+        }
+        return pack;
+    }
+    buildSelectedCase(row, kind, ctx) {
+        const { projectDir, redactionNotes } = ctx;
+        const base = buildCaseFromRow(row, kind, kind === 'negative' ? 'block' : 'allow');
+        const redaction = redactParams(base.params, projectDir);
+        redactionNotes.push(...redaction.notes);
+        const historyResult = readTrajectoryStore(`context history read for session=${row.sessionId} before id=${row.id}`, () => this.db.getRuleHostContextRowsBefore(row.sessionId, row.id, HISTORY_LIMIT));
+        const history = assembleBehaviorHistory(historyResult.rows, historyResult.truncated, { projectDir, toolSemantics: this.toolSemantics });
+        const action = buildRuleHostAction(row.toolName, redaction.redacted, projectDir, { canonicalKind: this.toolSemantics.resolve(row.toolName) });
+        const ruleContext = { version: 2, history, facts: computeBehaviorFacts(history, action.normalizedPath || null, null) };
+        return { ...base, params: redaction.redacted, ruleContext };
+    }
+}

package/host-runtime/dist/behavior-history.d.ts

@@ -0,0 +1,6 @@
+import type { RuleHistoryWindow, ToolSemanticRegistry } from '@principles/core/runtime-v2';
+import type { RuleHostContextRow } from '@principles/core/trajectory-types';
+export declare function assembleBehaviorHistory(rows: readonly RuleHostContextRow[], truncated: boolean, options: {
+    projectDir: string;
+    toolSemantics: ToolSemanticRegistry;
+}): RuleHistoryWindow;

package/host-runtime/dist/behavior-history.js

@@ -0,0 +1,76 @@
+/** Shared validated history assembly; host vocabulary is supplied by its owner. */
+import { extractFilePathFromParams, normalizePathPure } from '@principles/core/runtime-v2/internalization/rule-host-input-builder';
+const VALID_OUTCOMES = new Set(['success', 'failure', 'blocked']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isRuleToolOutcome(value) {
+    return typeof value === 'string' && VALID_OUTCOMES.has(value);
+}
+function unavailable(reason) {
+    return {
+        status: 'unavailable',
+        unavailableReason: reason,
+        truncated: false,
+        calls: [],
+    };
+}
+export function assembleBehaviorHistory(rows, truncated, options) {
+    const { projectDir, toolSemantics } = options;
+    const records = [];
+    for (const row of rows) {
+        // ── validate tool_name (ERR-001: unknown) ──
+        const { toolName } = row;
+        if (typeof toolName !== 'string' || toolName.length === 0) {
+            return unavailable(`row id=${row.id}: tool_name must be a non-empty string`);
+        }
+        // ── validate outcome (ERR-001: unknown, enum check) ──
+        const { outcome } = row;
+        if (!isRuleToolOutcome(outcome)) {
+            return unavailable(`row id=${row.id}: outcome "${row.outcome}" is not a valid RuleToolOutcome`);
+        }
+        // ── validate & parse params_json (ERR-001: unknown) ──
+        const paramsJsonStr = row.paramsJson;
+        if (typeof paramsJsonStr !== 'string') {
+            return unavailable(`row id=${row.id}: params_json must be a string`);
+        }
+        let parsedParams;
+        try {
+            parsedParams = JSON.parse(paramsJsonStr);
+        }
+        catch {
+            return unavailable(`row id=${row.id}: params_json is not valid JSON`);
+        }
+        // Must be a non-array object (spec §5.2)
+        if (!isPlainObject(parsedParams)) {
+            return unavailable(`row id=${row.id}: params_json must parse to a non-array object`);
+        }
+        // ── build RuleToolCallRecord ──
+        // PRI-634-F: resolve through the supplied registry (baseline + host
+        // layer) instead of baseline-only canonicalizeToolKind — production tools
+        // like 'shell'/'cmd'/'delete_file' previously degraded to 'other' here
+        // while the gate classified them as bash/write (vocabulary drift).
+        const canonicalKind = toolSemantics.resolve(toolName);
+        // Extract normalized path using the same pure logic as buildRuleHostAction
+        // (avoids production/replay drift, spec §4.4)
+        const rawPath = extractFilePathFromParams(parsedParams, {
+            isBashTool: canonicalKind === 'execute',
+            isWriteTool: canonicalKind === 'write',
+            toolName,
+        });
+        const normalizedPath = normalizePathPure(rawPath, projectDir);
+        records.push({
+            sequenceId: row.id,
+            toolName,
+            canonicalKind,
+            normalizedPath: normalizedPath === '' ? null : normalizedPath,
+            paramsSummary: parsedParams,
+            outcome,
+        });
+    }
+    return {
+        status: 'available',
+        truncated,
+        calls: records,
+    };
+}

package/host-runtime/dist/index.d.ts

@@ -85,3 +85,6 @@ export declare function createProductionHostRuntime(options?: Partial<Pick<HostR
      */
     events?: HostEventEmitter;
 }): HostRuntime;
+export * from './behavior-example-pack-assembler.js';
+export * from './behavior-history.js';
+export * from './workspace-behavior-evidence.js';

package/host-runtime/dist/index.js

@@ -265,3 +265,6 @@ export function createProductionHostRuntime(options = {}) {
         },
     });
 }
+export * from './behavior-example-pack-assembler.js';
+export * from './behavior-history.js';
+export * from './workspace-behavior-evidence.js';

package/host-runtime/dist/workspace-behavior-evidence.d.ts

@@ -0,0 +1,3 @@
+import type { BehaviorEvidencePort, ToolSemanticRegistry } from '@principles/core/runtime-v2';
+/** Lazy storage access: missing labels need no DB, and a failed open remains observable. */
+export declare function createWorkspaceBehaviorEvidencePort(workspaceDir: string, toolSemantics?: ToolSemanticRegistry): BehaviorEvidencePort;

package/host-runtime/dist/workspace-behavior-evidence.js

@@ -0,0 +1,74 @@
+/** Read-only adapter over the canonical trajectory store; never creates/migrates it. */
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { createOwnerEvidenceScopeError } from '@principles/core/runtime-v2/internalization/evidence-readiness';
+import { BehaviorExamplePackAssembler } from './behavior-example-pack-assembler.js';
+import { resolveWorkspaceHostToolSemantics } from './host-tool-semantic-resolver.js';
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function contextRow(value) {
+    if (!record(value) || typeof value.id !== 'number' || !Number.isSafeInteger(value.id)
+        || typeof value.tool_name !== 'string' || typeof value.outcome !== 'string' || typeof value.params_json !== 'string') {
+        throw new Error('Malformed trajectory context row');
+    }
+    const params = JSON.parse(value.params_json);
+    if (!record(params))
+        throw new Error('Malformed trajectory params object');
+    if (Object.keys(params).some((key) => key === '__proto__' || key === 'constructor' || key === 'prototype')) {
+        throw new Error('Unsafe keys in persisted trajectory params');
+    }
+    return { id: value.id, toolName: value.tool_name, outcome: value.outcome, paramsJson: value.params_json };
+}
+function source(db) {
+    return {
+        getPainEventByCanonicalId(id) {
+            const row = db.prepare('SELECT id, session_id FROM pain_events WHERE canonical_pain_id = ? LIMIT 1').get(id);
+            if (row === undefined)
+                return null;
+            if (!record(row) || typeof row.id !== 'number' || typeof row.session_id !== 'string')
+                throw new Error('Malformed pain lineage row');
+            return { id: row.id, sessionId: row.session_id };
+        },
+        getRuleHostEvidenceRow(id) {
+            const row = db.prepare('SELECT id, session_id, tool_name, outcome, params_json FROM tool_calls WHERE id = ? LIMIT 1').get(id);
+            if (row === undefined)
+                return null;
+            if (!record(row) || typeof row.session_id !== 'string')
+                throw new Error('Malformed trajectory evidence row');
+            return { ...contextRow(row), sessionId: row.session_id };
+        },
+        getRuleHostContextRowsBefore(sessionId, beforeId, limit) {
+            const rows = db.prepare('SELECT id, tool_name, outcome, params_json FROM tool_calls WHERE session_id = ? AND id < ? ORDER BY id DESC LIMIT ?').all(sessionId, beforeId, limit + 1);
+            return { rows: rows.slice(0, limit).reverse().map(contextRow), truncated: rows.length > limit };
+        },
+    };
+}
+/** Lazy storage access: missing labels need no DB, and a failed open remains observable. */
+export function createWorkspaceBehaviorEvidencePort(workspaceDir, toolSemantics) {
+    return {
+        assemble(selection) {
+            const resolved = toolSemantics === undefined ? resolveWorkspaceHostToolSemantics(workspaceDir) : null;
+            if (resolved !== null && !resolved.ok)
+                throw createOwnerEvidenceScopeError('evidence_source_error', resolved.reason);
+            const semantics = toolSemantics ?? (resolved !== null && resolved.ok ? resolved.registry : undefined);
+            if (semantics === undefined)
+                throw createOwnerEvidenceScopeError('evidence_source_error', 'Host tool semantics unavailable');
+            let db;
+            try {
+                db = new Database(path.join(workspaceDir, '.state', 'trajectory.db'), { readonly: true, fileMustExist: true });
+            }
+            catch (error) {
+                throw createOwnerEvidenceScopeError('evidence_source_error', `Trajectory evidence unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                // One read snapshot prevents a pack combining different trajectory revisions.
+                return db.transaction(() => new BehaviorExamplePackAssembler({ source: source(db), toolSemantics: semantics })
+                    .assemble({ ...selection, projectDir: workspaceDir }))();
+            }
+            finally {
+                db.close();
+            }
+        },
+    };
+}

package/host-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/host-runtime",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,15 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./behavior-example-pack-assembler": {
+      "types": "./dist/behavior-example-pack-assembler.d.ts",
+      "default": "./dist/behavior-example-pack-assembler.js"
+    },
+    "./behavior-history": {
+      "types": "./dist/behavior-history.d.ts",
+      "default": "./dist/behavior-history.js"
+    }
   },
   "files": [
     "dist",

package/install-layout/dist/index.d.ts

@@ -6,7 +6,23 @@ export type InstallHost = (typeof INSTALL_HOSTS)[number];
 export interface InstallManifest {
     layoutVersion: typeof INSTALL_LAYOUT_VERSION;
     mode: InstallLayoutMode;
+    /**
+     * Hosts THIS reader version recognizes. Host strings the reader does not
+     * know are NOT here — they land in `unknownHosts` so an install registered
+     * with a newer host keeps resolving instead of being rejected as malformed.
+     */
     hosts: InstallHost[];
+    /**
+     * Host strings present in the persisted `hosts` array that this reader
+     * version does not know (forward compatibility, 2026-10-16). A NEWER
+     * installer may register a host an OLDER reader never heard of; that is a
+     * compatibility warning, never "manifest malformed" — treating it as one
+     * made every pre-WorkBuddy Companion report `console_runtime_not_installed`
+     * against a healthy 3-host install and mass-stop its workers. Fail-closed
+     * stays reserved for structural damage: wrong layoutVersion, non-array or
+     * non-string hosts, bad mode, illegal workspace paths.
+     */
+    unknownHosts?: readonly string[];
     /**
      * Canonical absolute paths of Workspaces the install serves (PRI-624 Slice C).
      * Optional so pre-PRI-624 manifests stay valid; always normalized to
@@ -16,6 +32,11 @@ export interface InstallManifest {
      */
     workspaces?: readonly string[];
 }
+/** Structured forward-compatibility observation from manifest parsing (rc-9). */
+export interface InstallManifestWarning {
+    code: 'install_manifest_unknown_host';
+    host: string;
+}
 export interface InstallLayoutPaths {
     homeDir: string;
     pdDir: string;
@@ -58,6 +79,8 @@ export interface LayoutResolution {
     manifest?: InstallManifest;
     reason?: string;
     nextAction?: string;
+    /** Forward-compatibility warnings surfaced while parsing the manifest. */
+    warnings?: readonly InstallManifestWarning[];
 }
 export interface ResolveInstallLayoutOptions {
     homeDir: string;
@@ -65,10 +88,26 @@ export interface ResolveInstallLayoutOptions {
     canonicalRuntimeExists: boolean;
     legacyExtensionExists: boolean;
 }
-/** Merge one Workspace into a manifest's workspace list (installer write path). Idempotent by canonical path. */
+/**
+ * Merge one Workspace into a manifest's workspace list (installer write path). Idempotent by canonical path. */
 export declare function mergeInstallManifestWorkspaces(current: InstallManifest | undefined, workspaceDir: string): string[];
+/**
+ * The `hosts` array a manifest WRITER must persist: every registration the
+ * reader recognized plus every unknown one, deduped, known hosts first.
+ * Writers that rebuild `hosts` from `manifest.hosts` alone silently DELETE a
+ * newer host's registration — the write-side twin of the read-side
+ * unknown-host brick (2026-10-16). `undefined` yields `[]` so the installer's
+ * fresh-install path keeps working unchanged.
+ */
+export declare function installManifestHostsForPersist(manifest: InstallManifest | undefined): string[];
+/**
+ * Parse the install manifest. Structural damage fails closed with `error`;
+ * a host string this reader version does not know is a `warnings` entry and
+ * the manifest still parses (forward compatibility — see `InstallManifest.unknownHosts`).
+ */
 export declare function parseInstallManifest(value: unknown): {
     manifest?: InstallManifest;
+    warnings?: readonly InstallManifestWarning[];
     error?: string;
 };
 export declare function getInstallLayoutPaths(homeDir: string): InstallLayoutPaths;

package/install-layout/dist/index.js

@@ -8,6 +8,9 @@ function isRecord(value) {
 function isHost(value) {
     return typeof value === 'string' && INSTALL_HOSTS.includes(value);
 }
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
 /** Workspace entries must be non-empty absolute paths — the Companion spawns per-Workspace workers keyed by canonical path. */
 function parseWorkspaceList(value) {
     if (value === undefined)
@@ -25,7 +28,8 @@ function parseWorkspaceList(value) {
     }
     return { workspaces: resolved };
 }
-/** Merge one Workspace into a manifest's workspace list (installer write path). Idempotent by canonical path. */
+/**
+ * Merge one Workspace into a manifest's workspace list (installer write path). Idempotent by canonical path. */
 export function mergeInstallManifestWorkspaces(current, workspaceDir) {
     const canonical = path.resolve(workspaceDir);
     const resolved = [];
@@ -38,6 +42,22 @@ export function mergeInstallManifestWorkspaces(current, workspaceDir) {
         resolved.push(canonical);
     return resolved;
 }
+/**
+ * The `hosts` array a manifest WRITER must persist: every registration the
+ * reader recognized plus every unknown one, deduped, known hosts first.
+ * Writers that rebuild `hosts` from `manifest.hosts` alone silently DELETE a
+ * newer host's registration — the write-side twin of the read-side
+ * unknown-host brick (2026-10-16). `undefined` yields `[]` so the installer's
+ * fresh-install path keeps working unchanged.
+ */
+export function installManifestHostsForPersist(manifest) {
+    return [...new Set([...(manifest?.hosts ?? []), ...(manifest?.unknownHosts ?? [])])];
+}
+/**
+ * Parse the install manifest. Structural damage fails closed with `error`;
+ * a host string this reader version does not know is a `warnings` entry and
+ * the manifest still parses (forward compatibility — see `InstallManifest.unknownHosts`).
+ */
 export function parseInstallManifest(value) {
     if (!isRecord(value))
         return { error: 'install_manifest_malformed: expected an object' };
@@ -47,14 +67,55 @@ export function parseInstallManifest(value) {
     if (value.mode !== 'canonical' && value.mode !== 'legacy') {
         return { error: 'install_manifest_malformed: mode must be canonical or legacy' };
     }
-    if (!Array.isArray(value.hosts) || value.hosts.length === 0 || !value.hosts.every(isHost)) {
-        return { error: 'install_manifest_malformed: hosts must contain codex, openclaw and/or workbuddy' };
+    // Host entries must be non-empty strings; WHICH strings are valid hosts is
+    // version-relative knowledge, so unknown strings warn instead of failing.
+    if (!Array.isArray(value.hosts) || !value.hosts.every(isNonEmptyString)) {
+        return { error: 'install_manifest_malformed: hosts must be an array of host name strings' };
+    }
+    // Idempotency: the parser must re-read its own output. An all-unknown-hosts
+    // manifest parses to hosts: [] + unknownHosts, so the optional persisted
+    // `unknownHosts` field is accepted on input too (installManifestHostsForPersist
+    // reunifies them on write; writers persist the union into `hosts`).
+    let carriedUnknownHosts = [];
+    if (value.unknownHosts !== undefined) {
+        if (!Array.isArray(value.unknownHosts) || !value.unknownHosts.every(isNonEmptyString)) {
+            return { error: 'install_manifest_malformed: unknownHosts must be an array of host name strings' };
+        }
+        carriedUnknownHosts = value.unknownHosts.filter((host) => !isHost(host));
+    }
+    if (value.hosts.length === 0 && carriedUnknownHosts.length === 0) {
+        return { error: 'install_manifest_malformed: hosts must contain at least one host' };
+    }
+    const hosts = [];
+    const unknownHosts = [];
+    const warnings = [];
+    for (const host of [...new Set(value.hosts)]) {
+        if (isHost(host))
+            hosts.push(host);
+        else {
+            unknownHosts.push(host);
+            warnings.push({ code: 'install_manifest_unknown_host', host });
+        }
+    }
+    for (const host of carriedUnknownHosts) {
+        if (!unknownHosts.includes(host)) {
+            unknownHosts.push(host);
+            warnings.push({ code: 'install_manifest_unknown_host', host });
+        }
     }
-    const hosts = [...new Set(value.hosts)];
     const workspaces = parseWorkspaceList(value.workspaces);
     if (workspaces.error)
         return { error: workspaces.error };
-    return { manifest: { layoutVersion: INSTALL_LAYOUT_VERSION, mode: value.mode, hosts, workspaces: workspaces.workspaces } };
+    return {
+        manifest: {
+            layoutVersion: INSTALL_LAYOUT_VERSION,
+            mode: value.mode,
+            hosts,
+            ...(unknownHosts.length > 0 ? { unknownHosts } : {}),
+            workspaces: workspaces.workspaces,
+        },
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
 }
 export function getInstallLayoutPaths(homeDir) {
     const home = path.resolve(homeDir);
@@ -96,8 +157,28 @@ export function getWorkbuddyWorkspaceDir(homeDir) {
 export function resolveInstallLayout(options) {
     const paths = getInstallLayoutPaths(options.homeDir);
     const parsed = parseInstallManifest(options.manifest);
+    const { warnings } = parsed;
     if (parsed.manifest && parsed.manifest.mode === 'canonical' && options.canonicalRuntimeExists) {
-        return { mode: 'canonical', paths, manifest: parsed.manifest };
+        return { mode: 'canonical', paths, manifest: parsed.manifest, ...(warnings !== undefined ? { warnings } : {}) };
+    }
+    // RF-01 (review 2026-10-16): when a canonical runtime EXISTS, the manifest
+    // is the install-state authority. A manifest that was READ but cannot be
+    // honored (newer layoutVersion, structural damage) must refuse the whole
+    // resolution — falling through to the legacy extension dir would launch a
+    // runtime that does not match the installed protocol. Legacy fallback stays
+    // legitimate only when the reader genuinely saw NO manifest (absent file →
+    // `options.manifest === undefined`), i.e. a real legacy-only install, or
+    // when there is no canonical runtime to bypass.
+    if (options.canonicalRuntimeExists && options.manifest !== undefined && parsed.manifest === undefined) {
+        return {
+            mode: 'missing',
+            paths,
+            reason: parsed.error ?? 'install_manifest_malformed',
+            nextAction: parsed.error?.startsWith('install_manifest_unsupported_version')
+                ? 'Update PD Companion from https://github.com/csuzngjh/principles/releases (companion-v* Windows installer); do not reinstall the healthy PD runtime.'
+                : 'Run the PD installer/updater to repair the structurally damaged installation manifest.',
+            ...(warnings !== undefined ? { warnings } : {}),
+        };
     }
     if (options.legacyExtensionExists) {
         return {
@@ -106,6 +187,7 @@ export function resolveInstallLayout(options) {
             ...(parsed.manifest ? { manifest: parsed.manifest } : {}),
             reason: parsed.error ?? 'install_layout_legacy_fallback',
             nextAction: 'Run the installer update to migrate the shared runtime to ~/.pd/runtime.',
+            ...(warnings !== undefined ? { warnings } : {}),
         };
     }
     return {