create-principles-disciple 1.121.7 → 1.121.9

package/dist/update/release-manager.js

@@ -0,0 +1,253 @@
+/**
+ * ReleaseManager — the deep module behind every update surface (SPEC §6.2).
+ *
+ * External surface is intentionally small: inspect / check / apply /
+ * rollback. The module hides metadata validation, download, extraction,
+ * staging, probes, journaling, host control, rollback, and cleanup. In this
+ * phase (shadow mode) apply/rollback refuse read-only: activation lands with
+ * the transaction state machine, never by loosening this gate.
+ *
+ * Every refusal carries a stable reason and an Owner-visible next action
+ * (rc-9) and is computed BEFORE any installation state is mutated.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { resolveTrustedReleaseTarget, downloadTrustedReleasePayload, ReleaseTrustError } from './trust-metadata.js';
+import { parseChannelMetadata } from './channel-metadata.js';
+import { buildReleaseMetadata, isReleaseMetadataExpired, parseReleaseMetadata, verifyReleaseMetadataIdentity, } from './release-metadata.js';
+import { evaluateReleaseAdvancement, } from './release-policy.js';
+import { readBootstrapManifest, readInstallConfig, resolvePdHomePaths, } from './install-layout.js';
+import { readActiveRecord, TransactionJournalError } from './transaction-journal.js';
+export class ReleaseManagerError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, message, nextAction) {
+        super(message);
+        this.name = 'ReleaseManagerError';
+        this.reason = reason;
+        this.nextAction = nextAction;
+    }
+}
+/**
+ * Single authority for active.json: the transaction journal's strict reader
+ * (schemaVersion + full field set). This adapter only maps its corruption
+ * error onto the ReleaseManager surface contract — it must never re-parse or
+ * re-validate the file with a second, weaker schema.
+ */
+function readActiveReleaseRecord(paths) {
+    try {
+        return readActiveRecord(paths.activeRecordPath);
+    }
+    catch (error) {
+        if (error instanceof TransactionJournalError) {
+            throw new ReleaseManagerError('active_record_corrupt', `active.json is corrupt and must be recovered from the transaction journal: ${paths.activeRecordPath} (${error.message})`, 'Run the official installer recovery or an explicit update operation; the last journal-confirmed release is selected automatically.');
+        }
+        throw error;
+    }
+}
+/**
+ * Reads a cached TUF-verified document, mapping corrupt JSON to the
+ * ReleaseManager error contract instead of leaking a bare SyntaxError
+ * (rc-3/rc-9: corrupted required state fails loud with a next action).
+ */
+function parseCachedJson(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new ReleaseManagerError('release_metadata_invalid', `A cached verified metadata document is not valid JSON (${filePath}): ${error instanceof Error ? error.message : String(error)}`, 'The cached document disagrees with its verified digest chain. Re-run the update check to re-verify and replace it.');
+    }
+}
+/**
+ * The signed channel document is fetched from the trusted TUF target
+ * `channels/<channel>.json`; its payload is the ChannelMetadata. The release
+ * metadata document comes from `releases/<release-id>/metadata.json` —
+ * already verified as a trusted target with an exact digest.
+ */
+export class ReleaseManager {
+    paths;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.paths = resolvePdHomePaths(options.pdHome);
+    }
+    inspect() {
+        const installConfig = readInstallConfig(this.paths);
+        const bootstrap = readBootstrapManifest(this.paths);
+        const active = readActiveReleaseRecord(this.paths);
+        // readActiveRecord returns null only when active.json is absent, so the
+        // releases/ skeleton alone distinguishes a pre-activation dual-slot root.
+        const layout = active !== null
+            ? 'dual-slot'
+            : fs.existsSync(this.paths.releasesDir)
+                ? 'dual-slot'
+                : fs.existsSync(this.legacyOverlayMarker())
+                    ? 'legacy-overlay'
+                    : 'none';
+        return {
+            layout,
+            productVersion: active?.productVersion ?? null,
+            releaseId: active?.releaseId ?? null,
+            generation: active?.generation ?? null,
+            bootstrapVersion: bootstrap?.bootstrapVersion ?? null,
+            channel: installConfig.channel,
+        };
+    }
+    async check(channel) {
+        const now = this.options.now ?? (() => new Date());
+        const status = this.inspect();
+        const channelTargetPath = `channels/${channel}.json`;
+        let trustedTarget;
+        try {
+            trustedTarget = await resolveTrustedReleaseTarget({
+                metadataDir: this.paths.trustDir,
+                metadataBaseUrl: this.options.metadataBaseUrl,
+                targetPath: channelTargetPath,
+                expectedChannel: channel,
+                expectedPlatform: 'metadata',
+                fetcher: this.options.fetcher,
+            });
+        }
+        catch (error) {
+            if (error instanceof ReleaseTrustError) {
+                throw new ReleaseManagerError('metadata_refresh_failed', error.message, error.nextAction);
+            }
+            throw error;
+        }
+        // Download the digest-verified channel payload into the installation's
+        // channels cache before parsing it (verify-then-trust, never the reverse).
+        await downloadTrustedReleasePayload({
+            metadataDir: this.paths.trustDir,
+            metadataBaseUrl: this.options.metadataBaseUrl,
+            targetPath: channelTargetPath,
+            destinationPath: path.join(this.paths.channelsDir, `${channel}.json`),
+            fetcher: this.options.fetcher,
+        });
+        const channelMetadata = this.readChannelMetadataPayload(channel);
+        const releaseMetadata = this.readReleaseMetadataDocument(channelMetadata, now);
+        // Current state for the advancement policy comes from the ACTIVE release's
+        // own metadata when a dual-slot installation exists.
+        let decision = evaluateReleaseAdvancement({
+            channel: channelMetadata,
+            candidate: releaseMetadata,
+            current: null,
+            bootstrapVersion: status.bootstrapVersion ?? '0.0.0',
+            now: now(),
+        });
+        if (status.releaseId !== null && status.productVersion !== null) {
+            const activeMetadata = this.readActiveReleaseMetadata(status.releaseId);
+            if (activeMetadata !== null) {
+                decision = evaluateReleaseAdvancement({
+                    channel: channelMetadata,
+                    candidate: releaseMetadata,
+                    current: {
+                        productVersion: status.productVersion,
+                        releaseId: status.releaseId,
+                        publicationSequence: activeMetadata.publicationSequence,
+                        bootstrapVersion: status.bootstrapVersion ?? '0.0.0',
+                        previouslyConfirmedReleaseIds: [status.releaseId],
+                    },
+                    bootstrapVersion: status.bootstrapVersion ?? '0.0.0',
+                    now: now(),
+                });
+            }
+        }
+        const candidate = {
+            productVersion: releaseMetadata.productVersion,
+            releaseId: releaseMetadata.releaseId,
+            publicationSequence: releaseMetadata.publicationSequence,
+            assets: releaseMetadata.assets.map((asset) => ({
+                platform: asset.platform,
+                arch: asset.arch,
+                nodeAbi: asset.nodeAbi,
+            })),
+        };
+        const shadowComparison = await this.compareWithLegacyUpdater(status, decision, candidate.productVersion);
+        return {
+            channel,
+            candidate,
+            decision,
+            trustedTarget,
+            shadowComparison,
+        };
+    }
+    async apply() {
+        void this.paths; // reserved: Phase 4 activation drives this.paths / this.options
+        throw new ReleaseManagerError('shadow_mode_read_only', 'Release application is not enabled yet: the ReleaseManager runs in read-only shadow mode while the transactional activation system is brought up.', 'Continue using the current update path. Activation arrives with the dual-slot transaction rollout; this refusal protects against hybrid installations.');
+    }
+    async rollback() {
+        void this.paths; // reserved: Phase 4 rollback drives this.paths / this.options
+        throw new ReleaseManagerError('shadow_mode_read_only', 'Rollback is not enabled yet: the ReleaseManager runs in read-only shadow mode while the transactional activation system is brought up.', 'Continue using the current update path. Rollback arrives with the dual-slot transaction rollout.');
+    }
+    legacyOverlayMarker() {
+        const openclawRoot = this.options.openclawHome
+            ?? path.join(os.homedir(), '.openclaw');
+        return path.join(openclawRoot, 'extensions', 'principles-disciple');
+    }
+    readChannelMetadataPayload(channel) {
+        // The channel payload was downloaded and digest-verified by the TUF chain
+        // before this reader parses it (verify-then-trust).
+        const payloadPath = path.join(this.paths.channelsDir, `${channel}.json`);
+        if (!fs.existsSync(payloadPath)) {
+            throw new ReleaseManagerError('release_metadata_unavailable', `The signed channel payload is not cached locally: ${payloadPath}`, 'Re-run the update check so the verified channel payload is stored, then retry.');
+        }
+        const payload = parseCachedJson(payloadPath);
+        return parseChannelMetadata(payload);
+    }
+    readActiveReleaseMetadata(releaseId) {
+        const metadataPath = path.join(this.paths.releasesDir, releaseId, 'metadata.json');
+        if (!fs.existsSync(metadataPath))
+            return null;
+        const document = parseCachedJson(metadataPath);
+        const metadata = parseReleaseMetadata(document);
+        verifyReleaseMetadataIdentity(metadata);
+        return metadata;
+    }
+    readReleaseMetadataDocument(channel, now) {
+        const releaseDir = path.join(this.paths.releasesDir, channel.releaseId);
+        const metadataPath = path.join(releaseDir, 'metadata.json');
+        if (!fs.existsSync(metadataPath)) {
+            throw new ReleaseManagerError('release_metadata_unavailable', `Release metadata for ${channel.productVersion} is not available locally: ${metadataPath}`, 'This shadow-mode check only evaluates already-verified metadata. Download arrives with the transactional updater.');
+        }
+        const document = parseCachedJson(metadataPath);
+        const metadata = parseReleaseMetadata(document);
+        verifyReleaseMetadataIdentity(metadata);
+        if (isReleaseMetadataExpired(metadata, now())) {
+            throw new ReleaseManagerError('release_metadata_invalid', `Release metadata for ${metadata.productVersion} expired at ${metadata.expiresAt}.`, 'Wait for refreshed signed metadata from the official repository.');
+        }
+        if (metadata.metadataDigest !== channel.releaseMetadataDigest) {
+            throw new ReleaseManagerError('release_metadata_invalid', 'The cached release metadata does not match the digest the signed channel points at.', 'Re-run the update check to re-verify metadata, then retry.');
+        }
+        return metadata;
+    }
+    async compareWithLegacyUpdater(status, decision, candidateVersion) {
+        if (this.options.legacyCheck === undefined || status.productVersion === null) {
+            return { legacy: null, agrees: null, note: 'legacy comparison unavailable (no legacy updater or no active release)' };
+        }
+        let failureNote = null;
+        const legacy = await this.options.legacyCheck(status.productVersion).catch((error) => {
+            failureNote = `legacy updater failed: ${error instanceof Error ? error.message : String(error)}`;
+            return null;
+        });
+        if (failureNote !== null) {
+            return { legacy: null, agrees: null, note: failureNote };
+        }
+        if (legacy === null) {
+            return { legacy: null, agrees: null, note: 'legacy updater returned no decision' };
+        }
+        const newWouldAdvance = decision.allowed && decision.direction !== 'reinstall';
+        const legacyWouldAdvance = legacy.updateAvailable === true
+            && legacy.latestVersion !== null
+            && legacy.latestVersion !== status.productVersion;
+        const agrees = newWouldAdvance === legacyWouldAdvance;
+        return {
+            legacy,
+            agrees,
+            note: agrees ? null : `decision mismatch: new=${newWouldAdvance ? 'advance' : 'no-advance'} (${candidateVersion}) legacy=${legacyWouldAdvance ? 'advance' : 'no-advance'} (${legacy.latestVersion ?? 'unknown'})`,
+        };
+    }
+}
+/** Producer helper re-exported for the publication pipeline. */
+export { buildReleaseMetadata };
+//# sourceMappingURL=release-manager.js.map

package/dist/update/release-manager.js.map

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

package/dist/update/release-metadata.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Strict Release Metadata contract (SPEC §4.2).
+ *
+ * Release Metadata is immutable after publication. It records product
+ * version, release ID, source commit, asset digests, supported platforms,
+ * minimum bootstrap version, compatibility constraints, and the publication
+ * sequence. Signed envelopes arrive as `unknown`; nothing is trusted until
+ * this validator accepts it. Required fields fail loud (rc-3), elements are
+ * validated (rc-4), and own-property access is used throughout (rc-5).
+ */
+import { type ReleaseAssetIdentity } from './release-identity.js';
+export declare const RELEASE_METADATA_SCHEMA_VERSION = 1;
+export interface ReleaseMetadata {
+    readonly schemaVersion: number;
+    readonly productVersion: string;
+    readonly releaseId: string;
+    readonly sourceCommit: string;
+    readonly metadataDigest: string;
+    readonly minBootstrapVersion: string;
+    readonly publicationSequence: number;
+    readonly expiresAt: string;
+    readonly assets: readonly ReleaseAssetIdentity[];
+    readonly compatibility: {
+        readonly dataSchemaForwardReadableFrom: string;
+    };
+}
+export type ReleaseMetadataErrorCode = 'release_metadata_invalid' | 'release_metadata_identity_mismatch';
+export declare class ReleaseMetadataError extends Error {
+    readonly code: ReleaseMetadataErrorCode;
+    readonly field: string;
+    constructor(code: ReleaseMetadataErrorCode, field: string, message: string);
+}
+/**
+ * Field-by-field strict parse. Rejects unknown top-level fields so a future
+ * schema change fails loud instead of silently dropping meaning.
+ */
+export declare function parseReleaseMetadata(value: unknown): ReleaseMetadata;
+/**
+ * Verifies the internal identity chain: recomputing the release ID from the
+ * metadata's own content must reproduce `releaseId`, and the canonical
+ * document digest must reproduce `metadataDigest`. A metadata document whose
+ * identity does not close is refuse-before-activation (SPEC §4.3).
+ */
+export declare function verifyReleaseMetadataIdentity(metadata: ReleaseMetadata): void;
+export declare function isReleaseMetadataExpired(metadata: ReleaseMetadata, now?: Date): boolean;
+/** Builds a well-formed metadata document from identity inputs (producer side). */
+export declare function buildReleaseMetadata(input: {
+    productVersion: string;
+    sourceCommit: string;
+    minBootstrapVersion: string;
+    publicationSequence: number;
+    expiresAt: string;
+    assets: readonly ReleaseAssetIdentity[];
+    dataSchemaForwardReadableFrom: string;
+}): ReleaseMetadata;
+export declare function isReleaseMetadata(value: unknown): value is ReleaseMetadata;
+//# sourceMappingURL=release-metadata.d.ts.map

package/dist/update/release-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-metadata.d.ts","sourceRoot":"","sources":["../../src/update/release-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AASH,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,aAAa,EAAE;QACtB,QAAQ,CAAC,6BAA6B,EAAE,MAAM,CAAC;KAChD,CAAC;CACH;AAED,MAAM,MAAM,wBAAwB,GAChC,0BAA0B,GAC1B,oCAAoC,CAAC;AAEzC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,IAAI,EAAE,wBAAwB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAKzE;CACF;AA+BD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAkFpE;AAgBD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAsB7E;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,GAAE,IAAiB,GAAG,OAAO,CAEnG;AAED,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACxC,6BAA6B,EAAE,MAAM,CAAC;CACvC,GAAG,eAAe,CAkBlB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAS1E"}

package/dist/update/release-metadata.js

@@ -0,0 +1,200 @@
+/**
+ * Strict Release Metadata contract (SPEC §4.2).
+ *
+ * Release Metadata is immutable after publication. It records product
+ * version, release ID, source commit, asset digests, supported platforms,
+ * minimum bootstrap version, compatibility constraints, and the publication
+ * sequence. Signed envelopes arrive as `unknown`; nothing is trusted until
+ * this validator accepts it. Required fields fail loud (rc-3), elements are
+ * validated (rc-4), and own-property access is used throughout (rc-5).
+ */
+import { assertGitCommit, assertSha256Hex, isSha256Hex, parseProductVersion, ProductIdentityError, } from './product-identity.js';
+import { canonicalJson, computeReleaseContentDigest, deriveReleaseId, } from './release-identity.js';
+export const RELEASE_METADATA_SCHEMA_VERSION = 1;
+export class ReleaseMetadataError extends Error {
+    code;
+    field;
+    constructor(code, field, message) {
+        super(message);
+        this.name = 'ReleaseMetadataError';
+        this.code = code;
+        this.field = field;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireOwn(record, field) {
+    if (!Object.hasOwn(record, field)) {
+        throw new ReleaseMetadataError('release_metadata_invalid', field, `Release metadata is missing required field "${field}"`);
+    }
+    return record[field];
+}
+function parseRfc3339Utc(value, field) {
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/.test(value)) {
+        throw new ReleaseMetadataError('release_metadata_invalid', field, `${field} must be an RFC3339 UTC timestamp ending in Z, got: ${JSON.stringify(value)}`);
+    }
+    const time = Date.parse(value);
+    if (Number.isNaN(time)) {
+        throw new ReleaseMetadataError('release_metadata_invalid', field, `${field} is not a valid date: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parsePositiveInteger(value, field) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new ReleaseMetadataError('release_metadata_invalid', field, `${field} must be a positive safe integer, got: ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/**
+ * Field-by-field strict parse. Rejects unknown top-level fields so a future
+ * schema change fails loud instead of silently dropping meaning.
+ */
+export function parseReleaseMetadata(value) {
+    if (!isPlainObject(value)) {
+        throw new ReleaseMetadataError('release_metadata_invalid', 'root', 'Release metadata must be a JSON object');
+    }
+    const record = value;
+    const schemaVersion = requireOwn(record, 'schemaVersion');
+    if (schemaVersion !== RELEASE_METADATA_SCHEMA_VERSION) {
+        throw new ReleaseMetadataError('release_metadata_invalid', 'schemaVersion', `Unsupported release metadata schemaVersion: ${JSON.stringify(schemaVersion)}`);
+    }
+    const { productVersion } = parseProductVersion(requireOwn(record, 'productVersion'));
+    const minBootstrapVersion = parseProductVersion(requireOwn(record, 'minBootstrapVersion'), 'minBootstrapVersion').productVersion;
+    const sourceCommit = assertGitCommit(requireOwn(record, 'sourceCommit'), 'sourceCommit');
+    const releaseId = assertSha256Hex(requireOwn(record, 'releaseId'), 'releaseId');
+    const metadataDigest = assertSha256Hex(requireOwn(record, 'metadataDigest'), 'metadataDigest');
+    const publicationSequence = parsePositiveInteger(requireOwn(record, 'publicationSequence'), 'publicationSequence');
+    const expiresAt = parseRfc3339Utc(requireOwn(record, 'expiresAt'), 'expiresAt');
+    const assetsValue = requireOwn(record, 'assets');
+    if (!Array.isArray(assetsValue) || assetsValue.length === 0) {
+        throw new ReleaseMetadataError('release_metadata_invalid', 'assets', 'assets must be a non-empty array');
+    }
+    const compatibilityValue = requireOwn(record, 'compatibility');
+    if (!isPlainObject(compatibilityValue)) {
+        throw new ReleaseMetadataError('release_metadata_invalid', 'compatibility', 'compatibility must be an object');
+    }
+    const dataSchemaForwardReadableFrom = requireOwn(compatibilityValue, 'dataSchemaForwardReadableFrom');
+    parseProductVersion(dataSchemaForwardReadableFrom, 'compatibility.dataSchemaForwardReadableFrom');
+    const knownKeys = new Set([
+        'schemaVersion', 'productVersion', 'releaseId', 'sourceCommit', 'metadataDigest',
+        'minBootstrapVersion', 'publicationSequence', 'expiresAt', 'assets', 'compatibility',
+    ]);
+    for (const key of Object.keys(record)) {
+        if (!knownKeys.has(key)) {
+            throw new ReleaseMetadataError('release_metadata_invalid', key, `Release metadata contains unknown field "${key}"`);
+        }
+    }
+    const assets = assetsValue.map((asset, index) => {
+        if (!isPlainObject(asset)) {
+            throw new ReleaseMetadataError('release_metadata_invalid', 'assets', `assets[${index}] must be an object`);
+        }
+        const assetKeys = new Set(['platform', 'arch', 'nodeAbi', 'archiveSha256', 'archiveSizeBytes']);
+        for (const key of Object.keys(asset)) {
+            if (!assetKeys.has(key)) {
+                throw new ReleaseMetadataError('release_metadata_invalid', 'assets', `assets[${index}] contains unknown field "${key}"`);
+            }
+        }
+        return {
+            platform: requireOwn(asset, 'platform'),
+            arch: requireOwn(asset, 'arch'),
+            nodeAbi: requireOwn(asset, 'nodeAbi'),
+            archiveSha256: requireOwn(asset, 'archiveSha256'),
+            archiveSizeBytes: requireOwn(asset, 'archiveSizeBytes'),
+        };
+    });
+    // The identity validator inside deriveReleaseId re-checks every asset field
+    // strictly (identifier shape, digest hex, size) — reuse it by round-tripping.
+    try {
+        deriveReleaseId({ productVersion, sourceCommit, minBootstrapVersion, assets });
+    }
+    catch (error) {
+        if (error instanceof ProductIdentityError) {
+            throw new ReleaseMetadataError('release_metadata_invalid', error.field, error.message);
+        }
+        throw error;
+    }
+    return {
+        schemaVersion,
+        productVersion,
+        releaseId,
+        sourceCommit,
+        metadataDigest,
+        minBootstrapVersion,
+        publicationSequence,
+        expiresAt,
+        assets,
+        compatibility: { dataSchemaForwardReadableFrom: dataSchemaForwardReadableFrom },
+    };
+}
+function metadataToJsonValue(metadata) {
+    return JSON.parse(canonicalJson({
+        schemaVersion: metadata.schemaVersion,
+        productVersion: metadata.productVersion,
+        releaseId: metadata.releaseId,
+        sourceCommit: metadata.sourceCommit,
+        minBootstrapVersion: metadata.minBootstrapVersion,
+        publicationSequence: metadata.publicationSequence,
+        expiresAt: metadata.expiresAt,
+        assets: metadata.assets,
+        compatibility: metadata.compatibility,
+    }));
+}
+/**
+ * Verifies the internal identity chain: recomputing the release ID from the
+ * metadata's own content must reproduce `releaseId`, and the canonical
+ * document digest must reproduce `metadataDigest`. A metadata document whose
+ * identity does not close is refuse-before-activation (SPEC §4.3).
+ */
+export function verifyReleaseMetadataIdentity(metadata) {
+    const derivedReleaseId = deriveReleaseId({
+        productVersion: metadata.productVersion,
+        sourceCommit: metadata.sourceCommit,
+        minBootstrapVersion: metadata.minBootstrapVersion,
+        assets: metadata.assets,
+    });
+    if (derivedReleaseId !== metadata.releaseId) {
+        throw new ReleaseMetadataError('release_metadata_identity_mismatch', 'releaseId', `Release metadata releaseId ${metadata.releaseId} does not match the identity derived from its own content (${derivedReleaseId})`);
+    }
+    const documentDigest = computeReleaseContentDigest(metadataToJsonValue(metadata));
+    if (documentDigest !== metadata.metadataDigest) {
+        throw new ReleaseMetadataError('release_metadata_identity_mismatch', 'metadataDigest', `Release metadata digest ${metadata.metadataDigest} does not match the canonical document digest (${documentDigest})`);
+    }
+}
+export function isReleaseMetadataExpired(metadata, now = new Date()) {
+    return Date.parse(metadata.expiresAt) <= now.getTime();
+}
+/** Builds a well-formed metadata document from identity inputs (producer side). */
+export function buildReleaseMetadata(input) {
+    const releaseId = deriveReleaseId(input);
+    const metadata = {
+        schemaVersion: RELEASE_METADATA_SCHEMA_VERSION,
+        productVersion: input.productVersion,
+        releaseId,
+        sourceCommit: input.sourceCommit,
+        metadataDigest: '',
+        minBootstrapVersion: input.minBootstrapVersion,
+        publicationSequence: input.publicationSequence,
+        expiresAt: input.expiresAt,
+        assets: [...input.assets],
+        compatibility: { dataSchemaForwardReadableFrom: input.dataSchemaForwardReadableFrom },
+    };
+    const metadataDigest = computeReleaseContentDigest(metadataToJsonValue(metadata));
+    const complete = { ...metadata, metadataDigest };
+    verifyReleaseMetadataIdentity(complete);
+    return complete;
+}
+export function isReleaseMetadata(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!isSha256Hex(Reflect.get(value, 'releaseId')))
+        return false;
+    try {
+        parseReleaseMetadata(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=release-metadata.js.map

package/dist/update/release-metadata.js.map

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

package/dist/update/release-policy.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Release advancement preflight policy (SPEC §4.3, §9, §13).
+ *
+ * Pure decisions over already-validated metadata: publication sequence
+ * monotonicity, the explicit downgrade policy, channel pointer integrity,
+ * expiry, and bootstrap compatibility. Every refusal carries a stable reason
+ * code and an Owner-visible next action (rc-9) and must happen BEFORE any
+ * installation state is mutated (ERR-074 guard placement).
+ */
+import type { ChannelMetadata } from './channel-metadata.js';
+import type { ReleaseMetadata } from './release-metadata.js';
+export type ReleasePolicyRefusalReason = 'channel_pointer_mismatch' | 'release_metadata_expired' | 'channel_metadata_expired' | 'sequence_regression' | 'downgrade_blocked' | 'bootstrap_too_old';
+export interface ReleasePolicyRefusal {
+    readonly allowed: false;
+    readonly reason: ReleasePolicyRefusalReason;
+    readonly message: string;
+    readonly nextAction: string;
+}
+export interface ReleasePolicyAllowance {
+    readonly allowed: true;
+    readonly direction: 'update' | 'reinstall' | 'explicit_downgrade';
+}
+export type ReleasePolicyDecision = ReleasePolicyRefusal | ReleasePolicyAllowance;
+export interface CurrentInstallationState {
+    readonly productVersion: string;
+    readonly releaseId: string;
+    readonly publicationSequence: number;
+    readonly bootstrapVersion: string;
+    /** Releases previously confirmed on this installation (rollback-safe targets). */
+    readonly previouslyConfirmedReleaseIds: readonly string[];
+}
+/**
+ * The channel pointer must reference exactly this release metadata document
+ * (SPEC §4.3: "Channel Metadata references the exact Release Metadata digest").
+ */
+export declare function verifyChannelPointer(channel: ChannelMetadata, release: ReleaseMetadata): ReleasePolicyRefusal | null;
+/**
+ * Full advancement decision. `allowExplicitDowngrade` is the Owner's explicit
+ * confirmation flag; even with it, the target must be a previously confirmed
+ * release — arbitrary downgrades to unseen releases stay refused because their
+ * data compatibility window is unproven (SPEC §10).
+ */
+export declare function evaluateReleaseAdvancement(input: {
+    channel: ChannelMetadata;
+    candidate: ReleaseMetadata;
+    current: CurrentInstallationState | null;
+    bootstrapVersion: string;
+    now?: Date;
+    allowExplicitDowngrade?: boolean;
+}): ReleasePolicyDecision;
+//# sourceMappingURL=release-policy.d.ts.map

package/dist/update/release-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-policy.d.ts","sourceRoot":"","sources":["../../src/update/release-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAK7D,MAAM,MAAM,0BAA0B,GAClC,0BAA0B,GAC1B,0BAA0B,GAC1B,0BAA0B,GAC1B,qBAAqB,GACrB,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,WAAW,GAAG,oBAAoB,CAAC;CACnE;AAED,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG,sBAAsB,CAAC;AAElF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kFAAkF;IAClF,QAAQ,CAAC,6BAA6B,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,oBAAoB,GAAG,IAAI,CAkBpH;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE;IAChD,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAC;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,GAAG,qBAAqB,CAmExB"}