@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.224

package/dist/foundation/release/cohort-state.js

@@ -0,0 +1,384 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export const RELEASE_COHORT_SCHEMA = PRODUCT_IDENTITY.protocol.releaseCohortSchema;
+const RELEASE_ID_PATTERN = /^[0-9A-Za-z.+_-]+-[a-f0-9]{20}$/;
+/**
+ * Derive protection exclusively from current selectors and ownership authorities.
+ * The historical retention snapshot is deliberately not an input to this plan.
+ */
+export function planProtectedReleases(state, inputs = {}) {
+    const holds = inputs.externalHolds ?? [];
+    for (const hold of holds) {
+        if (hold.authority !== "agent" && hold.authority !== "migration")
+            throw new Error(`unknown release hold authority: ${String(hold.authority)}`);
+        if (!state.releases[hold.releaseId] && !state.cleanup.pending[hold.releaseId]) {
+            throw new Error(`external ${hold.authority} hold names unknown release ${hold.releaseId}`);
+        }
+    }
+    const protectedIds = new Set();
+    for (const id of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
+        if (id !== null)
+            protectedIds.add(id);
+    }
+    for (const id of inputs.liveReleaseIds ?? [])
+        protectedIds.add(id);
+    for (const hold of holds)
+        protectedIds.add(hold.releaseId);
+    if (inputs.transaction?.status === "active" && inputs.transaction.priorActiveReleaseId !== null) {
+        protectedIds.add(inputs.transaction.priorActiveReleaseId);
+    }
+    const protectedReleaseIds = [...protectedIds].sort();
+    const known = Object.keys(state.releases).sort();
+    return {
+        protectedReleaseIds,
+        retainedReleaseIds: known.filter(id => protectedIds.has(id)),
+        collectibleReleaseIds: known.filter(id => !protectedIds.has(id)),
+    };
+}
+/** Serializes validated cohort-state revisions under a lock and commits each update atomically. */
+export class CohortStateStore {
+    path;
+    constructor(dataDir) {
+        this.path = resolve(dataDir, "release-state.json");
+    }
+    async read() {
+        try {
+            const state = normalizeState(JSON.parse(await readFile(this.path, "utf8")));
+            validateState(state);
+            return state;
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return emptyState();
+            throw error;
+        }
+    }
+    async update(operation) {
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const lockPath = `${this.path}.lock`;
+        const lock = await acquireLock(lockPath);
+        try {
+            const current = await this.read();
+            const next = await operation(current);
+            validateTransition(current, next);
+            const committed = { ...next, revision: current.revision + 1 };
+            const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify(committed, null, 2));
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, this.path);
+            return committed;
+        }
+        finally {
+            await lock.close();
+            await rm(lockPath, { force: true });
+        }
+    }
+    async recordCandidate(release) {
+        return await this.update(current => {
+            const existing = current.releases[release.releaseId];
+            const record = existing ?? {
+                releaseId: release.releaseId,
+                releaseRoot: release.releaseRoot,
+                packageVersion: release.packageVersion,
+                contentDigest: release.contentDigest,
+                approval: "candidate",
+                materializedAt: new Date().toISOString(),
+                certifiedAt: null,
+                diagnosticsPath: null,
+            };
+            return {
+                ...current,
+                releases: { ...current.releases, [release.releaseId]: record },
+                references: {
+                    ...current.references,
+                    pending: current.references.active === release.releaseId ? current.references.pending : release.releaseId,
+                },
+                activation: activation("pending", "candidate awaits certification and safe activation"),
+            };
+        });
+    }
+    async approve(releaseId, diagnosticsPath) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            return {
+                ...current,
+                releases: { ...current.releases, [releaseId]: { ...release, approval: "approved", certifiedAt: new Date().toISOString(), diagnosticsPath } },
+                references: { ...current.references, approved: releaseId, pending: current.references.active === releaseId ? null : releaseId },
+            };
+        });
+    }
+    async activate(releaseId) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            if (release.approval !== "approved")
+                throw new Error(`cannot activate unverified release ${releaseId}`);
+            const prior = current.references.active;
+            return {
+                ...current,
+                references: {
+                    ...current.references,
+                    active: releaseId,
+                    pending: null,
+                    approved: releaseId,
+                    rollback: prior && prior !== releaseId ? prior : current.references.rollback,
+                },
+                activation: activation("idle", null),
+            };
+        });
+    }
+    async blockPending(reason, blockerGenerationIds) {
+        return await this.update(current => ({ ...current, activation: { ...activation("blocked", reason), blockerGenerationIds: [...blockerGenerationIds] } }));
+    }
+    async rollback(ownershipReleased) {
+        if (!ownershipReleased)
+            throw new Error("cannot roll back before current cohort ownership is released");
+        return await this.update(current => {
+            const rollbackId = current.references.rollback;
+            if (!rollbackId)
+                throw new Error("no rollback release is recorded");
+            const rollback = requiredRelease(current, rollbackId);
+            if (rollback.approval !== "approved")
+                throw new Error(`cannot roll back to unverified release ${rollbackId}`);
+            return {
+                ...current,
+                references: {
+                    ...current.references,
+                    active: rollbackId,
+                    pending: null,
+                    approved: rollbackId,
+                    rollback: current.references.active,
+                },
+                activation: activation("idle", null),
+            };
+        });
+    }
+    async setRetention(releaseIds) {
+        return await this.update(current => {
+            for (const releaseId of releaseIds)
+                requiredRelease(current, releaseId);
+            return { ...current, references: { ...current.references, retention: unique(releaseIds) } };
+        });
+    }
+    /** Atomically replace legacy retention history and detach every currently collectible record. */
+    async reconcileRetention(resolveInputs, orphans = []) {
+        let plan = null;
+        let detachedReleaseIds = [];
+        const state = await this.update(async (current) => {
+            const inputs = await resolveInputs(current);
+            plan = planProtectedReleases(current, inputs);
+            const nextReleases = { ...current.releases };
+            const pending = { ...current.cleanup.pending };
+            for (const releaseId of plan.collectibleReleaseIds) {
+                const release = nextReleases[releaseId];
+                pending[releaseId] ??= cleanupDisposition(release, "detached", null);
+                delete nextReleases[releaseId];
+            }
+            for (const orphan of orphans) {
+                const releaseId = orphan.release.releaseId;
+                if (nextReleases[releaseId] || pending[releaseId] || plan.protectedReleaseIds.includes(releaseId))
+                    continue;
+                pending[releaseId] = cleanupDisposition(orphan.release, orphan.stage, orphan.trashPath ?? null);
+            }
+            detachedReleaseIds = plan.collectibleReleaseIds;
+            return {
+                ...current,
+                releases: nextReleases,
+                references: { ...current.references, retention: plan.retainedReleaseIds },
+                cleanup: { ...current.cleanup, pending },
+            };
+        });
+        if (plan === null)
+            throw new Error("release retention reconciliation did not produce a plan");
+        return { state, plan, detachedReleaseIds };
+    }
+    async markCleanupTrash(releaseId, trashPath) {
+        return await this.update(current => {
+            const disposition = current.cleanup.pending[releaseId];
+            if (!disposition)
+                throw new Error(`release ${releaseId} has no cleanup disposition`);
+            return replaceCleanup(current, releaseId, { ...disposition, stage: "trash", trashPath, lastError: null });
+        });
+    }
+    async recordCleanupFailure(releaseId, stage, error) {
+        return await this.update(current => {
+            const attemptedAt = new Date().toISOString();
+            const message = boundedError(error);
+            const disposition = current.cleanup.pending[releaseId];
+            const pending = disposition ? {
+                ...current.cleanup.pending,
+                [releaseId]: { ...disposition, attempts: disposition.attempts + 1, lastAttemptAt: attemptedAt, lastError: message },
+            } : current.cleanup.pending;
+            return {
+                ...current,
+                cleanup: {
+                    pending,
+                    diagnostics: [...current.cleanup.diagnostics, { releaseId, stage, attemptedAt, error: message }].slice(-64),
+                },
+            };
+        });
+    }
+    async completeCleanup(releaseId) {
+        return await this.update(current => {
+            const pending = { ...current.cleanup.pending };
+            delete pending[releaseId];
+            return { ...current, cleanup: { ...current.cleanup, pending } };
+        });
+    }
+    async removeUnreferencedRelease(releaseId, externalReferences) {
+        return await this.update(current => {
+            const release = requiredRelease(current, releaseId);
+            const protectedIds = new Set([
+                current.references.active,
+                current.references.pending,
+                current.references.approved,
+                current.references.rollback,
+                ...current.references.retention,
+                ...externalReferences,
+            ].filter((value) => value !== null));
+            if (protectedIds.has(releaseId))
+                throw new Error(`release ${releaseId} is still referenced and cannot be collected`);
+            const releases = { ...current.releases };
+            delete releases[releaseId];
+            return {
+                ...current,
+                releases,
+                cleanup: {
+                    ...current.cleanup,
+                    pending: { ...current.cleanup.pending, [releaseId]: cleanupDisposition(release, "detached", null) },
+                },
+            };
+        });
+    }
+}
+export function emptyState() {
+    return {
+        schema: RELEASE_COHORT_SCHEMA,
+        revision: 0,
+        releases: {},
+        references: { active: null, pending: null, approved: null, rollback: null, retention: [] },
+        cleanup: { pending: {}, diagnostics: [] },
+        activation: activation("idle", null),
+    };
+}
+function cleanupDisposition(release, stage, trashPath) {
+    return { release, stage, trashPath, attempts: 0, lastAttemptAt: null, lastError: null };
+}
+function replaceCleanup(current, releaseId, disposition) {
+    return { ...current, cleanup: { ...current.cleanup, pending: { ...current.cleanup.pending, [releaseId]: disposition } } };
+}
+function activation(state, reason) {
+    return { state, reason, blockerGenerationIds: [], updatedAt: new Date().toISOString() };
+}
+function requiredRelease(state, releaseId) {
+    const release = state.releases[releaseId];
+    if (!release)
+        throw new Error(`unknown release ${releaseId}`);
+    return release;
+}
+function unique(values) { return [...new Set(values)]; }
+async function acquireLock(path) {
+    const deadline = Date.now() + 5_000;
+    while (true) {
+        try {
+            const lock = await open(path, "wx", 0o600);
+            await lock.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+            await lock.sync();
+            return lock;
+        }
+        catch (error) {
+            if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+                throw error;
+            if (await reclaimAbandonedLock(path))
+                continue;
+            if (Date.now() >= deadline)
+                throw error;
+            await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+        }
+    }
+}
+async function reclaimAbandonedLock(path) {
+    let abandoned = false;
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        if (typeof value.pid === "number") {
+            try {
+                process.kill(value.pid, 0);
+            }
+            catch (error) {
+                abandoned = !(error instanceof Error && "code" in error && error.code === "EPERM");
+            }
+        }
+    }
+    catch {
+        const metadata = await stat(path).catch(() => null);
+        abandoned = metadata !== null && Date.now() - metadata.mtimeMs > 10_000;
+    }
+    if (!abandoned)
+        return false;
+    const quarantine = `${path}.abandoned`;
+    const oldQuarantine = await stat(quarantine).catch(() => null);
+    if (oldQuarantine && Date.now() - oldQuarantine.mtimeMs > 10_000)
+        await rm(quarantine, { force: true });
+    try {
+        // Concurrency: the fixed destination lets exactly one waiter claim the stale lock;
+        // another waiter cannot accidentally rename a newly acquired replacement.
+        await rename(path, quarantine);
+        await rm(quarantine, { force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeState(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    const state = value;
+    return {
+        ...state,
+        cleanup: state.cleanup ?? { pending: {}, diagnostics: [] },
+    };
+}
+function validateState(state) {
+    if (!state || state.schema !== RELEASE_COHORT_SCHEMA || !Number.isSafeInteger(state.revision) || state.revision < 0
+        || !state.releases || typeof state.releases !== "object" || !state.references || !Array.isArray(state.references.retention)
+        || !state.cleanup || typeof state.cleanup.pending !== "object" || !Array.isArray(state.cleanup.diagnostics)) {
+        throw new Error("invalid release cohort state");
+    }
+    for (const [releaseId, release] of Object.entries(state.releases))
+        validateReleaseRecord(releaseId, release);
+    for (const reference of [state.references.active, state.references.pending, state.references.approved, state.references.rollback]) {
+        if (reference !== null && !state.releases[reference])
+            throw new Error(`release reference points to an unknown release: ${reference}`);
+    }
+    for (const [releaseId, disposition] of Object.entries(state.cleanup.pending)) {
+        validateReleaseRecord(releaseId, disposition.release);
+        if (!["detached", "trash"].includes(disposition.stage))
+            throw new Error(`invalid cleanup disposition for ${releaseId}`);
+    }
+}
+function validateReleaseRecord(releaseId, release) {
+    if (release.releaseId !== releaseId || !RELEASE_ID_PATTERN.test(releaseId) || typeof release.releaseRoot !== "string"
+        || typeof release.packageVersion !== "string" || !/^[a-f0-9]{64}$/.test(release.contentDigest)
+        || !["candidate", "approved", "rejected"].includes(release.approval)) {
+        throw new Error(`invalid release record for ${releaseId}`);
+    }
+}
+function validateTransition(current, next) {
+    validateState(next);
+    if (next.schema !== current.schema)
+        throw new Error("release cohort schema cannot change during a state update");
+    if (next.revision !== current.revision)
+        throw new Error("release cohort revision is controlled by the state store");
+}
+function boundedError(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/[\r\n]+/g, " ").slice(0, 1_000);
+}

package/dist/foundation/release/dependency-layer.d.ts

@@ -0,0 +1,78 @@
+import { type ReleaseFileIdentity } from "./release.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export declare const DEPENDENCY_LAYER_SCHEMA: string;
+export declare const DEPENDENCY_LAYER_MANIFEST = "dependency-layer-manifest.json";
+export declare const RUNTIME_PAYLOAD_INVENTORY = "dist/runtime-payload-inventory.json";
+export interface RuntimePayloadExclusion {
+    readonly path: string;
+    readonly reason: "type-declaration" | "source-map" | "unreachable-development";
+}
+export interface RuntimePayloadInventory {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.runtimePayloadSchema;
+    readonly includedFiles: number;
+    readonly includedBytes: number;
+    readonly excludedFiles: number;
+    readonly excludedBytes: number;
+    readonly uncertaintyRetainedFiles: number;
+    readonly exclusions: readonly RuntimePayloadExclusion[];
+}
+export interface DependencyLayerIdentity {
+    readonly schema: typeof DEPENDENCY_LAYER_SCHEMA;
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly files: readonly ReleaseFileIdentity[];
+    readonly inventory: RuntimePayloadInventory;
+}
+export interface DependencyLayerReference {
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly binding: "node_modules";
+}
+export interface MaterializedDependencyLayer extends DependencyLayerIdentity {
+    readonly layerRoot: string;
+    readonly reused: boolean;
+}
+export interface DependencyLayerOperationEvent {
+    readonly operation: "source-read" | "layer-write" | "layer-reuse" | "verification-read";
+    readonly path: string;
+    readonly bytes: number;
+}
+export interface SelectedRuntimePayload {
+    readonly paths: readonly string[];
+    readonly inventory: RuntimePayloadInventory;
+}
+export interface PublishedRuntimeFileClassification {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly packagePath: string;
+    readonly disposition: "include" | "exclude";
+    readonly reason?: RuntimePayloadExclusion["reason"];
+}
+export interface GeneratedRuntimePayload extends SelectedRuntimePayload {
+    readonly classifications: readonly PublishedRuntimeFileClassification[];
+}
+export interface PublishedRuntimePayload extends GeneratedRuntimePayload {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.runtimePayloadSchema;
+    readonly entryPoints: readonly string[];
+    readonly declaredAssets: readonly string[];
+}
+/** Consume topology-independent publication classifications, retaining unknown installed content. */
+export declare function selectPublishedDependencyRuntimePayload(packageRoot: string, paths: readonly string[]): Promise<SelectedRuntimePayload>;
+/** Generate publication evidence from literal module reachability and declared runtime assets. */
+export declare function generateDependencyRuntimePayload(packageRoot: string, allPaths: readonly string[], productPaths: readonly string[]): Promise<GeneratedRuntimePayload>;
+/** Conservatively omit only files Node never executes; uncertain assets remain selected. */
+export declare function selectDependencyRuntimePayload(packageRoot: string, paths: readonly string[]): Promise<SelectedRuntimePayload>;
+export interface MaterializeDependencyLayerOptions {
+    readonly inventory: RuntimePayloadInventory;
+    readonly cachedFiles?: ReadonlyMap<string, Buffer>;
+    readonly onOperation?: (event: DependencyLayerOperationEvent) => void;
+    readonly writeCandidateFile?: (path: string, bytes: Uint8Array, mode: number) => Promise<void>;
+}
+/** Materialize or reuse an exact immutable dependency layer after one source-content pass. */
+export declare function materializeDependencyLayer(packageRoot: string, dataDir: string, paths: readonly string[], options: MaterializeDependencyLayerOptions): Promise<MaterializedDependencyLayer | null>;
+/** Read trusted layer certification and canonical metadata without rereading every payload byte. */
+export declare function readCertifiedDependencyLayer(dataDir: string, layerId: string, expected?: Pick<DependencyLayerIdentity, "layerId" | "contentDigest">): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+/** Fully verify a layer when certification is absent or explicit tamper evidence is required. */
+export declare function verifyDependencyLayer(dataDir: string, reference: DependencyLayerReference, onOperation?: (event: DependencyLayerOperationEvent) => void): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+export declare function dependencyReference(layer: MaterializedDependencyLayer): DependencyLayerReference;
+export declare function dependencyLayerCertificationPath(dataDir: string, layerId: string): string;