create-principles-disciple 1.121.8 → 1.121.10

package/dist/update/install-layout.js

@@ -0,0 +1,127 @@
+/**
+ * Installation layout contract (SPEC §5).
+ *
+ * Production installation state lives under `~/.pd`:
+ *
+ *   bootstrap/  installer-owned; a product release can never overwrite it
+ *   install.json  channel selection + automatic check settings
+ *   trust/      TUF trusted root metadata cache
+ *   channels/   cached signed channel metadata
+ *   releases/<release-id>/
+ *   staging/<transaction-id>/
+ *   transactions/<transaction-id>.json
+ *   active.json / previous.json
+ *   logs/
+ *
+ * This module owns ONLY path derivation and strict readers. Every read of
+ * untrusted on-disk JSON returns `unknown` until validated (rc-1) and fails
+ * loud on malformed required fields (rc-3).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { parseProductVersion, ProductIdentityError, isReleaseChannelName } from './product-identity.js';
+export function resolvePdHomePaths(pdHome) {
+    const home = path.resolve(pdHome);
+    return {
+        home,
+        bootstrapDir: path.join(home, 'bootstrap'),
+        bootstrapManifestPath: path.join(home, 'bootstrap', 'bootstrap.json'),
+        installConfigPath: path.join(home, 'install.json'),
+        trustDir: path.join(home, 'trust'),
+        channelsDir: path.join(home, 'channels'),
+        releasesDir: path.join(home, 'releases'),
+        stagingDir: path.join(home, 'staging'),
+        transactionsDir: path.join(home, 'transactions'),
+        activeRecordPath: path.join(home, 'active.json'),
+        previousRecordPath: path.join(home, 'previous.json'),
+        logsDir: path.join(home, 'logs'),
+    };
+}
+/** Creates the installation skeleton once; never touches an existing file. */
+export function ensurePdHomeLayout(paths) {
+    for (const directory of [
+        paths.bootstrapDir, paths.trustDir, paths.channelsDir,
+        paths.releasesDir, paths.stagingDir, paths.transactionsDir, paths.logsDir,
+    ]) {
+        fs.mkdirSync(directory, { recursive: true });
+    }
+}
+export class InstallLayoutError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = 'InstallLayoutError';
+        this.field = field;
+    }
+}
+function readJsonFileIfExists(filePath, label) {
+    if (!fs.existsSync(filePath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        // A bare SyntaxError would escape every typed reader below; corrupt
+        // installation state fails loud with its own field-tagged error (rc-3).
+        throw new InstallLayoutError(label, `${label} is not valid JSON (${filePath}): ${error instanceof Error ? error.message : String(error)}. Restore it with the official installer; do not guess a partial state.`);
+    }
+}
+/** Strict reader for the installer-owned bootstrap manifest. */
+export function readBootstrapManifest(paths) {
+    const value = readJsonFileIfExists(paths.bootstrapManifestPath, 'bootstrap.json');
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new InstallLayoutError('bootstrap', `bootstrap manifest must be a JSON object: ${paths.bootstrapManifestPath}`);
+    }
+    const record = value;
+    if (!Object.hasOwn(record, 'bootstrapVersion')) {
+        throw new InstallLayoutError('bootstrapVersion', 'bootstrap manifest is missing bootstrapVersion');
+    }
+    try {
+        const { bootstrapVersion } = { bootstrapVersion: parseProductVersion(record.bootstrapVersion, 'bootstrapVersion') };
+        const { installedAt } = record;
+        if (typeof installedAt !== 'string' || installedAt.length === 0) {
+            throw new InstallLayoutError('installedAt', 'bootstrap manifest installedAt must be a non-empty timestamp string');
+        }
+        return { bootstrapVersion: bootstrapVersion.productVersion, installedAt };
+    }
+    catch (error) {
+        if (error instanceof ProductIdentityError) {
+            throw new InstallLayoutError(error.field, error.message);
+        }
+        throw error;
+    }
+}
+/**
+ * Installation-level settings (SPEC §2.3). Missing file yields the safe
+ * default (stable channel, automatic checks off); a malformed file fails
+ * loud instead of degrading to guesses.
+ */
+export function readInstallConfig(paths) {
+    const value = readJsonFileIfExists(paths.installConfigPath, 'install.json');
+    if (value === undefined)
+        return { channel: 'stable', autoCheck: false };
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new InstallLayoutError('install.json', `install.json must be a JSON object: ${paths.installConfigPath}`);
+    }
+    const record = value;
+    const channelValue = Object.hasOwn(record, 'channel') ? record.channel : 'stable';
+    if (!isReleaseChannelName(channelValue)) {
+        throw new InstallLayoutError('channel', `install.json channel must be "stable" or "candidate", got: ${JSON.stringify(channelValue)}`);
+    }
+    const autoCheckValue = Object.hasOwn(record, 'autoCheck') ? record.autoCheck : false;
+    if (typeof autoCheckValue !== 'boolean') {
+        throw new InstallLayoutError('autoCheck', `install.json autoCheck must be a boolean, got: ${JSON.stringify(autoCheckValue)}`);
+    }
+    return { channel: channelValue, autoCheck: autoCheckValue };
+}
+export function writeInstallConfig(paths, config) {
+    const payload = {
+        channel: config.channel,
+        autoCheck: config.autoCheck,
+    };
+    fs.mkdirSync(paths.home, { recursive: true });
+    fs.writeFileSync(paths.installConfigPath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+//# sourceMappingURL=install-layout.js.map

package/dist/update/install-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-layout.js","sourceRoot":"","sources":["../../src/update/install-layout.ts"],"names":[],"mappings":"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"}

package/dist/update/legacy-migration.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Official legacy-overlay migration (SPEC §15 Phase 5).
+ *
+ * ONLY an official installer transaction migrates an existing overlay
+ * installation (~/.openclaw/extensions/principles-disciple) into the
+ * bootstrap + dual-slot layout. The legacy updater must never transform
+ * itself in place. Owner data, workspace config, and governance assets are
+ * preserved untouched; the overlay directory itself is left in place as
+ * read-only legacy diagnostics for a bounded period — never deleted or
+ * rewritten by the migration.
+ *
+ * Dry-run is the default posture (cli-4): the plan describes every resolved
+ * target and the exact step list without touching anything.
+ */
+export type MigrationRefusalReason = 'overlay_missing' | 'already_migrated' | 'overlay_manifest_invalid' | 'bootstrap_write_out_of_scope';
+export interface MigrationRefusal {
+    readonly migrated: false;
+    readonly dryRun: boolean;
+    readonly reason: MigrationRefusalReason;
+    readonly message: string;
+    readonly nextAction: string;
+}
+export interface MigrationStep {
+    readonly description: string;
+    readonly resolvedTarget: string;
+}
+export interface MigrationPlan {
+    readonly migrated: true;
+    readonly dryRun: boolean;
+    readonly overlayDir: string;
+    readonly pdHome: string;
+    readonly productVersion: string;
+    readonly releaseId: string;
+    readonly steps: readonly MigrationStep[];
+    readonly historyEventPath: string;
+}
+export type MigrationResult = MigrationPlan | MigrationRefusal;
+export interface LegacyMigrationInput {
+    readonly homeDir: string;
+    readonly openclawHome: string;
+    /** Only the official installer sets this — a product release may not write the bootstrap. */
+    readonly invokedByOfficialInstaller: boolean;
+    readonly dryRun: boolean;
+    readonly bootstrapVersion: string;
+    readonly transactionId: string;
+    readonly now?: () => Date;
+}
+/**
+ * Plans (and when dryRun=false, executes) the one-time official migration.
+ * The migration: lays down the bootstrap manifest, derives the overlay's
+ * canonical release identity, records it as generation 1 of the dual-slot
+ * layout, writes install.json defaults, and appends a legacy_migration
+ * history event. The overlay tree itself is never modified.
+ */
+export declare function migrateLegacyOverlay(input: LegacyMigrationInput): MigrationResult;
+//# sourceMappingURL=legacy-migration.d.ts.map

package/dist/update/legacy-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-migration.d.ts","sourceRoot":"","sources":["../../src/update/legacy-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsBH,MAAM,MAAM,sBAAsB,GAC9B,iBAAiB,GACjB,kBAAkB,GAClB,0BAA0B,GAC1B,8BAA8B,CAAC;AAEnC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,gBAAgB,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6FAA6F;IAC7F,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AA0CD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,eAAe,CA+LjF"}

package/dist/update/legacy-migration.js

@@ -0,0 +1,254 @@
+/**
+ * Official legacy-overlay migration (SPEC §15 Phase 5).
+ *
+ * ONLY an official installer transaction migrates an existing overlay
+ * installation (~/.openclaw/extensions/principles-disciple) into the
+ * bootstrap + dual-slot layout. The legacy updater must never transform
+ * itself in place. Owner data, workspace config, and governance assets are
+ * preserved untouched; the overlay directory itself is left in place as
+ * read-only legacy diagnostics for a bounded period — never deleted or
+ * rewritten by the migration.
+ *
+ * Dry-run is the default posture (cli-4): the plan describes every resolved
+ * target and the exact step list without touching anything.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createHash } from 'node:crypto';
+import { ensurePdHomeLayout, resolvePdHomePaths } from './install-layout.js';
+import { appendJournalTransition, writeActiveRecord } from './transaction-journal.js';
+import { appendHistoryEvent, classifyDirection } from './update-history.js';
+import { deriveReleaseId } from './release-identity.js';
+import { buildReleaseMetadata } from './release-metadata.js';
+import { parseProductVersion, ProductIdentityError } from './product-identity.js';
+/** Every path this migration writes must resolve inside the target ~/.pd root. */
+function assertWithinPdHome(candidate, pdHome, label) {
+    const resolved = path.resolve(candidate);
+    const root = path.resolve(pdHome);
+    if (resolved !== root && !resolved.startsWith(root + path.sep)) {
+        throw new ProductIdentityError(label, `Migration write escaped ~/.pd (${root}): ${resolved}`);
+    }
+    return resolved;
+}
+function overlayPluginDir(openclawHome) {
+    return path.join(openclawHome, 'extensions', 'principles-disciple');
+}
+function readOverlayProductVersion(overlayDir) {
+    const manifestPath = path.join(overlayDir, 'plugin', 'package.json');
+    if (!fs.existsSync(manifestPath)) {
+        throw new ProductIdentityError('overlay', `The overlay installation has no plugin manifest: ${manifestPath}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        throw new ProductIdentityError('overlay', `The overlay plugin manifest is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new ProductIdentityError('overlay', 'The overlay plugin manifest is not an object.');
+    }
+    const version = Reflect.get(value, 'version');
+    return parseProductVersion(version, 'overlay.plugin.version').productVersion;
+}
+function overlayComponentDigests(overlayDir) {
+    const digests = [];
+    for (const component of ['plugin', 'console', 'core', 'pd-cli', 'host-runtime', 'install-layout']) {
+        const manifestPath = path.join(overlayDir, component, 'package.json');
+        if (!fs.existsSync(manifestPath))
+            continue;
+        const bytes = fs.readFileSync(manifestPath);
+        digests.push({
+            component,
+            sha256: createHash('sha256').update(bytes).digest('hex'),
+            sizeBytes: bytes.length,
+        });
+    }
+    return digests;
+}
+/**
+ * Plans (and when dryRun=false, executes) the one-time official migration.
+ * The migration: lays down the bootstrap manifest, derives the overlay's
+ * canonical release identity, records it as generation 1 of the dual-slot
+ * layout, writes install.json defaults, and appends a legacy_migration
+ * history event. The overlay tree itself is never modified.
+ */
+export function migrateLegacyOverlay(input) {
+    const now = input.now ?? (() => new Date());
+    const overlayDir = overlayPluginDir(input.openclawHome);
+    const pdHome = path.join(input.homeDir, '.pd');
+    const paths = resolvePdHomePaths(pdHome);
+    if (!fs.existsSync(overlayDir)) {
+        return {
+            migrated: false,
+            dryRun: input.dryRun,
+            reason: 'overlay_missing',
+            message: `No legacy overlay installation found at ${overlayDir}.`,
+            nextAction: 'Nothing to migrate. Install PD with the official installer for the new layout.',
+        };
+    }
+    if (fs.existsSync(paths.activeRecordPath)) {
+        return {
+            migrated: false,
+            dryRun: input.dryRun,
+            reason: 'already_migrated',
+            message: `This installation already uses the dual-slot layout (${paths.activeRecordPath} exists).`,
+            nextAction: 'Use the normal update flow; do not re-run the legacy migration.',
+        };
+    }
+    if (!input.invokedByOfficialInstaller) {
+        return {
+            migrated: false,
+            dryRun: input.dryRun,
+            reason: 'bootstrap_write_out_of_scope',
+            message: 'The bootstrap and trust root may only be written by an official installer transaction — a product release or the legacy updater cannot migrate itself in place.',
+            nextAction: 'Re-run the official installer, which performs the migration as part of its own transaction.',
+        };
+    }
+    let productVersion;
+    let componentDigests;
+    try {
+        productVersion = readOverlayProductVersion(overlayDir);
+        componentDigests = overlayComponentDigests(overlayDir);
+    }
+    catch (error) {
+        if (error instanceof ProductIdentityError) {
+            return {
+                migrated: false,
+                dryRun: input.dryRun,
+                reason: 'overlay_manifest_invalid',
+                message: error.message,
+                nextAction: 'Reinstall the overlay with the official installer so its manifests are complete, then retry the migration.',
+            };
+        }
+        throw error;
+    }
+    // The migrated overlay's release identity is derived from the overlay's own
+    // component digests — canonical identity, not a checkout package.json.
+    const releaseId = deriveReleaseId({
+        productVersion,
+        sourceCommit: '0'.repeat(40),
+        minBootstrapVersion: input.bootstrapVersion,
+        assets: componentDigests.map((digest) => ({
+            platform: `overlay-${digest.component}`,
+            arch: 'x64',
+            nodeAbi: '0',
+            archiveSha256: digest.sha256,
+            archiveSizeBytes: digest.sizeBytes,
+        })),
+    });
+    const steps = [
+        { description: 'Create the ~/.pd installation skeleton', resolvedTarget: paths.home },
+        { description: `Write the installer-owned bootstrap manifest (v${input.bootstrapVersion})`, resolvedTarget: paths.bootstrapManifestPath },
+        { description: `Record the overlay release ${productVersion} as generation 1`, resolvedTarget: path.join(paths.releasesDir, releaseId) },
+        { description: 'Write installation defaults (stable channel, automatic checks off)', resolvedTarget: paths.installConfigPath },
+        { description: 'Append the legacy_migration history event (overlay remains read-only)', resolvedTarget: path.join(paths.logsDir, 'history.jsonl') },
+    ];
+    if (input.dryRun) {
+        return {
+            migrated: true,
+            dryRun: true,
+            overlayDir,
+            pdHome,
+            productVersion,
+            releaseId,
+            steps,
+            historyEventPath: path.join(paths.logsDir, 'history.jsonl'),
+        };
+    }
+    const journalPath = assertWithinPdHome(path.join(paths.transactionsDir, `${input.transactionId}.jsonl`), pdHome, 'journal');
+    const bootstrapManifestPath = assertWithinPdHome(paths.bootstrapManifestPath, pdHome, 'bootstrap');
+    const releaseDir = assertWithinPdHome(path.join(paths.releasesDir, releaseId), pdHome, 'releases');
+    const releaseMetadataPath = assertWithinPdHome(path.join(releaseDir, 'metadata.json'), pdHome, 'release-metadata');
+    const activeRecordPath = assertWithinPdHome(paths.activeRecordPath, pdHome, 'active-record');
+    const installConfigPath = assertWithinPdHome(paths.installConfigPath, pdHome, 'install-config');
+    const historyPath = assertWithinPdHome(path.join(paths.logsDir, 'history.jsonl'), pdHome, 'history');
+    // The migrated release's metadata is built through the strict producer so
+    // its releaseId AND canonical metadataDigest close the identity chain —
+    // placeholder digests would fail verifyReleaseMetadataIdentity on the
+    // first future update check.
+    const migratedRelease = buildReleaseMetadata({
+        productVersion,
+        sourceCommit: '0'.repeat(40),
+        minBootstrapVersion: input.bootstrapVersion,
+        publicationSequence: 1,
+        expiresAt: '9999-12-31T00:00:00Z',
+        assets: componentDigests.map((digest) => ({
+            platform: `overlay-${digest.component}`,
+            arch: 'x64',
+            nodeAbi: '0',
+            archiveSha256: digest.sha256,
+            archiveSizeBytes: digest.sizeBytes,
+        })),
+        dataSchemaForwardReadableFrom: productVersion,
+    });
+    if (migratedRelease.releaseId !== releaseId) {
+        throw new ProductIdentityError('releaseId', 'Migration identity derivation diverged between planning and execution.');
+    }
+    const transition = (from, to, detail) => {
+        appendJournalTransition(journalPath, {
+            at: now().toISOString(),
+            from,
+            to,
+            transactionId: input.transactionId,
+            releaseId,
+            productVersion,
+            releaseMetadataDigest: migratedRelease.metadataDigest,
+            generation: 1,
+            detail,
+        });
+    };
+    // Journal-first ordering (SPEC §8): EVERY transition is appended and
+    // fsynced BEFORE the side effect it describes. A crash between a journal
+    // append and its side effect is always recoverable (re-running the
+    // migration or the recovery rules sees the intent); a crash between a side
+    // effect and its journal append is not (the journal understates reality).
+    transition(null, 'planned', 'official legacy migration planned');
+    ensurePdHomeLayout(paths);
+    transition('planned', 'staged', 'writing the installer-owned bootstrap manifest');
+    fs.writeFileSync(bootstrapManifestPath, `${JSON.stringify({
+        bootstrapVersion: input.bootstrapVersion,
+        installedAt: now().toISOString(),
+    }, null, 2)}\n`);
+    transition('staged', 'probed', 'recording the overlay identity as the generation 1 release');
+    fs.mkdirSync(releaseDir, { recursive: true });
+    fs.writeFileSync(releaseMetadataPath, `${JSON.stringify(migratedRelease, null, 2)}\n`);
+    transition('probed', 'activated', 'writing the generation 1 active record');
+    writeActiveRecord(activeRecordPath, {
+        generation: 1,
+        releaseId,
+        releaseMetadataDigest: migratedRelease.metadataDigest,
+        previousReleaseId: null,
+        transactionId: input.transactionId,
+        productVersion,
+    });
+    // No previous.json: a freshly migrated installation has exactly ONE slot.
+    // Copying the generation-1 record here would let a rollback "succeed" as a
+    // no-op onto the same release while reporting a switch.
+    transition('activated', 'confirmed', 'confirming the legacy migration; overlay tree left untouched as read-only diagnostics');
+    fs.writeFileSync(installConfigPath, `${JSON.stringify({ channel: 'stable', autoCheck: false }, null, 2)}\n`);
+    appendHistoryEvent(historyPath, {
+        at: now().toISOString(),
+        kind: 'legacy_migration',
+        direction: classifyDirection({ kind: 'legacy_migration', releasePublicationSequence: 1, previousPublicationSequence: null }),
+        outcome: 'succeeded',
+        productVersion,
+        releaseId,
+        previousReleaseId: null,
+        previousRemainsActive: false,
+        reason: `Migrated the overlay installation at ${overlayDir} into the dual-slot layout; the overlay tree is preserved read-only.`,
+        nextAction: null,
+        transactionId: input.transactionId,
+    });
+    return {
+        migrated: true,
+        dryRun: false,
+        overlayDir,
+        pdHome,
+        productVersion,
+        releaseId,
+        steps,
+        historyEventPath: historyPath,
+    };
+}
+//# sourceMappingURL=legacy-migration.js.map

package/dist/update/legacy-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-migration.js","sourceRoot":"","sources":["../../src/update/legacy-migration.ts"],"names":[],"mappings":"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"}

package/dist/update/product-identity.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Canonical product identity (SPEC §4.1, §12).
+ *
+ * The product has ONE public `productVersion`. Component package versions are
+ * diagnostics. This module owns the strict runtime contract every surface
+ * (CLI, Console, Companion, manifest) must share so they can never report
+ * incompatible meanings of "current version".
+ */
+export type ReleaseChannelName = 'stable' | 'candidate';
+export interface CanonicalProductVersion {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+    readonly productVersion: string;
+}
+export declare class ProductIdentityError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/** Strict `x.y.z` parse — no prerelease/build suffixes in the product version. */
+export declare function parseProductVersion(value: unknown, field?: string): CanonicalProductVersion;
+/** Total-order comparison; negative when `left` is older than `right`. */
+export declare function compareProductVersions(left: CanonicalProductVersion, right: CanonicalProductVersion): number;
+export declare function isSha256Hex(value: unknown): value is string;
+export declare function assertSha256Hex(value: unknown, field: string): string;
+export declare function assertGitCommit(value: unknown, field: string): string;
+export declare function isReleaseChannelName(value: unknown): value is ReleaseChannelName;
+/**
+ * `pd version --json` report (SPEC §12). Phase 1 defines the contract; the
+ * product surfaces fill it in Phase 6. Every field is required so a missing
+ * fact fails loud instead of degrading into a partial lie.
+ */
+export interface VersionReport {
+    readonly productVersion: string;
+    readonly releaseId: string;
+    readonly components: Readonly<Record<string, string>>;
+    readonly bootstrapVersion: string;
+    readonly channel: ReleaseChannelName;
+    readonly source: 'official-installer' | 'official-legacy-overlay' | 'development-checkout' | 'unknown';
+    readonly generation: number;
+    readonly health: 'healthy' | 'degraded' | 'corrupt';
+    readonly lastTransaction: Readonly<{
+        id: string;
+        kind: string;
+        outcome: string;
+    }> | null;
+}
+/** `pd --version` short stable text contract: `Principles Disciple <version> (<releaseId prefix>)`. */
+export declare function formatShortVersion(report: Pick<VersionReport, 'productVersion' | 'releaseId'>): string;
+//# sourceMappingURL=product-identity.d.ts.map

package/dist/update/product-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-identity.d.ts","sourceRoot":"","sources":["../../src/update/product-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,WAAW,CAAC;AAMxD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIzC;CACF;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAmB,GAAG,uBAAuB,CAWrG;AAED,0EAA0E;AAC1E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,uBAAuB,EAAE,KAAK,EAAE,uBAAuB,GAAG,MAAM,CAI5G;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAEhF;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,yBAAyB,GAAG,sBAAsB,GAAG,SAAS,CAAC;IACvG,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,eAAe,EAAE,QAAQ,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;CAC1F;AAED,uGAAuG;AACvG,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,gBAAgB,GAAG,WAAW,CAAC,GAAG,MAAM,CAEtG"}

package/dist/update/product-identity.js

@@ -0,0 +1,63 @@
+/**
+ * Canonical product identity (SPEC §4.1, §12).
+ *
+ * The product has ONE public `productVersion`. Component package versions are
+ * diagnostics. This module owns the strict runtime contract every surface
+ * (CLI, Console, Companion, manifest) must share so they can never report
+ * incompatible meanings of "current version".
+ */
+const PRODUCT_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const SHA256_HEX_PATTERN = /^[a-f0-9]{64}$/;
+const GIT_COMMIT_PATTERN = /^[a-f0-9]{40}$/;
+export class ProductIdentityError extends Error {
+    field;
+    constructor(field, message) {
+        super(message);
+        this.name = 'ProductIdentityError';
+        this.field = field;
+    }
+}
+/** Strict `x.y.z` parse — no prerelease/build suffixes in the product version. */
+export function parseProductVersion(value, field = 'productVersion') {
+    if (typeof value !== 'string' || !PRODUCT_VERSION_PATTERN.test(value)) {
+        throw new ProductIdentityError(field, `${field} must be a strict x.y.z version, got: ${JSON.stringify(value)}`);
+    }
+    const [major, minor, patch] = value.split('.');
+    return {
+        major: Number(major),
+        minor: Number(minor),
+        patch: Number(patch),
+        productVersion: value,
+    };
+}
+/** Total-order comparison; negative when `left` is older than `right`. */
+export function compareProductVersions(left, right) {
+    if (left.major !== right.major)
+        return left.major - right.major;
+    if (left.minor !== right.minor)
+        return left.minor - right.minor;
+    return left.patch - right.patch;
+}
+export function isSha256Hex(value) {
+    return typeof value === 'string' && SHA256_HEX_PATTERN.test(value);
+}
+export function assertSha256Hex(value, field) {
+    if (!isSha256Hex(value)) {
+        throw new ProductIdentityError(field, `${field} must be a lowercase 64-char sha256 hex digest, got: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+export function assertGitCommit(value, field) {
+    if (typeof value !== 'string' || !GIT_COMMIT_PATTERN.test(value)) {
+        throw new ProductIdentityError(field, `${field} must be a 40-char git commit sha, got: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+export function isReleaseChannelName(value) {
+    return value === 'stable' || value === 'candidate';
+}
+/** `pd --version` short stable text contract: `Principles Disciple <version> (<releaseId prefix>)`. */
+export function formatShortVersion(report) {
+    return `Principles Disciple ${report.productVersion} (${report.releaseId.slice(0, 12)})`;
+}
+//# sourceMappingURL=product-identity.js.map

package/dist/update/product-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-identity.js","sourceRoot":"","sources":["../../src/update/product-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,uBAAuB,GAAG,4CAA4C,CAAC;AAC7E,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAC5C,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAS5C,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,KAAK,CAAS;IAEvB,YAAY,KAAa,EAAE,OAAe;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,UAAU,mBAAmB,CAAC,KAAc,EAAE,KAAK,GAAG,gBAAgB;IAC1E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,oBAAoB,CAAC,KAAK,EAAE,GAAG,KAAK,yCAAyC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClH,CAAC;IACD,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC;QACpB,cAAc,EAAE,KAAK;KACtB,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,sBAAsB,CAAC,IAA6B,EAAE,KAA8B;IAClG,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAChE,IAAI,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAChE,OAAO,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,KAAa;IAC3D,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,oBAAoB,CAAC,KAAK,EAAE,GAAG,KAAK,wDAAwD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACjI,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,KAAa;IAC3D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,oBAAoB,CAAC,KAAK,EAAE,GAAG,KAAK,2CAA2C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACpH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAc;IACjD,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,WAAW,CAAC;AACrD,CAAC;AAmBD,uGAAuG;AACvG,MAAM,UAAU,kBAAkB,CAAC,MAA2D;IAC5F,OAAO,uBAAuB,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC;AAC3F,CAAC"}

package/dist/update/release-asset-manifest.d.ts

@@ -0,0 +1,31 @@
+export interface ReleaseAssetManifestFile {
+    path: string;
+    sha256: string;
+    size: number;
+}
+export interface ReleaseAssetManifest {
+    files: ReleaseAssetManifestFile[];
+    schemaVersion: 1;
+}
+export interface ReleaseAssetIdentity {
+    arch: string;
+    nodeAbi: string;
+    platform: string;
+    schemaVersion: 1;
+}
+export type ReleaseAssetManifestErrorCode = 'asset_directory_missing' | 'asset_file_unexpected' | 'asset_digest_mismatch' | 'asset_identity_invalid' | 'asset_manifest_invalid' | 'asset_path_unsafe' | 'asset_target_mismatch';
+export declare class ReleaseAssetManifestError extends Error {
+    readonly code: ReleaseAssetManifestErrorCode;
+    constructor(code: ReleaseAssetManifestErrorCode, message: string);
+}
+export declare function parseReleaseAssetManifest(value: unknown): ReleaseAssetManifest;
+export declare function parseReleaseAssetIdentity(value: unknown): ReleaseAssetIdentity;
+export declare function verifyReleaseAssetTarget(identity: ReleaseAssetIdentity, target: {
+    platform: string;
+    arch: string;
+    nodeAbi: string;
+}): void;
+export declare function createReleaseAssetManifest(assetDir: string): ReleaseAssetManifest;
+export declare function verifyReleaseAssetManifest(assetDir: string, manifest: ReleaseAssetManifest): void;
+export declare function verifyReleaseAssetManifestAsync(assetDir: string, manifest: ReleaseAssetManifest): Promise<void>;
+//# sourceMappingURL=release-asset-manifest.d.ts.map

package/dist/update/release-asset-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-asset-manifest.d.ts","sourceRoot":"","sources":["../../src/update/release-asset-manifest.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,wBAAwB,EAAE,CAAC;IAClC,aAAa,EAAE,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,CAAC,CAAC;CAClB;AAED,MAAM,MAAM,6BAA6B,GACrC,yBAAyB,GACzB,uBAAuB,GACvB,uBAAuB,GACvB,wBAAwB,GACxB,wBAAwB,GACxB,mBAAmB,GACnB,uBAAuB,CAAC;AAE5B,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAE7C,YAAY,IAAI,EAAE,6BAA6B,EAAE,OAAO,EAAE,MAAM,EAI/D;CACF;AAiED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAqB9E;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,CAa9E;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1D,IAAI,CAUN;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAEjF;AAED,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAgBjG;AAED,wBAAsB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CA2BrH"}