opencode-session-port 0.0.0-stage → 0.1.1

package/src/core/crypto/kdf.ts

@@ -0,0 +1,101 @@
+/**
+ * Password KDF boundary for the provisional crypto container.
+ *
+ * Pinned `libsodium-wrappers-sumo@0.8.4` default ESM import + `await
+ * sodium.ready` (Phase 1 evidence: runtime named exports are not populated;
+ * the default object is).
+ *
+ * IMPORTANT (Oracle Gate 1 condition): the `seal`/`openAndStage` Promise
+ * boundary permits asynchronous execution but does NOT promise a nonblocking
+ * KDF. `crypto_pwhash` is synchronous and may block the event loop. Do not
+ * assume worker support and do not wire this into the TUI until the latency
+ * and execution strategy are measured (O-21 / O-19 follow-up).
+ */
+import sodium from "libsodium-wrappers-sumo";
+import {
+	ENVELOPE_FRAME_OVERHEAD_BYTES,
+	ENVELOPE_KDF_ARGON2ID13,
+	ENVELOPE_HEADER_SALT_BYTES,
+	ENVELOPE_SECRETSTREAM_HEADER_BYTES,
+} from "./envelope.ts";
+import { CryptoContainerError } from "./errors.ts";
+import type { CryptoPolicyDefinition } from "./policy.ts";
+
+/** Derives the 32-byte secretstream key from raw password bytes and a salt. */
+export interface PasswordKeyDerivation {
+	deriveKey(definition: CryptoPolicyDefinition, password: Uint8Array, salt: Uint8Array): Uint8Array;
+}
+
+function unsupported(detail: string): never {
+	throw new CryptoContainerError("unsupported-runtime", `unsupported libsodium runtime: ${detail}`);
+}
+
+/**
+ * Awaits `sodium.ready` and asserts that every primitive/constant this module
+ * relies on matches the provisional format assumptions. A mismatch fails
+ * closed instead of silently using an unvalidated layout.
+ */
+export async function requireSupportedSodiumRuntime(): Promise<void> {
+	await sodium.ready;
+
+	const requiredFunctions = [
+		"crypto_pwhash",
+		"crypto_secretstream_xchacha20poly1305_init_push",
+		"crypto_secretstream_xchacha20poly1305_init_pull",
+		"crypto_secretstream_xchacha20poly1305_push",
+		"crypto_secretstream_xchacha20poly1305_pull",
+		"randombytes_buf",
+		"memzero",
+		// O-22: remapped-ID derivation hashes with BLAKE2b-256 through
+		// `crypto_generichash`; a runtime without it must fail closed.
+		"crypto_generichash",
+	] as const;
+	for (const name of requiredFunctions) {
+		if (typeof sodium[name] !== "function") unsupported(`missing function ${name}`);
+	}
+
+	if (sodium.crypto_pwhash_ALG_ARGON2ID13 !== ENVELOPE_KDF_ARGON2ID13) {
+		unsupported("Argon2id algorithm id does not match the provisional format");
+	}
+	if (sodium.crypto_pwhash_SALTBYTES !== ENVELOPE_HEADER_SALT_BYTES) {
+		unsupported("crypto_pwhash salt size does not match the provisional format");
+	}
+	if (sodium.crypto_secretstream_xchacha20poly1305_HEADERBYTES !== ENVELOPE_SECRETSTREAM_HEADER_BYTES) {
+		unsupported("secretstream header size does not match the provisional format");
+	}
+	if (sodium.crypto_secretstream_xchacha20poly1305_ABYTES !== ENVELOPE_FRAME_OVERHEAD_BYTES) {
+		unsupported("secretstream ciphertext overhead does not match the provisional format");
+	}
+	if (sodium.crypto_secretstream_xchacha20poly1305_KEYBYTES !== 32) {
+		unsupported("secretstream key size does not match the provisional format");
+	}
+	if (sodium.crypto_secretstream_xchacha20poly1305_TAG_MESSAGE !== 0) {
+		unsupported("secretstream message tag does not match the provisional format");
+	}
+	if (sodium.crypto_secretstream_xchacha20poly1305_TAG_FINAL !== 3) {
+		unsupported("secretstream final tag does not match the provisional format");
+	}
+	// The pinned wrappers report crypto_pwhash_BYTES_MAX as a negative sentinel,
+	// so only the lower bound is checked here.
+	if (sodium.crypto_secretstream_xchacha20poly1305_KEYBYTES < sodium.crypto_pwhash_BYTES_MIN) {
+		unsupported("secretstream key size is below the crypto_pwhash output minimum");
+	}
+}
+
+/**
+ * Default derivation: Argon2id via `crypto_pwhash` with the definition's
+ * allow-listed costs. The returned key is owned by the caller and must be
+ * best-effort zeroed after the secretstream state is initialized.
+ */
+export const sodiumArgon2idDerivation: PasswordKeyDerivation = {
+	deriveKey(definition, password, salt) {
+		return sodium.crypto_pwhash(
+			sodium.crypto_secretstream_xchacha20poly1305_KEYBYTES,
+			password,
+			salt,
+			definition.kdf.opsLimit,
+			definition.kdf.memLimit,
+			sodium.crypto_pwhash_ALG_ARGON2ID13,
+		);
+	},
+};

package/src/core/crypto/policy.ts

@@ -0,0 +1,202 @@
+/**
+ * Allow-listed crypto policy definitions.
+ *
+ * Numeric profiles/caps live here as caller-supplied definitions — never in
+ * the shared contract and never in the artifact. The artifact only references
+ * a profile code that must resolve through the factory's allow-list.
+ *
+ * NO production profile is defined in this repository yet: Argon2id costs,
+ * chunk size, and artifact/compressed/decompressed/expansion/password caps are
+ * OPEN (O-01/O-03) and must be benchmarked and owner-approved before any
+ * production definition ships. `maxCompressedBytes` is a required distinct
+ * caller-supplied limit (never derived from `maxArtifactBytes`); tests
+ * construct clearly-marked test-only definitions.
+ */
+import type { CryptoPolicy } from "../contracts/crypto.ts";
+import { CryptoContainerError } from "./errors.ts";
+import {
+	ENVELOPE_PROFILE_CODE_MAX,
+	ENVELOPE_PROFILE_CODE_MIN,
+	FRAME_MAX_CIPHERTEXT_BYTES,
+} from "./envelope.ts";
+
+/** One allow-listed policy: numeric KDF costs, framing, and resource caps. */
+export interface CryptoPolicyDefinition {
+	/** Stable code-selected profile identifier used by `CheckpointCryptoFactory.create`. */
+	readonly id: string;
+	/** One-byte code stored in the artifact header and resolved against the allow-list. */
+	readonly profileCode: number;
+	readonly kdf: {
+		/** Argon2id ops limit; must be within the pinned libsodium bounds. */
+		readonly opsLimit: number;
+		/** Argon2id memory limit in bytes; must be within the pinned libsodium bounds. */
+		readonly memLimit: number;
+	};
+	readonly compression: {
+		/** zlib level (-1 default, 0..9) or undefined for the library default. */
+		readonly level?: number | undefined;
+	};
+	readonly framing: {
+		/** Plaintext bytes per secretstream frame produced while sealing. */
+		readonly chunkBytes: number;
+	};
+	readonly limits: {
+		readonly maxPasswordBytes: number;
+		readonly maxArtifactBytes: number;
+		/**
+		 * Required cap on the decrypted gzip (compressed) byte count, enforced
+		 * while streaming before each chunk is accepted. This is a distinct
+		 * caller-supplied limit, NOT derived from `maxArtifactBytes`; numeric
+		 * values remain OPEN (O-03).
+		 */
+		readonly maxCompressedBytes: number;
+		readonly maxDecompressedBytes: number;
+		readonly maxExpansionRatio: number;
+	};
+}
+
+/** Runtime bounds taken from the pinned libsodium build (not chosen here). */
+export interface SodiumPolicyBounds {
+	readonly opsLimitMin: number;
+	readonly memLimitMin: number;
+	readonly ciphertextOverheadBytes: number;
+}
+
+export interface CryptoPolicyRegistry {
+	readonly byId: ReadonlyMap<string, CryptoPolicyDefinition>;
+	readonly byProfileCode: ReadonlyMap<number, CryptoPolicyDefinition>;
+}
+
+function invalid(message: string): never {
+	throw new CryptoContainerError("invalid-policy-definition", message);
+}
+
+function asRecord(value: unknown, field: string): Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		invalid(`${field} must be an object`);
+	}
+	return value as Record<string, unknown>;
+}
+
+function requireSafeInteger(value: unknown, field: string, min: number, max: number): number {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+		invalid(`${field} must be a safe integer between ${min} and ${max}`);
+	}
+	return value;
+}
+
+function normalizeDefinition(raw: unknown, bounds: SodiumPolicyBounds): CryptoPolicyDefinition {
+	const source = asRecord(raw, "policy definition");
+	const id = source["id"];
+	if (typeof id !== "string" || id.length === 0) invalid("policy definition id must be a non-empty string");
+	const profileCode = requireSafeInteger(
+		source["profileCode"],
+		"policy definition profileCode",
+		ENVELOPE_PROFILE_CODE_MIN,
+		ENVELOPE_PROFILE_CODE_MAX,
+	);
+
+	const kdf = asRecord(source["kdf"], "policy definition kdf");
+	// Upper bounds: the pinned 0.8.4 wrappers report the library `_MAX`
+	// constants as negative sentinels, so they are not usable here; definitions
+	// are caller-supplied (trusted) and only need JS-safe integer validation.
+	const opsLimit = requireSafeInteger(kdf["opsLimit"], "kdf.opsLimit", bounds.opsLimitMin, Number.MAX_SAFE_INTEGER);
+	const memLimit = requireSafeInteger(kdf["memLimit"], "kdf.memLimit", bounds.memLimitMin, Number.MAX_SAFE_INTEGER);
+
+	const compression = asRecord(source["compression"], "policy definition compression");
+	const level = compression["level"];
+	const normalizedLevel = level === undefined ? undefined : requireSafeInteger(level, "compression.level", -1, 9);
+
+	const framing = asRecord(source["framing"], "policy definition framing");
+	const maxChunkBytes = FRAME_MAX_CIPHERTEXT_BYTES - bounds.ciphertextOverheadBytes;
+	const chunkBytes = requireSafeInteger(framing["chunkBytes"], "framing.chunkBytes", 1, maxChunkBytes);
+
+	const limits = asRecord(source["limits"], "policy definition limits");
+	const maxPasswordBytes = requireSafeInteger(limits["maxPasswordBytes"], "limits.maxPasswordBytes", 0, Number.MAX_SAFE_INTEGER);
+	const maxArtifactBytes = requireSafeInteger(limits["maxArtifactBytes"], "limits.maxArtifactBytes", 1, Number.MAX_SAFE_INTEGER);
+	// A gzip stream needs at least one nonempty member, so the compressed cap
+	// minimum is 1; a distinct value is required, never derived from the
+	// artifact cap (O-03 numeric values remain OPEN).
+	const maxCompressedBytes = requireSafeInteger(
+		limits["maxCompressedBytes"],
+		"limits.maxCompressedBytes",
+		1,
+		Number.MAX_SAFE_INTEGER,
+	);
+	const maxDecompressedBytes = requireSafeInteger(
+		limits["maxDecompressedBytes"],
+		"limits.maxDecompressedBytes",
+		0,
+		Number.MAX_SAFE_INTEGER,
+	);
+	const maxExpansionRatio = limits["maxExpansionRatio"];
+	if (typeof maxExpansionRatio !== "number" || !Number.isFinite(maxExpansionRatio) || maxExpansionRatio <= 0) {
+		invalid("limits.maxExpansionRatio must be a positive finite number");
+	}
+
+	return Object.freeze({
+		id,
+		profileCode,
+		kdf: Object.freeze({ opsLimit, memLimit }),
+		compression: Object.freeze({ level: normalizedLevel }),
+		framing: Object.freeze({ chunkBytes }),
+		limits: Object.freeze({
+			maxPasswordBytes,
+			maxArtifactBytes,
+			maxCompressedBytes,
+			maxDecompressedBytes,
+			maxExpansionRatio,
+		}),
+	});
+}
+
+/**
+ * Validates and copies caller-supplied definitions into an immutable
+ * allow-list. Duplicate ids/profile codes and out-of-range numeric values are
+ * rejected (fail closed); an empty allow-list is valid and rejects every
+ * `create` call.
+ */
+export function buildCryptoPolicyRegistry(
+	definitions: readonly CryptoPolicyDefinition[],
+	bounds: SodiumPolicyBounds,
+): CryptoPolicyRegistry {
+	if (!Array.isArray(definitions)) invalid("policy definitions must be an array");
+	const byId = new Map<string, CryptoPolicyDefinition>();
+	const byProfileCode = new Map<number, CryptoPolicyDefinition>();
+	for (const raw of definitions) {
+		const definition = normalizeDefinition(raw, bounds);
+		if (byId.has(definition.id)) invalid("duplicate policy definition id");
+		if (byProfileCode.has(definition.profileCode)) invalid("duplicate policy profile code");
+		byId.set(definition.id, definition);
+		byProfileCode.set(definition.profileCode, definition);
+	}
+	return { byId, byProfileCode };
+}
+
+/** Resolves an explicitly selected policy id; unknown ids fail closed. */
+export function resolvePolicyById(registry: CryptoPolicyRegistry, policy: CryptoPolicy): CryptoPolicyDefinition {
+	const id = (policy as { id?: unknown } | null | undefined)?.id;
+	if (typeof id !== "string" || id.length === 0) {
+		throw new CryptoContainerError("unknown-policy", "an explicit non-empty crypto policy id is required");
+	}
+	const definition = registry.byId.get(id);
+	if (definition === undefined) {
+		throw new CryptoContainerError("unknown-policy", "the requested crypto policy id is not allow-listed");
+	}
+	return definition;
+}
+
+/**
+ * Resolves the artifact's one-byte profile code strictly through the
+ * caller-supplied allow-list. Unknown codes fail closed before any KDF work.
+ */
+export function resolvePolicyByProfileCode(
+	registry: CryptoPolicyRegistry,
+	profileCode: number,
+): CryptoPolicyDefinition {
+	const definition = registry.byProfileCode.get(profileCode);
+	if (definition === undefined) {
+		throw new CryptoContainerError("unknown-kdf-profile", "artifact references a KDF profile that is not allow-listed");
+	}
+	return definition;
+}

package/src/core/crypto/zero.ts

@@ -0,0 +1,33 @@
+/**
+ * Best-effort clearing of byte buffers owned by this module.
+ *
+ * There is NO secure-deletion guarantee (A-07): this only overwrites buffers
+ * this module allocated. Caller-owned password material is never modified.
+ * libsodium secretstream state objects are released by dropping references;
+ * pinned libsodium-wrappers-sumo@0.8.4 exposes no documented generic free
+ * helper for them (see Phase 1 evidence / lib-13).
+ */
+import sodium from "libsodium-wrappers-sumo";
+
+/** Best-effort zero of a module-owned buffer. */
+export function bestEffortZero(bytes: Uint8Array): void {
+	if (bytes.length > 0) sodium.memzero(bytes);
+}
+
+/** Best-effort zero of all module-owned buffers in a list. */
+export function bestEffortZeroAll(chunks: readonly Uint8Array[]): void {
+	for (const chunk of chunks) bestEffortZero(chunk);
+}
+
+/** Concatenates fresh copies into one new buffer owned by the caller. */
+export function concatChunks(chunks: readonly Uint8Array[]): Uint8Array {
+	let total = 0;
+	for (const chunk of chunks) total += chunk.length;
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.length;
+	}
+	return out;
+}

package/src/core/restore/identity.ts

@@ -0,0 +1,202 @@
+/**
+ * PROVISIONAL per-artifact remapped-ID derivation (owner-selected O-22 scheme).
+ *
+ * ============================ NOT FROZEN ============================
+ * On 2026-10-09 the owner selected the scheme for implementation: remapped
+ * IDs are derived with BLAKE2b-256 (via the pinned
+ * `libsodium-wrappers-sumo@0.8.4` `crypto_generichash`) over a versioned,
+ * namespace-separated, unambiguously length-prefixed tuple of the artifact
+ * identity and the original ID, encoded as `ses_` + 64 lowercase hex for
+ * sessions and `msg_` + 64 lowercase hex for messages. The exact byte layout
+ * below is a PROVISIONAL, versioned encoding fixed only for this
+ * implementation so tests can pin it. It is not a released format, carries no
+ * backward-compatibility promise, and makes no host/runtime compatibility
+ * claim: exact artifact placement of the identity remains subject to O-02,
+ * and host validation of derived IDs remains OPEN (OQ-24).
+ *
+ * The `v1` version tag is part of the derivation domain. Any future encoding
+ * change must use a new tag instead of silently reinterpreting `v1`.
+ * =====================================================================
+ *
+ * Framed derivation input, in order. Every field — including the raw identity
+ * and the final variable-length JSON string — is prefixed by its byte length
+ * encoded as an 8-byte unsigned big-endian integer:
+ *
+ *   field                              bytes
+ *   UTF-8 "SessionPort/remapped-id"      23
+ *   UTF-8 "v1"                            2
+ *   UTF-8 namespace ("session"/"message") 7
+ *   raw artifact identity                16
+ *   UTF-8 of JSON.stringify(originalID)  variable
+ *
+ * `JSON.stringify` is applied to a validated JS string, so arbitrary string
+ * values are preserved exactly: lone surrogates are escaped by well-formed
+ * JSON.stringify and `TextEncoder` therefore never applies lossy U+FFFD
+ * replacement to the original ID. The length prefixes keep the tuple
+ * unambiguous despite the variable-length final field.
+ *
+ * The original ID is never included in any output or error message; only the
+ * 32-byte BLAKE2b digest is hex-encoded. There is no fallback or regeneration
+ * behavior: invalid inputs fail closed.
+ */
+import sodium from "libsodium-wrappers-sumo";
+import { ARTIFACT_IDENTITY_BYTES, type ArtifactIdentity } from "../contracts/crypto.ts";
+import { requireSupportedSodiumRuntime } from "../crypto/kdf.ts";
+
+/** Remap namespaces; each derives in a distinct domain. */
+export type RemappedIdNamespace = "session" | "message";
+
+/**
+ * Synchronous deriver over the provisional O-22 encoding. Construct it once
+ * with `createRemappedIdDeriver()` (which awaits/validates pinned sodium
+ * readiness); `derive` is pure and synchronous thereafter.
+ */
+export interface RemappedIdDeriver {
+	derive(namespace: RemappedIdNamespace, artifactIdentity: ArtifactIdentity, originalID: string): string;
+}
+
+/** Fail-closed validation/runtime codes for remapped-ID derivation. */
+export type RemappedIdErrorCode =
+	| "invalid-namespace"
+	| "invalid-artifact-identity"
+	| "invalid-original-id"
+	| "derivation-failure";
+
+/** Error that never echoes the original ID. */
+export class RemappedIdError extends Error {
+	readonly code: RemappedIdErrorCode;
+
+	constructor(code: RemappedIdErrorCode, message: string) {
+		super(message);
+		this.name = "RemappedIdError";
+		this.code = code;
+	}
+}
+
+/** Provisional domain/version tags; see the module comment before changing. */
+const REMAPPED_ID_DOMAIN = "SessionPort/remapped-id";
+const REMAPPED_ID_VERSION = "v1";
+
+const HASH_BYTES = 32;
+const LENGTH_PREFIX_BYTES = 8;
+const OUTPUT_PREFIX: Readonly<Record<RemappedIdNamespace, string>> = Object.freeze({
+	session: "ses_",
+	message: "msg_",
+});
+
+const textEncoder = new TextEncoder();
+const HEX_DIGITS = "0123456789abcdef";
+
+function invalidNamespace(): never {
+	throw new RemappedIdError("invalid-namespace", 'namespace must be exactly "session" or "message"');
+}
+
+function invalidIdentity(): never {
+	throw new RemappedIdError(
+		"invalid-artifact-identity",
+		`artifact identity must be a Uint8Array of exactly ${ARTIFACT_IDENTITY_BYTES} bytes`,
+	);
+}
+
+function invalidOriginalId(): never {
+	throw new RemappedIdError("invalid-original-id", "original ID must be a string");
+}
+
+function validateNamespace(namespace: RemappedIdNamespace): RemappedIdNamespace {
+	if (namespace !== "session" && namespace !== "message") invalidNamespace();
+	return namespace;
+}
+
+function validateArtifactIdentity(artifactIdentity: ArtifactIdentity): ArtifactIdentity {
+	if (!(artifactIdentity instanceof Uint8Array) || artifactIdentity.length !== ARTIFACT_IDENTITY_BYTES) {
+		invalidIdentity();
+	}
+	return artifactIdentity;
+}
+
+function validateOriginalId(originalID: string): string {
+	if (typeof originalID !== "string") invalidOriginalId();
+	return originalID;
+}
+
+/** 8-byte unsigned big-endian byte-length prefix. */
+function encodeLengthPrefix(byteLength: number): Uint8Array {
+	const prefix = new Uint8Array(LENGTH_PREFIX_BYTES);
+	new DataView(prefix.buffer).setBigUint64(0, BigInt(byteLength), false);
+	return prefix;
+}
+
+/** One length-prefixed framed field: u64 BE length || raw field bytes. */
+function frameField(field: Uint8Array): Uint8Array {
+	const out = new Uint8Array(LENGTH_PREFIX_BYTES + field.length);
+	out.set(encodeLengthPrefix(field.length), 0);
+	out.set(field, LENGTH_PREFIX_BYTES);
+	return out;
+}
+
+/**
+ * Builds the exact framed derivation input documented in the module comment.
+ * All inputs are already validated.
+ */
+function buildDerivationInput(
+	namespace: RemappedIdNamespace,
+	artifactIdentity: ArtifactIdentity,
+	originalID: string,
+): Uint8Array {
+	const fields = [
+		frameField(textEncoder.encode(REMAPPED_ID_DOMAIN)),
+		frameField(textEncoder.encode(REMAPPED_ID_VERSION)),
+		frameField(textEncoder.encode(namespace)),
+		frameField(artifactIdentity),
+		frameField(textEncoder.encode(JSON.stringify(originalID))),
+	];
+	let total = 0;
+	for (const field of fields) total += field.length;
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const field of fields) {
+		out.set(field, offset);
+		offset += field.length;
+	}
+	return out;
+}
+
+/** Lowercase hex over the digest; the original ID is never part of the output. */
+function toLowerHex(bytes: Uint8Array): string {
+	let out = "";
+	for (const byte of bytes) out += HEX_DIGITS[byte >>> 4]! + HEX_DIGITS[byte & 0x0f]!;
+	return out;
+}
+
+function deriveRemappedId(
+	namespace: RemappedIdNamespace,
+	artifactIdentity: ArtifactIdentity,
+	originalID: string,
+): string {
+	const validatedNamespace = validateNamespace(namespace);
+	const validatedIdentity = validateArtifactIdentity(artifactIdentity);
+	const validatedOriginalId = validateOriginalId(originalID);
+	const digest = sodium.crypto_generichash(
+		HASH_BYTES,
+		buildDerivationInput(validatedNamespace, validatedIdentity, validatedOriginalId),
+		null,
+	);
+	if (!(digest instanceof Uint8Array) || digest.length !== HASH_BYTES) {
+		throw new RemappedIdError("derivation-failure", "BLAKE2b-256 produced an unexpected digest size");
+	}
+	return OUTPUT_PREFIX[validatedNamespace] + toLowerHex(digest);
+}
+
+/**
+ * Awaits/validates pinned sodium readiness (including `crypto_generichash`)
+ * and returns the synchronous provisional deriver. Fails closed on an
+ * unsupported runtime; there is no fallback deriver.
+ */
+export async function createRemappedIdDeriver(): Promise<RemappedIdDeriver> {
+	await requireSupportedSodiumRuntime();
+	return {
+		derive(namespace, artifactIdentity, originalID) {
+			return deriveRemappedId(namespace, artifactIdentity, originalID);
+		},
+	};
+}

package/src/core/restore/index.ts

@@ -0,0 +1,24 @@
+/**
+ * SessionPort V1 restore lane (Phase 3).
+ *
+ * Pure restore preflight/planning plus the provisional per-artifact remapped-ID
+ * derivation (O-22). `planRestore` snapshots and validates the checkpoint
+ * payload and local destination, applies the owner-approved canonical-duplicate
+ * and reference-remap policy (O-04/O-05), rederives every message ID of every
+ * session planned for import (owner clarification 2026-10-10), detects ID
+ * collisions and dangling references, and returns a deterministic
+ * parent-before-child import order. It performs no host call, file IO, LLM
+ * call, or import; broader partial-import retry/reporting semantics remain OPEN
+ * (O-06), and derived-ID runtime validation remains OPEN (OQ-24).
+ */
+export { planRestore, RestorePlanError } from "./planner.ts";
+export type {
+	PlanRestoreInput,
+	RestoreClassification,
+	RestorePlan,
+	RestorePlanEntry,
+	RestorePlanErrorCode,
+	RestoreSkipReason,
+} from "./planner.ts";
+export { createRemappedIdDeriver, RemappedIdError } from "./identity.ts";
+export type { RemappedIdDeriver, RemappedIdErrorCode, RemappedIdNamespace } from "./identity.ts";