@principles/install-layout 0.3.1 → 0.4.0

package/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/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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/install-layout",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",