create-principles-disciple 1.121.7 → 1.121.9

package/dist/update/release-policy.js

@@ -0,0 +1,103 @@
+/**
+ * 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 { isChannelMetadataExpired } from './channel-metadata.js';
+import { isReleaseMetadataExpired } from './release-metadata.js';
+import { compareProductVersions, parseProductVersion } from './product-identity.js';
+/**
+ * The channel pointer must reference exactly this release metadata document
+ * (SPEC §4.3: "Channel Metadata references the exact Release Metadata digest").
+ */
+export function verifyChannelPointer(channel, release) {
+    if (channel.releaseMetadataDigest !== release.metadataDigest || channel.releaseId !== release.releaseId) {
+        return {
+            allowed: false,
+            reason: 'channel_pointer_mismatch',
+            message: `The signed ${channel.channel} channel points at release metadata ${channel.releaseMetadataDigest.slice(0, 12)} (${channel.productVersion}), not the presented release ${release.releaseId.slice(0, 12)} (${release.productVersion}).`,
+            nextAction: 'Do not install this release. Re-fetch channel metadata and the release it references, then retry.',
+        };
+    }
+    if (channel.publicationSequence !== release.publicationSequence) {
+        return {
+            allowed: false,
+            reason: 'channel_pointer_mismatch',
+            message: `The channel publication sequence (${channel.publicationSequence}) disagrees with the release metadata sequence (${release.publicationSequence}).`,
+            nextAction: 'Do not install this release. The channel pointer and release metadata must come from the same publication.',
+        };
+    }
+    return 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 function evaluateReleaseAdvancement(input) {
+    const { channel, candidate, current, bootstrapVersion } = input;
+    const now = input.now ?? new Date();
+    const pointerFailure = verifyChannelPointer(channel, candidate);
+    if (pointerFailure)
+        return pointerFailure;
+    if (isReleaseMetadataExpired(candidate, now)) {
+        return {
+            allowed: false,
+            reason: 'release_metadata_expired',
+            message: `Release ${candidate.productVersion} metadata expired at ${candidate.expiresAt}.`,
+            nextAction: 'Do not install this release. Wait for refreshed signed metadata from the official repository.',
+        };
+    }
+    if (isChannelMetadataExpired(channel, now)) {
+        return {
+            allowed: false,
+            reason: 'channel_metadata_expired',
+            message: `The ${channel.channel} channel metadata expired at ${channel.expiresAt}.`,
+            nextAction: 'Do not install this release. Refresh the signed channel metadata and retry.',
+        };
+    }
+    const bootstrap = parseProductVersion(bootstrapVersion, 'bootstrapVersion');
+    const requiredBootstrap = parseProductVersion(candidate.minBootstrapVersion, 'candidate.minBootstrapVersion');
+    if (compareProductVersions(bootstrap, requiredBootstrap) < 0) {
+        return {
+            allowed: false,
+            reason: 'bootstrap_too_old',
+            message: `Release ${candidate.productVersion} requires bootstrap >= ${candidate.minBootstrapVersion}; installed bootstrap is ${bootstrapVersion}.`,
+            nextAction: 'Do not install this release. Run the official installer once to update the bootstrap, then retry the update.',
+        };
+    }
+    if (current === null) {
+        return { allowed: true, direction: 'update' };
+    }
+    if (candidate.releaseId === current.releaseId) {
+        return { allowed: true, direction: 'reinstall' };
+    }
+    if (candidate.publicationSequence < current.publicationSequence) {
+        if (input.allowExplicitDowngrade === true && current.previouslyConfirmedReleaseIds.includes(candidate.releaseId)) {
+            return { allowed: true, direction: 'explicit_downgrade' };
+        }
+        return {
+            allowed: false,
+            reason: current.publicationSequence > candidate.publicationSequence ? 'downgrade_blocked' : 'sequence_regression',
+            message: `Release ${candidate.productVersion} (sequence ${candidate.publicationSequence}) is older than the active ${current.productVersion} (sequence ${current.publicationSequence}).`,
+            nextAction: input.allowExplicitDowngrade === true
+                ? 'Explicit downgrade is only permitted to releases previously confirmed on this installation. Select a confirmed release or update forward.'
+                : 'Downgrades are refused by default. If the Owner explicitly intends this, re-run with downgrade confirmation to a previously confirmed release.',
+        };
+    }
+    if (candidate.publicationSequence === current.publicationSequence && candidate.releaseId !== current.releaseId) {
+        return {
+            allowed: false,
+            reason: 'sequence_regression',
+            message: `Two different releases claim publication sequence ${candidate.publicationSequence}; the active release is ${current.releaseId.slice(0, 12)}.`,
+            nextAction: 'Do not install this release. Report the conflicting metadata to the repository maintainer.',
+        };
+    }
+    return { allowed: true, direction: 'update' };
+}
+//# sourceMappingURL=release-policy.js.map

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * Host coordination and automatic-rollback policy (SPEC §9).
+ *
+ * One global active release per installation. Only hosts that were RUNNING
+ * before activation must restart and complete the handshake — hosts that
+ * were already stopped are not failures. If any previously-running host
+ * cannot start the same release, every affected host returns to the prior
+ * release: a split-brain component mix must never become active.
+ *
+ * Attribution rules:
+ * - Deterministic failures attributable to the new release (entrypoint load,
+ *   handshake mismatch, startup crash) qualify for automatic rollback.
+ * - Network unavailability, empty business data, and unrelated
+ *   external-service failures do NOT — they would roll back a healthy
+ *   release for environmental noise.
+ *
+ * At most ONE automatic rollback per transaction. A second deterministic
+ * failure opens the circuit breaker: the last confirmed release stays
+ * active and an explicit Owner action is required.
+ */
+export type HostHandshakeOutcome = {
+    readonly kind: 'passed';
+} | {
+    readonly kind: 'not_restarted';
+} | {
+    readonly kind: 'failed';
+    readonly failureClass: HostFailureClass;
+    readonly detail: string;
+};
+export type HostFailureClass = 'deterministic_start_failure' | 'handshake_mismatch' | 'network_unavailable' | 'external_service_unavailable' | 'unknown';
+export interface HostObservation {
+    readonly hostId: string;
+    readonly wasRunningBeforeActivation: boolean;
+    readonly outcome: HostHandshakeOutcome;
+}
+export type RollbackDecision = {
+    readonly action: 'confirm';
+    readonly reason: string;
+} | {
+    readonly action: 'retry_handshake';
+    readonly reason: string;
+    readonly nextAction: string;
+} | {
+    readonly action: 'auto_rollback';
+    readonly reason: string;
+    readonly hosts: readonly string[];
+} | {
+    readonly action: 'circuit_breaker_open';
+    readonly reason: string;
+    readonly nextAction: string;
+};
+export declare function decideHostCoordination(input: {
+    observations: readonly HostObservation[];
+    autoRollbackAlreadyUsed: boolean;
+}): RollbackDecision;
+//# sourceMappingURL=rollback-policy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-policy.d.ts","sourceRoot":"","sources":["../../src/update/rollback-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAElG,MAAM,MAAM,gBAAgB,GACxB,6BAA6B,GAC7B,oBAAoB,GACpB,qBAAqB,GACrB,8BAA8B,GAC9B,SAAS,CAAC;AAEd,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,0BAA0B,EAAE,OAAO,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,oBAAoB,CAAC;CACxC;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC5F;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAChG;IAAE,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAItG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,YAAY,EAAE,SAAS,eAAe,EAAE,CAAC;IACzC,uBAAuB,EAAE,OAAO,CAAC;CAClC,GAAG,gBAAgB,CA2CnB"}

package/dist/update/rollback-policy.js

@@ -0,0 +1,61 @@
+/**
+ * Host coordination and automatic-rollback policy (SPEC §9).
+ *
+ * One global active release per installation. Only hosts that were RUNNING
+ * before activation must restart and complete the handshake — hosts that
+ * were already stopped are not failures. If any previously-running host
+ * cannot start the same release, every affected host returns to the prior
+ * release: a split-brain component mix must never become active.
+ *
+ * Attribution rules:
+ * - Deterministic failures attributable to the new release (entrypoint load,
+ *   handshake mismatch, startup crash) qualify for automatic rollback.
+ * - Network unavailability, empty business data, and unrelated
+ *   external-service failures do NOT — they would roll back a healthy
+ *   release for environmental noise.
+ *
+ * At most ONE automatic rollback per transaction. A second deterministic
+ * failure opens the circuit breaker: the last confirmed release stays
+ * active and an explicit Owner action is required.
+ */
+const DETERMINISTIC_CLASSES = new Set(['deterministic_start_failure', 'handshake_mismatch']);
+export function decideHostCoordination(input) {
+    const { observations, autoRollbackAlreadyUsed } = input;
+    if (observations.length === 0) {
+        return { action: 'confirm', reason: 'no hosts required coordination' };
+    }
+    const mustRestart = observations.filter((observation) => observation.wasRunningBeforeActivation);
+    if (mustRestart.length === 0) {
+        return { action: 'confirm', reason: 'no hosts were running before activation; nothing to restart' };
+    }
+    const deterministicFailures = mustRestart.filter((observation) => observation.outcome.kind === 'failed'
+        && DETERMINISTIC_CLASSES.has(observation.outcome.failureClass));
+    const environmentalFailures = mustRestart.filter((observation) => observation.outcome.kind === 'failed'
+        && !DETERMINISTIC_CLASSES.has(observation.outcome.failureClass));
+    const pending = mustRestart.filter((observation) => observation.outcome.kind === 'not_restarted');
+    if (deterministicFailures.length > 0) {
+        const failingHosts = deterministicFailures.map((observation) => observation.hostId);
+        if (autoRollbackAlreadyUsed) {
+            return {
+                action: 'circuit_breaker_open',
+                reason: `A second deterministic failure followed the transaction's single automatic rollback (hosts: ${failingHosts.join(', ')}).`,
+                nextAction: 'The last confirmed release remains active. Inspect the failing host logs under ~/.pd/logs, fix the cause, and run an explicit update or rollback operation.',
+            };
+        }
+        return {
+            action: 'auto_rollback',
+            reason: `Deterministic startup failures attributable to the new release (hosts: ${failingHosts.join(', ')}); all affected hosts return to the previous confirmed release to avoid split brain.`,
+            hosts: failingHosts,
+        };
+    }
+    if (environmentalFailures.length > 0 || pending.length > 0) {
+        const affected = [...environmentalFailures, ...pending].map((observation) => observation.hostId);
+        return {
+            action: 'retry_handshake',
+            reason: `Non-deterministic conditions (network / external service / still restarting) on hosts: ${affected.join(', ')}. These do not qualify for automatic rollback.`,
+            nextAction: 'Retry the release handshake for the affected hosts. The release stays activated-but-unconfirmed until every previously running host passes or a deterministic failure appears.',
+        };
+    }
+    return { action: 'confirm', reason: 'every previously running host completed the release handshake' };
+}
+//# sourceMappingURL=rollback-policy.js.map

package/dist/update/rollback-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback-policy.js","sourceRoot":"","sources":["../../src/update/rollback-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AA0BH,MAAM,qBAAqB,GAAkC,IAAI,GAAG,CAAC,CAAC,6BAA6B,EAAE,oBAAoB,CAAC,CAAC,CAAC;AAE5H,MAAM,UAAU,sBAAsB,CAAC,KAGtC;IACC,MAAM,EAAE,YAAY,EAAE,uBAAuB,EAAE,GAAG,KAAK,CAAC;IACxD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;IACzE,CAAC;IAED,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,0BAA0B,CAAC,CAAC;IACjG,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,6DAA6D,EAAE,CAAC;IACtG,CAAC;IAED,MAAM,qBAAqB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ;WAClG,qBAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IAClE,MAAM,qBAAqB,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ;WAClG,CAAC,qBAAqB,CAAC,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC;IACnE,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,KAAK,eAAe,CAAC,CAAC;IAElG,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,YAAY,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACpF,IAAI,uBAAuB,EAAE,CAAC;YAC5B,OAAO;gBACL,MAAM,EAAE,sBAAsB;gBAC9B,MAAM,EAAE,+FAA+F,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;gBAClI,UAAU,EAAE,6JAA6J;aAC1K,CAAC;QACJ,CAAC;QACD,OAAO;YACL,MAAM,EAAE,eAAe;YACvB,MAAM,EAAE,0EAA0E,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,sFAAsF;YAC/L,KAAK,EAAE,YAAY;SACpB,CAAC;IACJ,CAAC;IAED,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,CAAC,GAAG,qBAAqB,EAAE,GAAG,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QACjG,OAAO;YACL,MAAM,EAAE,iBAAiB;YACzB,MAAM,EAAE,0FAA0F,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,gDAAgD;YACrK,UAAU,EAAE,gLAAgL;SAC7L,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,+DAA+D,EAAE,CAAC;AACxG,CAAC"}

package/dist/update/transaction-journal.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Transaction journal and recovery (SPEC §8, §14.3).
+ *
+ * An update follows a persisted state machine:
+ *
+ *   planned -> downloaded -> verified -> staged -> probed
+ *           -> activated -> host_verified -> confirmed
+ *           -> rolled_back | refused | failed
+ *
+ * EVERY transition is appended (and fsynced) to the transaction journal
+ * BEFORE the side effect it describes. On restart, recovery reconciles any
+ * unfinished transaction: the outcome is always old-confirmed, new-confirmed,
+ * or an explicit safe refusal — never a hybrid.
+ */
+export declare const TRANSACTION_STATES: readonly ['planned', 'downloaded', 'verified', 'staged', 'probed', 'activated', 'host_verified', 'confirmed', 'rolled_back', 'refused', 'failed'];
+export type TransactionState = typeof TRANSACTION_STATES[number];
+export type TransactionKind = 'update' | 'reinstall' | 'explicit_downgrade' | 'rollback' | 'legacy_migration' | 'recovery';
+export interface JournalTransition {
+    readonly at: string;
+    readonly from: TransactionState | null;
+    readonly to: TransactionState;
+    readonly transactionId: string;
+    readonly releaseId: string;
+    readonly productVersion: string;
+    readonly releaseMetadataDigest: string;
+    readonly generation: number;
+    readonly detail?: string;
+}
+export interface ActiveRecord {
+    readonly schemaVersion: 1;
+    readonly generation: number;
+    readonly releaseId: string;
+    readonly releaseMetadataDigest: string;
+    readonly previousReleaseId: string | null;
+    readonly transactionId: string;
+    readonly productVersion: string;
+}
+export declare class TransactionJournalError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface RecoveryAwareJournalRead {
+    readonly transitions: readonly JournalTransition[];
+    /**
+     * True when the final physical journal record was a torn (unparseable,
+     * unterminated) write — its transition never durably committed and is
+     * EXCLUDED from `transitions`. Physical repair (truncation) belongs to an
+     * explicit recovery operation, never to this reader.
+     */
+    readonly tornTailDetected: boolean;
+}
+/** Reads and strictly validates the whole journal (fail loud on any tear). */
+export declare function readTransactionJournal(journalPath: string): readonly JournalTransition[];
+/**
+ * Recovery-aware journal reader (crash contract, SPEC §8).
+ *
+ * The writer appends `JSON + '\n'` and fsyncs. A crash mid-append can leave a
+ * TORN final record: unparseable JSON without a trailing newline. Such a
+ * record never durably committed, so recovery drops it. Everything else is
+ * strict: a malformed line anywhere else (including a complete-but-invalid
+ * final line that DOES end with a newline) fails loud, because a complete
+ * write with bad content is corruption, not a torn write.
+ */
+export declare function readTransactionJournalForRecovery(journalPath: string): RecoveryAwareJournalRead;
+/**
+ * Appends one transition durably (append + fsync) BEFORE the caller performs
+ * the side effect the transition describes. Journal-first ordering is what
+ * makes crash recovery sound.
+ */
+export declare function appendJournalTransition(journalPath: string, transition: JournalTransition): void;
+export interface ActiveRecordWrite {
+    readonly generation: number;
+    readonly releaseId: string;
+    readonly releaseMetadataDigest: string;
+    readonly previousReleaseId: string | null;
+    readonly transactionId: string;
+    readonly productVersion: string;
+}
+/** Serializes + atomically replaces active.json (see atomic-file adapter). */
+export declare function writeActiveRecord(recordPath: string, write: ActiveRecordWrite): void;
+/** Strict active.json reader; returns null when absent. */
+export declare function readActiveRecord(recordPath: string): ActiveRecord | null;
+export type RecoveryOutcome = {
+    readonly kind: 'old_confirmed';
+    readonly releaseId: string | null;
+    readonly generation: number | null;
+    readonly reason: string;
+} | {
+    readonly kind: 'new_confirmed';
+    readonly releaseId: string;
+    readonly generation: number;
+    readonly reason: string;
+} | {
+    readonly kind: 'explicit_refusal';
+    readonly reason: string;
+    readonly nextAction: string;
+};
+/**
+ * Reconciles ONE transaction against the active record after a crash. The
+ * invariant: the result is old-confirmed, new-confirmed, or an explicit
+ * refusal — never a hybrid release (SPEC §18-4).
+ *
+ * Rules:
+ * - No journal activity for this transaction → nothing to reconcile.
+ * - Journal reached `confirmed` → new release stands.
+ * - Journal never reached `activated` → old release stands (nothing was
+ *   swapped); staging residue is cleaned up by the caller.
+ * - Journal reached `activated` (or later, unconfirmed) but active.json does
+ *   not carry this transaction's generation → the crash interrupted the
+ *   active-record write. The journal-confirmed PREVIOUS generation wins:
+ *   recovery re-points to it; a hybrid (new code, old pointer) is never
+ *   activated. If there is no previous pointer to fall back to, refuse
+ *   explicitly and demand the official installer.
+ */
+export declare function recoverUnfinishedTransaction(input: {
+    transitions: readonly JournalTransition[];
+    activeRecord: ActiveRecord | null;
+    previousRecord: ActiveRecord | null;
+    transactionId: string;
+}): RecoveryOutcome;
+//# sourceMappingURL=transaction-journal.d.ts.map

package/dist/update/transaction-journal.d.ts.map

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