@hs-x/cli 0.2.7 → 0.3.6

package/dist/link-migration-journal.d.ts

@@ -0,0 +1,131 @@
+import type { LinkPreflightPlan } from './link-preflight.js';
+import { type TokenKeyCustodyAdapter } from './token-key-custody.js';
+/**
+ * Ordered step boundaries. Each is idempotent and resumable; the journal
+ * records which boundaries a run has crossed so a resumed `hs-x link` picks up
+ * exactly where a crash left off and converges to the same final state.
+ */
+export declare const LINK_MIGRATION_STEPS: readonly ["preflight-passed", "kv-owner-prefix-rewritten", "pointer-rewritten", "probe-passed", "cp-committed", "custody-rekeyed", "done"];
+export type LinkMigrationStep = (typeof LINK_MIGRATION_STEPS)[number];
+declare const LINK_MIGRATION_CODES: readonly ["HSX_E_LINK_PROBE_FAILED", "HSX_E_LINK_MIGRATION_INTERRUPTED"];
+export type LinkMigrationErrorCode = (typeof LINK_MIGRATION_CODES)[number];
+/** One binding's preserve-set — references only, never key bytes. */
+export interface LinkMigrationBinding {
+    readonly projectId: string;
+    readonly environment: string;
+    readonly hubSpotAppId: number;
+    readonly installKvNamespaceId: string;
+    readonly installKvNamespaceName: string;
+    readonly tokenKeySecretName: string;
+    readonly custodyMechanism: string;
+    /** custodyId embedding the OLD owner (what the binding records pre-link). */
+    readonly oldCustodyId: string;
+    /** custodyId embedding the NEW owner (what the binding records post-link). */
+    readonly newCustodyId: string;
+    /** Authoritative Worker names the migration must never rename. */
+    readonly workerNames: readonly string[];
+}
+export interface LinkMigrationJournal {
+    readonly schemaVersion: 1;
+    readonly journalId: string;
+    readonly status: 'in-progress' | 'done' | 'aborted';
+    readonly cloudflareAccountId: string;
+    readonly stateKvNamespaceId: string;
+    readonly priorOwnerId: string;
+    readonly newOwnerId: string;
+    readonly bindings: readonly LinkMigrationBinding[];
+    /** Union of every binding's Worker names — authoritative, never renamed. */
+    readonly workerNames: readonly string[];
+    readonly completedSteps: readonly LinkMigrationStep[];
+    /** Whether the CP commit reported success (gates old-custody removal). */
+    readonly cpCommitOk?: boolean;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export declare function defaultLinkMigrationJournalPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Deterministic journal id from the STABLE identity of the claim: the
+ * Cloudflare account, the tenant-state namespace, and the TARGET owner. It does
+ * NOT depend on the prior owner, so a resumed run finds the journal even after
+ * the local pointer has already been rewritten to the new owner.
+ */
+export declare function linkMigrationJournalId(input: {
+    readonly cloudflareAccountId: string;
+    readonly stateKvNamespaceId: string;
+    readonly newOwnerId: string;
+}): string;
+export declare function loadLinkMigrationJournal(journalId: string, path?: string): Promise<LinkMigrationJournal | undefined>;
+export declare function saveLinkMigrationJournal(journal: LinkMigrationJournal, path?: string): Promise<void>;
+export declare function deleteLinkMigrationJournal(journalId: string, path?: string): Promise<void>;
+/**
+ * Build a fresh (unpersisted) journal from a passed link-preflight plan. The
+ * preserve-set — Worker names, INSTALL_KV namespace ids, custody references —
+ * comes straight from the plan's STRUCTURED fields (never the informational
+ * `checks` strings). Only escrowed bindings can reach here (the preflight fails
+ * closed on `worker-secret-only` custody), so each binding has a custody id.
+ */
+export declare function buildLinkMigrationJournal(input: {
+    readonly plan: LinkPreflightPlan;
+    readonly newOwnerId: string;
+    readonly now?: () => Date;
+}): LinkMigrationJournal;
+/** The read/write surface the migration needs over a KV namespace. */
+export interface LinkMigrationKvClient {
+    get(key: string): Promise<string | undefined>;
+    put(key: string, value: string): Promise<void>;
+    list(prefix: string): Promise<readonly string[]>;
+    delete(key: string): Promise<void>;
+}
+export interface LinkProbeInput {
+    readonly binding: LinkMigrationBinding;
+    /** The escrowed token key, already proven to open the binding's canary. */
+    readonly resolvedTokenKey: string;
+    /** Read-only handle bound to the binding's EXACT INSTALL_KV namespace. */
+    readonly installKv: Pick<LinkMigrationKvClient, 'get' | 'list'>;
+}
+export type LinkProbe = (input: LinkProbeInput) => Promise<void>;
+export interface LinkMigrationSeams {
+    readonly stateKv: LinkMigrationKvClient;
+    readonly makeInstallKv: (namespaceId: string) => Pick<LinkMigrationKvClient, 'get' | 'list'>;
+    readonly custodyAdapter: TokenKeyCustodyAdapter;
+    /** Rewrite the local pointer's ownerId (forward = new, compensate = old). */
+    readonly rewritePointer: (ownerId: string) => Promise<void>;
+    /** Commit the owner rewrite to the control plane; undefined = ok. */
+    readonly commit: () => Promise<string | undefined>;
+    readonly probe?: LinkProbe;
+    readonly now?: () => Date;
+}
+export interface LinkMigrationResult {
+    readonly journal: LinkMigrationJournal;
+    readonly rewrittenKeyCount: number;
+    readonly rekeyedBindingCount: number;
+    readonly notifyWarning?: string;
+    readonly resumed: boolean;
+}
+/**
+ * Default probe: a harmless signed proof that token resolution still works AND
+ * the exact INSTALL_KV namespace is reachable after the owner rewrite. The
+ * canary was already opened (the resolved key is passed in); this additionally
+ * performs a read against the binding's INSTALL_KV namespace (a real HubSpot
+ * call is T04/live and out of scope). Throws a typed error on failure.
+ */
+export declare const defaultLinkProbe: LinkProbe;
+/**
+ * Run (or resume) the journaled link migration to convergence. Each step is
+ * skipped when the journal already records it, and every action is idempotent,
+ * so a resumed run reaches a final state identical to the unfailed path.
+ *
+ * `failAfter` injects a fatal interruption immediately AFTER a boundary is
+ * persisted — the seam the acceptance tests use to prove convergence. A probe
+ * failure (as opposed to an injected interruption after the probe boundary)
+ * compensates: the KV owner prefix and pointer are rolled back and the journal
+ * is cleared so the operation is re-runnable from a clean pre-link state.
+ */
+export declare function runLinkMigration(input: {
+    readonly journal: LinkMigrationJournal;
+    readonly seams: LinkMigrationSeams;
+    readonly journalPath?: string;
+    readonly failAfter?: string;
+}): Promise<LinkMigrationResult>;
+export {};
+//# sourceMappingURL=link-migration-journal.d.ts.map

package/dist/link-migration-journal.d.ts.map

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

package/dist/link-migration-journal.js

@@ -0,0 +1,395 @@
+// ADR-022 T03 — journaled, resumable transactional link migration.
+//
+// Linking an installed project must PRESERVE Worker identity, the exact
+// INSTALL_KV namespace, and the escrowed token key. The mutation sequence
+// (KV owner-prefix rewrite → local pointer rewrite → token-resolution probe →
+// control-plane owner commit → token-key custody re-key) is journaled with
+// explicit step boundaries so an injected failure at any boundary re-runs to
+// convergence WITHOUT replacing a key or a namespace. The probe (a harmless
+// signed proof, BEFORE the CP commit) is the point of no return that is still
+// reversible: if it fails, the KV owner prefix and the local pointer are rolled
+// back to the pre-link owner and the operation aborts with a typed error.
+//
+// The custody re-key follows the T01 handoff: the token key is re-escrowed
+// under the NEW owner's custody id while the OLD entry is kept, and the old
+// entry is removed only AFTER the CP commit succeeds — so there is never a
+// window with zero custody entries and the key bytes are never regenerated.
+//
+// The journal is a VERSIONED local record (CLI state dir, 0600) that carries
+// ONLY references — owner ids, namespace ids, worker names, secret NAMES, and
+// custody ids. It never contains key bytes or a sealed canary.
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { Schema, schemas } from '@hs-x/types';
+import { CliError } from './cli-error.js';
+import { statePath } from './paths.js';
+import { escrowTokenKey, resolveEscrowedTokenKey, tokenKeyCustodyIdFor, } from './token-key-custody.js';
+/**
+ * Ordered step boundaries. Each is idempotent and resumable; the journal
+ * records which boundaries a run has crossed so a resumed `hs-x link` picks up
+ * exactly where a crash left off and converges to the same final state.
+ */
+export const LINK_MIGRATION_STEPS = [
+    'preflight-passed',
+    'kv-owner-prefix-rewritten',
+    'pointer-rewritten',
+    'probe-passed',
+    'cp-committed',
+    'custody-rekeyed',
+    'done',
+];
+const LINK_MIGRATION_CODES = [
+    // The token-resolution probe failed AFTER the KV/pointer rewrite: the owner
+    // prefix and pointer were rolled back to the pre-link owner. Re-runnable.
+    'HSX_E_LINK_PROBE_FAILED',
+    // A journaled boundary was crossed and then the run was interrupted (the
+    // injected-failure seam, or a real crash). Re-running `hs-x link` resumes.
+    'HSX_E_LINK_MIGRATION_INTERRUPTED',
+];
+const EMPTY_STORE = { schemaVersion: 1, journals: {} };
+export function defaultLinkMigrationJournalPath(env = process.env) {
+    const override = env.HSX_LINK_JOURNAL_PATH;
+    if (override && override.length > 0)
+        return override;
+    return statePath('link-migrations.json');
+}
+/**
+ * Deterministic journal id from the STABLE identity of the claim: the
+ * Cloudflare account, the tenant-state namespace, and the TARGET owner. It does
+ * NOT depend on the prior owner, so a resumed run finds the journal even after
+ * the local pointer has already been rewritten to the new owner.
+ */
+export function linkMigrationJournalId(input) {
+    return createHash('sha256')
+        .update(`${input.cloudflareAccountId}\n${input.stateKvNamespaceId}\n${input.newOwnerId}`)
+        .digest('hex')
+        .slice(0, 24);
+}
+async function loadStore(path) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch {
+        return EMPTY_STORE;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed.schemaVersion !== 1 ||
+            typeof parsed.journals !== 'object' ||
+            parsed.journals === null) {
+            return EMPTY_STORE;
+        }
+        return { schemaVersion: 1, journals: parsed.journals };
+    }
+    catch {
+        return EMPTY_STORE;
+    }
+}
+async function writeStore(path, store) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(store, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    try {
+        await chmod(path, 0o600);
+    }
+    catch {
+        // best effort on platforms without POSIX perms
+    }
+}
+export async function loadLinkMigrationJournal(journalId, path = defaultLinkMigrationJournalPath()) {
+    const store = await loadStore(path);
+    return store.journals[journalId];
+}
+export async function saveLinkMigrationJournal(journal, path = defaultLinkMigrationJournalPath()) {
+    const store = await loadStore(path);
+    await writeStore(path, {
+        schemaVersion: 1,
+        journals: { ...store.journals, [journal.journalId]: journal },
+    });
+}
+export async function deleteLinkMigrationJournal(journalId, path = defaultLinkMigrationJournalPath()) {
+    const store = await loadStore(path);
+    if (!(journalId in store.journals))
+        return;
+    const { [journalId]: _removed, ...rest } = store.journals;
+    const remaining = rest;
+    if (Object.keys(remaining).length === 0) {
+        await rm(path, { force: true });
+        return;
+    }
+    await writeStore(path, { schemaVersion: 1, journals: remaining });
+}
+/**
+ * Build a fresh (unpersisted) journal from a passed link-preflight plan. The
+ * preserve-set — Worker names, INSTALL_KV namespace ids, custody references —
+ * comes straight from the plan's STRUCTURED fields (never the informational
+ * `checks` strings). Only escrowed bindings can reach here (the preflight fails
+ * closed on `worker-secret-only` custody), so each binding has a custody id.
+ */
+export function buildLinkMigrationJournal(input) {
+    const nowIso = (input.now ? input.now() : new Date()).toISOString();
+    const bindings = input.plan.bindings.map((binding) => ({
+        projectId: binding.projectId,
+        environment: binding.environment,
+        hubSpotAppId: binding.hubSpotAppId,
+        installKvNamespaceId: binding.installKvNamespaceId,
+        installKvNamespaceName: binding.installKvNamespaceName,
+        tokenKeySecretName: binding.tokenKeySecretName,
+        custodyMechanism: binding.tokenKeyCustody.mechanism,
+        oldCustodyId: binding.tokenKeyCustody.custodyId,
+        newCustodyId: tokenKeyCustodyIdFor({
+            ownerId: input.newOwnerId,
+            projectId: binding.projectId,
+            environment: binding.environment,
+            hubSpotAppId: binding.hubSpotAppId,
+        }),
+        workerNames: binding.workerNames,
+    }));
+    const workerNames = [...new Set(bindings.flatMap((binding) => binding.workerNames))].sort();
+    return {
+        schemaVersion: 1,
+        journalId: linkMigrationJournalId({
+            cloudflareAccountId: input.plan.cloudflareAccountId,
+            stateKvNamespaceId: input.plan.stateKvNamespaceId,
+            newOwnerId: input.newOwnerId,
+        }),
+        status: 'in-progress',
+        cloudflareAccountId: input.plan.cloudflareAccountId,
+        stateKvNamespaceId: input.plan.stateKvNamespaceId,
+        priorOwnerId: input.plan.priorOwnerId,
+        newOwnerId: input.newOwnerId,
+        bindings,
+        workerNames,
+        completedSteps: [],
+        createdAt: nowIso,
+        updatedAt: nowIso,
+    };
+}
+function migrationError(code, detail) {
+    return new CliError({ code, message: `${code}: ${detail}` });
+}
+/**
+ * Default probe: a harmless signed proof that token resolution still works AND
+ * the exact INSTALL_KV namespace is reachable after the owner rewrite. The
+ * canary was already opened (the resolved key is passed in); this additionally
+ * performs a read against the binding's INSTALL_KV namespace (a real HubSpot
+ * call is T04/live and out of scope). Throws a typed error on failure.
+ */
+export const defaultLinkProbe = async (input) => {
+    if (input.resolvedTokenKey.length === 0) {
+        throw migrationError('HSX_E_LINK_PROBE_FAILED', `token resolution for ${input.binding.installKvNamespaceId} produced an empty key.`);
+    }
+    try {
+        // Harmless token-state read: prove the preserved INSTALL_KV namespace still
+        // answers under the rewritten owner. We do not require any entries.
+        await input.installKv.list('token-state/');
+    }
+    catch (cause) {
+        throw migrationError('HSX_E_LINK_PROBE_FAILED', `INSTALL_KV namespace ${input.binding.installKvNamespaceId} did not respond to a token-state read: ${cause instanceof Error ? cause.message : String(cause)}`);
+    }
+};
+// ---------------------------------------------------------------------------
+// Owner-prefix rewrite (idempotent copy-then-delete; used forward + reverse)
+// ---------------------------------------------------------------------------
+async function rewriteOwnerPrefix(kv, from, to) {
+    const fromPrefix = `owners/${from}/`;
+    const toPrefix = `owners/${to}/`;
+    const fromKeys = await kv.list(fromPrefix);
+    if (fromKeys.length === 0)
+        return [];
+    const rewritten = [];
+    for (const fromKey of fromKeys) {
+        const value = await kv.get(fromKey);
+        if (value === undefined)
+            continue;
+        const toKey = `${toPrefix}${fromKey.slice(fromPrefix.length)}`;
+        await kv.put(toKey, rewriteOwnerIdValue(value, from, to));
+        rewritten.push({ fromKey, toKey });
+    }
+    // Delete sources only after every write succeeded, so a mid-loop crash leaves
+    // both prefixes populated rather than losing data.
+    for (const { fromKey } of rewritten) {
+        await kv.delete(fromKey);
+    }
+    return rewritten;
+}
+function rewriteOwnerIdValue(value, from, to) {
+    try {
+        const parsed = JSON.parse(value);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            !Array.isArray(parsed) &&
+            parsed.ownerId === from) {
+            return JSON.stringify({ ...parsed, ownerId: to });
+        }
+    }
+    catch {
+        // Non-JSON values keep their bytes.
+    }
+    return value;
+}
+function bindingKvKey(ownerId, binding) {
+    return `owners/${ownerId}/projects/${binding.projectId}/bindings/${binding.environment}/${binding.hubSpotAppId}`;
+}
+async function readBindingRecord(kv, ownerId, binding) {
+    const key = bindingKvKey(ownerId, binding);
+    const raw = await kv.get(key);
+    if (raw === undefined) {
+        throw migrationError('HSX_E_LINK_MIGRATION_INTERRUPTED', `binding record ${key} is missing after the owner rewrite — cannot re-key custody.`);
+    }
+    return Schema.decodeUnknownSync(schemas.LocalAppRuntimeBinding)(JSON.parse(raw));
+}
+// ---------------------------------------------------------------------------
+// The journaled runner
+// ---------------------------------------------------------------------------
+function withStep(journal, step, patch, nowIso) {
+    const completedSteps = journal.completedSteps.includes(step)
+        ? journal.completedSteps
+        : [...journal.completedSteps, step];
+    return { ...journal, ...patch, completedSteps, updatedAt: nowIso };
+}
+/**
+ * Run (or resume) the journaled link migration to convergence. Each step is
+ * skipped when the journal already records it, and every action is idempotent,
+ * so a resumed run reaches a final state identical to the unfailed path.
+ *
+ * `failAfter` injects a fatal interruption immediately AFTER a boundary is
+ * persisted — the seam the acceptance tests use to prove convergence. A probe
+ * failure (as opposed to an injected interruption after the probe boundary)
+ * compensates: the KV owner prefix and pointer are rolled back and the journal
+ * is cleared so the operation is re-runnable from a clean pre-link state.
+ */
+export async function runLinkMigration(input) {
+    const path = input.journalPath ?? defaultLinkMigrationJournalPath();
+    const now = input.seams.now ?? (() => new Date());
+    const probe = input.seams.probe ?? defaultLinkProbe;
+    const resumed = input.journal.completedSteps.length > 0;
+    let journal = input.journal;
+    let rewrittenKeyCount = 0;
+    let rekeyedBindingCount = 0;
+    let notifyWarning;
+    const persist = async (step, patch = {}) => {
+        journal = withStep(journal, step, patch, now().toISOString());
+        await saveLinkMigrationJournal(journal, path);
+        if (input.failAfter && input.failAfter === step) {
+            throw migrationError('HSX_E_LINK_MIGRATION_INTERRUPTED', `injected failure after boundary "${step}".`);
+        }
+    };
+    const done = (step) => journal.completedSteps.includes(step);
+    // ── preflight-passed: recorded at journal creation. ──────────────────────
+    if (!done('preflight-passed')) {
+        await persist('preflight-passed');
+    }
+    // ── KV owner-prefix rewrite (idempotent copy-then-delete). ───────────────
+    if (!done('kv-owner-prefix-rewritten')) {
+        const rewritten = await rewriteOwnerPrefix(input.seams.stateKv, journal.priorOwnerId, journal.newOwnerId);
+        rewrittenKeyCount = rewritten.length;
+        await persist('kv-owner-prefix-rewritten');
+    }
+    // ── Local pointer rewrite (idempotent). ──────────────────────────────────
+    if (!done('pointer-rewritten')) {
+        await input.seams.rewritePointer(journal.newOwnerId);
+        await persist('pointer-rewritten');
+    }
+    // ── Probe: token resolution + INSTALL_KV read. Reversible on failure. ────
+    if (!done('probe-passed')) {
+        try {
+            for (const binding of journal.bindings) {
+                const record = await readBindingRecord(input.seams.stateKv, journal.newOwnerId, binding);
+                if (record.tokenKeyCustody.kind !== 'escrowed') {
+                    throw migrationError('HSX_E_LINK_PROBE_FAILED', `binding ${bindingKvKey(journal.newOwnerId, binding)} no longer records escrowed custody.`);
+                }
+                const resolvedTokenKey = await resolveEscrowedTokenKey({
+                    custody: record.tokenKeyCustody,
+                    adapter: input.seams.custodyAdapter,
+                });
+                await probe({
+                    binding,
+                    resolvedTokenKey,
+                    installKv: input.seams.makeInstallKv(binding.installKvNamespaceId),
+                });
+            }
+        }
+        catch (cause) {
+            await compensate(journal, input.seams);
+            await deleteLinkMigrationJournal(journal.journalId, path);
+            if (cause instanceof CliError)
+                throw cause;
+            throw migrationError('HSX_E_LINK_PROBE_FAILED', cause instanceof Error ? cause.message : String(cause));
+        }
+        await persist('probe-passed');
+    }
+    // ── Control-plane owner commit (best-effort; gates old-custody removal). ─
+    if (!done('cp-committed')) {
+        notifyWarning = await input.seams.commit();
+        await persist('cp-committed', { cpCommitOk: notifyWarning === undefined });
+    }
+    // ── Custody re-key: re-escrow under the new owner's id, then (only once ───
+    //    the CP commit succeeded) remove the old entry. Never a zero-entry gap.
+    if (!done('custody-rekeyed')) {
+        const cpCommitOk = journal.cpCommitOk === true;
+        for (const binding of journal.bindings) {
+            const record = await readBindingRecord(input.seams.stateKv, journal.newOwnerId, binding);
+            if (record.tokenKeyCustody.kind !== 'escrowed')
+                continue;
+            if (record.tokenKeyCustody.custodyId === binding.newCustodyId) {
+                // Already re-keyed on a prior (interrupted) run — just ensure the old
+                // entry is gone (idempotent) when the CP commit has succeeded.
+                if (cpCommitOk)
+                    await input.seams.custodyAdapter.remove(binding.oldCustodyId);
+                continue;
+            }
+            // Resolve the SAME key from the old custody, re-escrow it under the new
+            // custody id (a fresh canary is sealed under the identical key — no new
+            // key is minted), then repoint the binding record at the new custody.
+            const tokenKey = await resolveEscrowedTokenKey({
+                custody: record.tokenKeyCustody,
+                adapter: input.seams.custodyAdapter,
+            });
+            const newCustody = await escrowTokenKey({
+                adapter: input.seams.custodyAdapter,
+                custodyId: binding.newCustodyId,
+                tokenKeySecretValue: tokenKey,
+                ...(input.seams.now ? { now: input.seams.now } : {}),
+            });
+            const updated = {
+                ...record,
+                tokenKeyCustody: newCustody,
+                updatedAt: now().toISOString(),
+            };
+            await input.seams.stateKv.put(bindingKvKey(journal.newOwnerId, binding), JSON.stringify(Schema.encodeSync(schemas.LocalAppRuntimeBinding)(updated)));
+            // Old entry removed only after the CP commit succeeded (both entries
+            // coexist until here, so there is never a window with zero custody).
+            if (cpCommitOk)
+                await input.seams.custodyAdapter.remove(binding.oldCustodyId);
+            rekeyedBindingCount += 1;
+        }
+        await persist('custody-rekeyed');
+    }
+    // ── Done. ────────────────────────────────────────────────────────────────
+    if (!done('done')) {
+        await persist('done', { status: 'done' });
+    }
+    return {
+        journal,
+        rewrittenKeyCount,
+        rekeyedBindingCount,
+        resumed,
+        ...(notifyWarning !== undefined ? { notifyWarning } : {}),
+    };
+}
+/**
+ * Roll the reversible steps back to the pre-link owner: reverse the KV owner
+ * prefix (new → old) and the local pointer. Custody is untouched at probe time
+ * (re-key runs later), so there is nothing to undo there.
+ */
+async function compensate(journal, seams) {
+    if (journal.completedSteps.includes('kv-owner-prefix-rewritten')) {
+        await rewriteOwnerPrefix(seams.stateKv, journal.newOwnerId, journal.priorOwnerId);
+    }
+    if (journal.completedSteps.includes('pointer-rewritten')) {
+        await seams.rewritePointer(journal.priorOwnerId);
+    }
+}
+//# sourceMappingURL=link-migration-journal.js.map

package/dist/link-migration-journal.js.map

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

package/dist/link-preflight.d.ts

@@ -0,0 +1,78 @@
+import { Schema, schemas } from '@hs-x/types';
+import { type TokenKeyCustodyAdapter } from './token-key-custody.js';
+type CloudflarePointer = Schema.Schema.Type<typeof schemas.CloudflarePointer>;
+declare const LINK_PREFLIGHT_CODES: readonly ["HSX_E_LINK_PREFLIGHT_NAMESPACE", "HSX_E_LINK_PREFLIGHT_STATE_CORRUPT", "HSX_E_LINK_PREFLIGHT_AMBIGUOUS", "HSX_E_LINK_PREFLIGHT_UNPROVEN"];
+export type LinkPreflightErrorCode = (typeof LINK_PREFLIGHT_CODES)[number];
+/** Read-only slice of the tenant-state KV surface the preflight is allowed. */
+export interface LinkPreflightReadOnlyKv {
+    get(key: string): Promise<string | undefined>;
+    list(prefix: string): Promise<readonly string[]>;
+}
+export interface LinkPreflightNamespaceInfo {
+    readonly id: string;
+    readonly title: string;
+}
+/** One binding's redacted continuity plan — names and ids, never key bytes. */
+export interface LinkPreflightBindingPlan {
+    readonly projectId: string;
+    readonly environment: string;
+    readonly hubSpotAppId: number;
+    /** Worker names recorded by the active deploy for this project/environment. */
+    readonly workerNames: readonly string[];
+    readonly installKvNamespaceId: string;
+    readonly installKvNamespaceName: string;
+    readonly tokenKeySecretName: string;
+    readonly tokenKeyCustody: {
+        readonly kind: 'escrowed';
+        readonly mechanism: string;
+        readonly custodyId: string;
+        /** The escrowed key was retrieved and opened the sealed canary. */
+        readonly canaryProven: true;
+    };
+}
+export interface LinkPreflightPlan {
+    readonly plan: 'link-preflight';
+    readonly schemaVersion: 1;
+    readonly priorOwnerId: string;
+    readonly newOwnerId?: string;
+    readonly cloudflareAccountId: string;
+    readonly stateKvNamespaceId: string;
+    readonly ownerMetaPresent: boolean;
+    readonly bindings: readonly LinkPreflightBindingPlan[];
+    /** Deterministic, ordered record of what was proven. */
+    readonly checks: readonly string[];
+}
+/**
+ * Read-only Cloudflare KV namespace metadata lookup:
+ * `GET /client/v4/accounts/{account}/storage/kv/namespaces/{id}`.
+ * `undefined` = the namespace does not exist. Transport / auth failures throw
+ * `HSX_E_API_NETWORK` (they are not evidence of a missing namespace).
+ */
+export declare function fetchCloudflareKvNamespace(input: {
+    readonly accountId: string;
+    readonly apiToken: string;
+    readonly namespaceId: string;
+    readonly baseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+}): Promise<LinkPreflightNamespaceInfo | undefined>;
+/**
+ * Run the ADR-022 continuity preflight for one owner prefix. Read-only by
+ * construction: the KV surface exposes only get/list, the namespace lookup is
+ * a metadata GET, and custody resolution is the T01 read-only primitive.
+ * Throws typed `CliError`s (the link-preflight codes above, or the T01
+ * token-key-custody codes); returns the redacted plan on success.
+ */
+export declare function runLinkPreflight(input: {
+    readonly pointer: CloudflarePointer;
+    /** The `local_*` (or current) owner prefix link intends to rewrite. */
+    readonly priorOwnerId: string;
+    /** Known claim target; omitted in the dashboard flow (target chosen later). */
+    readonly newOwnerId?: string;
+    readonly apiToken?: string;
+    readonly baseUrl?: string;
+    readonly kv?: LinkPreflightReadOnlyKv;
+    readonly getNamespace?: (namespaceId: string) => Promise<LinkPreflightNamespaceInfo | undefined>;
+    readonly custodyAdapter?: TokenKeyCustodyAdapter;
+}): Promise<LinkPreflightPlan>;
+export {};
+//# sourceMappingURL=link-preflight.d.ts.map

package/dist/link-preflight.d.ts.map

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