@vmz/vmz 0.0.3 → 0.0.4

package/dist/production-test-pack.js

@@ -0,0 +1,452 @@
+/**
+ * A4: Production scenario pack + deterministic CI profile.
+ * Assembles real user-path scenarios for `pnpm verify -- production-test`.
+ * Does not invent Vitest/Jest/Playwright semantics.
+ */
+// @ts-nocheck
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { canonicalJson, sha256Hex } from './release-pack.js';
+export const PRODUCTION_SCENARIO_PACK_SCHEMA = 'vmz.production.scenario_pack.v0';
+export const PRODUCTION_CI_PROFILE_SCHEMA = 'vmz.production.ci_profile.v0';
+export const PRODUCTION_TEST_REPORT_SCHEMA = 'vmz.production.test_report.v0';
+/** Official Browser Production Profile v1 scenario pack (thin slice). */
+export function browserProductionScenarioPack() {
+    return {
+        schema: PRODUCTION_SCENARIO_PACK_SCHEMA,
+        id: 'browser-production.v1',
+        title: 'Browser Production Profile — production user paths',
+        scenarios: [
+            {
+                scenarioId: 'production.catalog.compile.list',
+                category: 'compile',
+                fixture: 'packages/examples/production-catalog',
+                modes: ['compile'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'production.catalog.logic.list',
+                category: 'logic',
+                fixture: 'packages/examples/production-catalog',
+                modes: ['logic'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'production.catalog.ssr.list',
+                category: 'ssr',
+                fixture: 'packages/examples/production-catalog',
+                modes: ['ssr'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'production.catalog.resume.chip',
+                category: 'resume',
+                fixture: 'packages/examples/production-catalog',
+                modes: ['resume'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'production.catalog.browser.select',
+                category: 'browser',
+                fixture: 'packages/examples/production-catalog',
+                modes: ['browser'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'resume.resume.island',
+                category: 'island-resume',
+                fixture: 'packages/examples/island',
+                modes: ['resume'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'resume.event.entry',
+                category: 'island-resume',
+                fixture: 'packages/examples/island',
+                modes: ['resume'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 't3.deployment.island.resume',
+                category: 'deployment',
+                fixture: 'packages/examples/island',
+                modes: ['deployment'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 't3.deployment.usercard.isolation',
+                category: 'server-capability',
+                fixture: 'packages/examples/fullstack',
+                modes: ['deployment'],
+                runner: 'vmz-test',
+                required: true,
+            },
+            {
+                scenarioId: 'production.router.access',
+                category: 'auth-access',
+                fixture: 'packages/examples/production-router',
+                modes: ['ssr'],
+                runner: 'serve-host',
+                required: true,
+                detail: 'Page.access allow/deny/not-found/redirect',
+            },
+            {
+                scenarioId: 'production.router.action',
+                category: 'loader-action',
+                fixture: 'packages/examples/production-router',
+                modes: ['ssr'],
+                runner: 'serve-host',
+                required: true,
+                detail: 'Page.action POST + redirect',
+            },
+            {
+                scenarioId: 'production.router.loader-cancel',
+                category: 'loader-action',
+                fixture: 'packages/examples/production-router',
+                modes: ['logic'],
+                runner: 'in-process',
+                required: true,
+                detail: 'AbortSignal cancel + stale generation supersede',
+            },
+            {
+                scenarioId: 'production.release.rollback',
+                category: 'artifact-rollback',
+                fixture: 'packages/examples/production-router',
+                modes: ['deployment'],
+                runner: 'release-pack',
+                required: true,
+                detail: 'pack digest + CURRENT/PREVIOUS rollback',
+            },
+            // Explicit quarantine — must never be reported as passed.
+            {
+                scenarioId: 'production.ui.field.submit',
+                category: 'field',
+                fixture: null,
+                modes: ['browser'],
+                runner: 'quarantine',
+                required: false,
+                quarantine: true,
+                reason: 'A4: Field input/submit/dup-submit/cancel not assembled (@vmz/ui UI1)',
+            },
+            {
+                scenarioId: 'production.ui.dialog.focus',
+                category: 'dialog',
+                fixture: null,
+                modes: ['browser'],
+                runner: 'quarantine',
+                required: false,
+                quarantine: true,
+                reason: 'A4: Dialog focus enter/loop/restore + outside dismiss not assembled',
+            },
+            {
+                scenarioId: 'production.locale.switch-rtl',
+                category: 'locale',
+                fixture: null,
+                modes: ['browser'],
+                runner: 'quarantine',
+                required: false,
+                quarantine: true,
+                reason: 'A4: locale switch / fallback forbidden / RTL not in this pack',
+            },
+            {
+                scenarioId: 'production.theme.missing-token',
+                category: 'theme',
+                fixture: null,
+                modes: ['browser'],
+                runner: 'quarantine',
+                required: false,
+                quarantine: true,
+                reason: 'A4: theme switch + missing semantic token not in this pack',
+            },
+            {
+                scenarioId: 'production.mount.child-failure',
+                category: 'mount',
+                fixture: null,
+                modes: ['browser'],
+                runner: 'quarantine',
+                required: false,
+                quarantine: true,
+                reason: 'A4: ApplicationMount child failure isolation not in this pack',
+            },
+        ],
+    };
+}
+/** Deterministic CI profile for production-test (no flaky disguise). */
+export function browserProductionCiProfile(overrides = {}) {
+    return normalizeCiProfile({
+        schema: PRODUCTION_CI_PROFILE_SCHEMA,
+        id: 'browser-production.ci.v1',
+        seed: 0x176bff,
+        workers: 1,
+        sort: 'scenarioId',
+        retry: { enabled: false, maxAttempts: 1, promoteFlakyPass: false },
+        quarantine: {
+            policy: 'explicit',
+            neverCountAsPassed: true,
+        },
+        artifacts: {
+            onFailure: true,
+            retain: ['report', 'trace', 'artifactManifest'],
+            dir: 'dist/production-reports/production-test',
+        },
+        toolchain: {
+            node: true,
+            rust: true,
+            chrome: true,
+        },
+        forbiddenRunners: ['vitest', 'jest', 'playwright', '@playwright/test'],
+        ...overrides,
+    });
+}
+/**
+ * @param {unknown} raw
+ * @returns {{ ok: true, pack: Record<string, any> } | { ok: false, diagnostics: Array<{ code: string, message: string }> }}
+ */
+export function normalizeScenarioPack(raw) {
+    /** @type {Array<{ code: string, message: string }>} */
+    const diagnostics = [];
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, diagnostics: [{ code: 'pack.invalid', message: 'pack must be a plain object' }] };
+    }
+    const p = /** @type {Record<string, any>} */ (raw);
+    if (p.schema !== PRODUCTION_SCENARIO_PACK_SCHEMA) {
+        diagnostics.push({
+            code: 'pack.schema',
+            message: `schema want ${PRODUCTION_SCENARIO_PACK_SCHEMA}, got ${JSON.stringify(p.schema)}`,
+        });
+    }
+    if (typeof p.id !== 'string' || !p.id.trim()) {
+        diagnostics.push({ code: 'pack.id', message: 'pack.id required' });
+    }
+    if (!Array.isArray(p.scenarios) || p.scenarios.length < 1) {
+        diagnostics.push({ code: 'pack.scenarios', message: 'scenarios must be a non-empty array' });
+    }
+    const scenarios = [];
+    const seen = new Set();
+    for (const [i, s] of (p.scenarios || []).entries()) {
+        if (!s || typeof s !== 'object') {
+            diagnostics.push({ code: 'pack.scenario', message: `scenarios[${i}] must be an object` });
+            continue;
+        }
+        const scenarioId = String(s.scenarioId || '').trim();
+        if (!scenarioId) {
+            diagnostics.push({ code: 'pack.scenarioId', message: `scenarios[${i}].scenarioId required` });
+            continue;
+        }
+        if (seen.has(scenarioId)) {
+            diagnostics.push({ code: 'pack.scenarioId.dup', message: `duplicate scenarioId ${scenarioId}` });
+            continue;
+        }
+        seen.add(scenarioId);
+        const quarantine = s.quarantine === true;
+        const required = s.required !== false && !quarantine;
+        if (quarantine && s.status === 'passed') {
+            diagnostics.push({
+                code: 'pack.quarantine.passed',
+                message: `${scenarioId}: quarantine must never be authored as passed`,
+            });
+        }
+        scenarios.push({
+            scenarioId,
+            category: String(s.category || 'other'),
+            fixture: s.fixture == null ? null : String(s.fixture),
+            modes: Array.isArray(s.modes) ? s.modes.map(String) : [],
+            runner: String(s.runner || 'vmz-test'),
+            required,
+            quarantine,
+            reason: s.reason ? String(s.reason) : null,
+            detail: s.detail ? String(s.detail) : null,
+        });
+    }
+    // Deterministic order for CI.
+    scenarios.sort((a, b) => (a.scenarioId < b.scenarioId ? -1 : a.scenarioId > b.scenarioId ? 1 : 0));
+    if (diagnostics.length)
+        return { ok: false, diagnostics };
+    return {
+        ok: true,
+        pack: {
+            schema: PRODUCTION_SCENARIO_PACK_SCHEMA,
+            id: String(p.id).trim(),
+            title: typeof p.title === 'string' ? p.title : p.id,
+            scenarios,
+        },
+    };
+}
+/**
+ * @param {unknown} raw
+ */
+export function normalizeCiProfile(raw) {
+    const d = raw && typeof raw === 'object' && !Array.isArray(raw) ? /** @type {Record<string, any>} */ (raw) : {};
+    const retry = d.retry && typeof d.retry === 'object' ? d.retry : {};
+    const quarantine = d.quarantine && typeof d.quarantine === 'object' ? d.quarantine : {};
+    const artifacts = d.artifacts && typeof d.artifacts === 'object' ? d.artifacts : {};
+    const seed = typeof d.seed === 'number' && Number.isFinite(d.seed) ? d.seed : 0x176bff;
+    return {
+        schema: PRODUCTION_CI_PROFILE_SCHEMA,
+        id: typeof d.id === 'string' && d.id ? d.id : 'browser-production.ci.v1',
+        seed,
+        workers: d.workers === 1 ? 1 : 1, // production CI profile forces serial for determinism
+        sort: d.sort === 'scenarioId' ? 'scenarioId' : 'scenarioId',
+        retry: {
+            enabled: retry.enabled === true,
+            maxAttempts: Math.max(1, Number(retry.maxAttempts) || 1),
+            promoteFlakyPass: false, // hard rule: never disguise flaky as passed
+        },
+        quarantine: {
+            policy: quarantine.policy === 'implicit' ? 'implicit' : 'explicit',
+            neverCountAsPassed: quarantine.neverCountAsPassed !== false,
+        },
+        artifacts: {
+            onFailure: artifacts.onFailure !== false,
+            retain: Array.isArray(artifacts.retain) ? artifacts.retain.map(String) : ['report', 'trace', 'artifactManifest'],
+            dir: typeof artifacts.dir === 'string' ? artifacts.dir : 'dist/production-reports/production-test',
+        },
+        toolchain: {
+            node: true,
+            rust: d.toolchain?.rust !== false,
+            chrome: d.toolchain?.chrome !== false,
+        },
+        forbiddenRunners: Array.isArray(d.forbiddenRunners)
+            ? d.forbiddenRunners.map(String)
+            : ['vitest', 'jest', 'playwright', '@playwright/test'],
+    };
+}
+export function scenarioPackDigest(pack) {
+    return sha256Hex(canonicalJson(pack));
+}
+export function ciProfileDigest(profile) {
+    return sha256Hex(canonicalJson(profile));
+}
+/**
+ * Build a production test report from scenario results.
+ * Quarantine entries must be status=`quarantined` (never `passed`).
+ * @param {{ pack: Record<string, any>, profile: Record<string, any>, results: Array<Record<string, any>>, artifactsDir?: string }} input
+ */
+export function buildProductionTestReport(input) {
+    const pack = input.pack;
+    const profile = input.profile;
+    const byId = new Map((input.results || []).map((r) => [r.scenarioId, r]));
+    const tests = [];
+    /** @type {string[]} */
+    const errors = [];
+    for (const s of pack.scenarios) {
+        const r = byId.get(s.scenarioId);
+        if (s.quarantine) {
+            const status = r?.status === 'passed' ? 'illegal-passed' : r?.status || 'quarantined';
+            if (status === 'illegal-passed' || status === 'passed') {
+                errors.push(`${s.scenarioId}: quarantine must not count as passed`);
+            }
+            tests.push({
+                scenarioId: s.scenarioId,
+                category: s.category,
+                status: 'quarantined',
+                required: false,
+                quarantine: true,
+                reason: s.reason || r?.reason || null,
+                detail: r?.detail || null,
+                artifacts: r?.artifacts || null,
+                attempts: r?.attempts || 1,
+                flaky: false,
+            });
+            continue;
+        }
+        if (!r) {
+            if (s.required)
+                errors.push(`${s.scenarioId}: missing result`);
+            tests.push({
+                scenarioId: s.scenarioId,
+                category: s.category,
+                status: 'missing',
+                required: s.required,
+                quarantine: false,
+                reason: null,
+                detail: null,
+                artifacts: null,
+                attempts: 0,
+                flaky: false,
+            });
+            continue;
+        }
+        const attempts = Math.max(1, Number(r.attempts) || 1);
+        const flaky = r.flaky === true || (attempts > 1 && r.status === 'passed');
+        // Hard rule: retry success must not be reported as stable passed.
+        let status = String(r.status || 'error');
+        if (flaky && status === 'passed') {
+            status = 'flaky';
+            errors.push(`${s.scenarioId}: flaky pass must not be reported as passed`);
+        }
+        if (s.required && status !== 'passed') {
+            errors.push(`${s.scenarioId}: required status=${status}`);
+        }
+        tests.push({
+            scenarioId: s.scenarioId,
+            category: s.category,
+            status,
+            required: s.required,
+            quarantine: false,
+            reason: r.reason || null,
+            detail: r.detail || null,
+            artifacts: r.artifacts || null,
+            attempts,
+            flaky,
+        });
+    }
+    // Deterministic listing order.
+    tests.sort((a, b) => (a.scenarioId < b.scenarioId ? -1 : a.scenarioId > b.scenarioId ? 1 : 0));
+    const failed = tests.some((t) => t.required && !['passed', 'quarantined'].includes(t.status));
+    const report = {
+        schema: PRODUCTION_TEST_REPORT_SCHEMA,
+        status: errors.length || failed ? 'failed' : 'passed',
+        packId: pack.id,
+        packDigest: scenarioPackDigest(pack),
+        ciProfileDigest: ciProfileDigest(profile),
+        seed: profile.seed,
+        workers: profile.workers,
+        retry: profile.retry,
+        quarantine: profile.quarantine,
+        artifactsDir: input.artifactsDir || profile.artifacts.dir,
+        generatedAt: null, // filled by emit for wall-clock; digests exclude this field
+        tests,
+        errors,
+    };
+    return report;
+}
+/** Stable digest of report (excludes generatedAt). */
+export function productionTestReportDigest(report) {
+    const { generatedAt: _g, ...rest } = report;
+    return sha256Hex(canonicalJson(rest));
+}
+/**
+ * Write report + pack/profile snapshots under artifactsDir.
+ * @returns {{ reportPath: string, packPath: string, profilePath: string, report: Record<string, any> }}
+ */
+export function emitProductionTestArtifacts(root, report, pack, profile) {
+    const dir = path.join(root, profile.artifacts.dir);
+    fs.mkdirSync(dir, { recursive: true });
+    const stamped = { ...report, generatedAt: new Date().toISOString() };
+    const reportPath = path.join(dir, 'report.json');
+    const packPath = path.join(dir, 'scenario-pack.json');
+    const profilePath = path.join(dir, 'ci-profile.json');
+    fs.writeFileSync(reportPath, `${JSON.stringify(stamped, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(packPath, `${JSON.stringify(pack, null, 2)}\n`, 'utf8');
+    fs.writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
+    return { reportPath, packPath, profilePath, report: stamped };
+}
+/** Assert CI profile forbids JS test-runner disguise. */
+export function assertNoForbiddenRunners(profile, importedNames = []) {
+    const forbidden = new Set((profile.forbiddenRunners || []).map((s) => s.toLowerCase()));
+    const hits = importedNames.filter((n) => forbidden.has(String(n).toLowerCase()));
+    return hits;
+}
+export function sha256Text(text) {
+    return crypto.createHash('sha256').update(String(text), 'utf8').digest('hex');
+}

package/dist/release-cmd.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `vmz artifact` — pack / publish / rollback / diff (A3 filesystem Delivery Profile).
+ */
+/**
+ * @param {string[]} argv
+ * @param {{ root?: string }} [ctx]
+ */
+export declare function cmdArtifact(argv: any, ctx?: {}): 0 | 1;

package/dist/release-cmd.js

@@ -0,0 +1,126 @@
+// @ts-nocheck
+/**
+ * `vmz artifact` — pack / publish / rollback / diff (A3 filesystem Delivery Profile).
+ */
+import path from 'node:path';
+import { log } from './log.js';
+import { diffArtifacts, loadReleaseEnvelope, packRelease, publishRelease, readPointer, rollbackRelease } from './release-pack.js';
+function usage() {
+    console.log(`vmz artifact — filesystem release packaging (A3)
+
+Usage:
+  vmz artifact pack [dist]              Write dist/_vmz manifests + envelope
+  vmz artifact publish [dist]           Pack + publish under dist/releases (atomic CURRENT)
+  vmz artifact rollback [releases]      Restore PREVIOUS pointer (no rebuild)
+  vmz artifact diff <aDigest> <bDigest> Structured file digest diff
+  vmz artifact current [releases]       Print CURRENT digest
+
+Options:
+  --releases <dir>   Releases root (default: <app>/dist/releases)
+  --app-id <id>      applicationId for envelope
+  --json             Machine-readable stdout
+`);
+}
+/**
+ * @param {string[]} argv
+ * @param {{ root?: string }} [ctx]
+ */
+export function cmdArtifact(argv, ctx = {}) {
+    const args = [...argv];
+    if (!args.length || args[0] === 'help' || args[0] === '--help') {
+        usage();
+        return 0;
+    }
+    const sub = args.shift();
+    /** @type {Record<string, string | boolean>} */
+    const flags = {};
+    /** @type {string[]} */
+    const pos = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--json') {
+            flags.json = true;
+            continue;
+        }
+        if (a === '--releases' || a === '--app-id') {
+            flags[a.slice(2)] = args[++i];
+            continue;
+        }
+        if (a.startsWith('--')) {
+            const eq = a.indexOf('=');
+            if (eq !== -1)
+                flags[a.slice(2, eq)] = a.slice(eq + 1);
+            else
+                flags[a.slice(2)] = true;
+            continue;
+        }
+        pos.push(a);
+    }
+    const cwd = path.resolve(ctx.root || process.cwd());
+    const dist = path.resolve(cwd, pos[0] || 'dist');
+    const releases = path.resolve(typeof flags.releases === 'string' ? flags.releases : path.join(cwd, 'dist', 'releases'));
+    const appId = typeof flags['app-id'] === 'string' ? flags['app-id'] : undefined;
+    const asJson = Boolean(flags.json);
+    try {
+        if (sub === 'pack') {
+            const envelope = packRelease(dist, { applicationId: appId });
+            if (asJson)
+                console.log(JSON.stringify(envelope, null, 2));
+            else
+                log.info(`artifact pack: digest=${envelope.artifactDigest} files=${Object.keys(envelope.fileDigests || {}).length}`);
+            return 0;
+        }
+        if (sub === 'publish') {
+            const envelope = packRelease(dist, { applicationId: appId });
+            const pub = publishRelease(releases, dist, envelope);
+            const out = { ...pub, artifactDigest: envelope.artifactDigest };
+            if (asJson)
+                console.log(JSON.stringify(out, null, 2));
+            else
+                log.info(`artifact publish: CURRENT=${pub.digest} PREVIOUS=${pub.previous || '-'}`);
+            return 0;
+        }
+        if (sub === 'rollback') {
+            const root = pos[0] ? path.resolve(cwd, pos[0]) : releases;
+            const rb = rollbackRelease(root);
+            if (asJson)
+                console.log(JSON.stringify(rb, null, 2));
+            else
+                log.info(`artifact rollback: restored=${rb.restored} demoted=${rb.demoted || '-'}`);
+            return 0;
+        }
+        if (sub === 'current') {
+            const root = pos[0] ? path.resolve(cwd, pos[0]) : releases;
+            const cur = readPointer(path.join(root, 'CURRENT'));
+            if (asJson)
+                console.log(JSON.stringify({ current: cur }, null, 2));
+            else
+                console.log(cur || '');
+            return cur ? 0 : 1;
+        }
+        if (sub === 'diff') {
+            const aDig = pos[0];
+            const bDig = pos[1];
+            if (!aDig || !bDig) {
+                log.error('artifact diff requires <aDigest> <bDigest>');
+                return 1;
+            }
+            const a = loadReleaseEnvelope(releases, aDig);
+            const b = loadReleaseEnvelope(releases, bDig);
+            const diff = diffArtifacts(a, b);
+            if (asJson)
+                console.log(JSON.stringify(diff, null, 2));
+            else {
+                log.info(`artifact diff: identical=${diff.identical} changed=${diff.changed.length} added=${diff.added.length} removed=${diff.removed.length}`);
+            }
+            return 0;
+        }
+        log.error(`unknown artifact subcommand: ${sub}`);
+        usage();
+        return 1;
+    }
+    catch (e) {
+        log.error(String(e && e.message ? e.message : e));
+        return 1;
+    }
+}

package/dist/release-pack.d.ts

@@ -0,0 +1,96 @@
+/**
+ * A3 filesystem release packaging — digests, atomic pointer, rollback, artifact diff.
+ *
+ * Not the full CDN/StaticDelivery matrix. Same VPG build (`dist/`) is packed into
+ * `_vmz/*` manifests + content digests; publish retains previous release for rollback
+ * without rebuild.
+ */
+export declare const RELEASE_ENVELOPE_SCHEMA = "vmz.release.envelope.v0";
+export declare const APPLICATION_ARTIFACT_SCHEMA = "vmz.application.artifact.v0";
+export declare const DELIVERY_ARTIFACT_MANIFEST_SCHEMA = "vmz.profile.delivery_artifact_manifest.v0";
+export declare const ROUTE_REALIZATION_TABLE_SCHEMA = "vmz.profile.route_realization_table.v0";
+export declare const ARTIFACT_DIFF_SCHEMA = "vmz.artifact.diff.v0";
+/**
+ * @param {Buffer | string} data
+ */
+export declare function sha256Hex(data: any): string;
+/**
+ * @param {string} filePath
+ */
+export declare function sha256File(filePath: any): string;
+/**
+ * @param {unknown} value
+ */
+export declare function canonicalJson(value: any): string;
+/**
+ * Pack `dist/` into `_vmz` manifests + release envelope (filesystem Delivery Profile).
+ * @param {string} distDir
+ * @param {{ applicationId?: string }} [opts]
+ */
+export declare function packRelease(distDir: any, opts?: {}): {
+    artifactDigest: string;
+    schema: string;
+    applicationId: any;
+    deliveryProfile: string;
+    applicationIntegrity: any;
+    deploymentDigest: any;
+    programDigest: string;
+    styleDigest: any;
+    routeDigest: string;
+    fileDigests: {};
+    manifests: {
+        applicationArtifact: string;
+        deliveryArtifactManifest: string;
+        routeRealization: string;
+    };
+};
+/**
+ * @param {string} pointerPath
+ * @param {string} digest
+ */
+export declare function atomicWritePointer(pointerPath: any, digest: any): void;
+/**
+ * @param {string} pointerPath
+ * @returns {string | null}
+ */
+export declare function readPointer(pointerPath: any): string;
+/**
+ * Publish packed dist into releases root; retain previous pointer for rollback.
+ * @param {string} releasesRoot
+ * @param {string} distDir
+ * @param {ReturnType<typeof packRelease>} envelope
+ */
+export declare function publishRelease(releasesRoot: any, distDir: any, envelope: any): {
+    digest: any;
+    previous: string;
+    currentPath: string;
+    releaseDir: string;
+};
+/**
+ * Rollback CURRENT → PREVIOUS without rebuild.
+ * @param {string} releasesRoot
+ */
+export declare function rollbackRelease(releasesRoot: any): {
+    restored: string;
+    demoted: string;
+    releaseDir: string;
+};
+/**
+ * Structured diff between two release envelopes / digest maps.
+ * @param {{ fileDigests?: Record<string, string>, artifactDigest?: string }} a
+ * @param {{ fileDigests?: Record<string, string>, artifactDigest?: string }} b
+ */
+export declare function diffArtifacts(a: any, b: any): {
+    schema: string;
+    beforeDigest: any;
+    afterDigest: any;
+    added: any[];
+    removed: any[];
+    changed: any[];
+    identical: boolean;
+};
+/**
+ * @param {string} releasesRoot
+ * @param {string} digest
+ */
+export declare function loadReleaseEnvelope(releasesRoot: any, digest: any): any;