@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/install-policy-observation.d.ts

@@ -0,0 +1,71 @@
+import { type InstallPolicy as InstallPolicyValue } from '../schema.js';
+import { ENVIRONMENT_CODES, type CheckoutId, type SourceProvenance } from './contract.js';
+declare const OWNER = "install-policy-lockfile-observation";
+interface FileIdentity {
+    readonly dev: string;
+    readonly ino: string;
+    readonly mode: string;
+    readonly nlink: string;
+    readonly size: string;
+    readonly mtimeNs: string;
+    readonly ctimeNs: string;
+}
+interface AncestorIdentity {
+    readonly canonicalPath: string;
+    readonly identity: FileIdentity;
+}
+interface AvailableLockfile {
+    readonly state: 'available';
+    readonly relativePath: string;
+    readonly canonicalPath: string;
+    readonly identity: FileIdentity;
+    readonly ancestors: readonly AncestorIdentity[];
+}
+interface MissingLockfile {
+    readonly state: 'missing';
+    readonly relativePath: string;
+    readonly ancestors: readonly AncestorIdentity[];
+}
+type ObservedLockfile = AvailableLockfile | MissingLockfile;
+interface ObservationBinding {
+    readonly source: SourceProvenance;
+    readonly siblingIndex: number;
+    readonly siblingSlug: string;
+    readonly checkoutRoot: string;
+    readonly checkoutId: CheckoutId;
+    readonly rootIdentity: FileIdentity;
+    readonly catalogSha256: string;
+    readonly lockfiles: readonly ObservedLockfile[];
+    readonly observedAt: string;
+    readonly validThrough: string;
+}
+export type InstallPolicyLockfileObservation = ({
+    readonly state: 'available';
+    readonly producer: typeof OWNER;
+} & ObservationBinding) | {
+    readonly state: 'unavailable' | 'failed';
+    readonly producer: typeof OWNER;
+    readonly code: typeof ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_UNAVAILABLE | typeof ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_INVALID;
+    readonly reason: string;
+};
+export interface InstallPolicyObservationContext {
+    readonly source: SourceProvenance;
+    readonly siblingIndex: number;
+    readonly siblingSlug: string;
+    readonly checkoutRoot: string;
+    readonly checkoutId: CheckoutId;
+    readonly policies: readonly InstallPolicyValue[];
+    readonly evaluatedAt: number;
+}
+export interface ConsumedInstallPolicyObservation extends ObservationBinding {
+}
+declare const installPolicyProjectionBrand: unique symbol;
+export interface InstallPolicyProjection {
+    readonly [installPolicyProjectionBrand]: true;
+}
+type SynchronousResult<T> = T extends PromiseLike<unknown> ? never : T;
+export declare function observeInstallPolicyLockfiles(input: unknown): Promise<InstallPolicyLockfileObservation>;
+export declare function withInstallPolicyProjection<T>(observation: unknown, expected: InstallPolicyObservationContext, use: (projection: InstallPolicyProjection) => SynchronousResult<T>): Promise<SynchronousResult<T> | undefined>;
+export declare function consumeInstallPolicyProjection(projection: InstallPolicyProjection): ConsumedInstallPolicyObservation | undefined;
+export declare function matchesInstallPolicyCatalog(observation: ConsumedInstallPolicyObservation, policies: readonly InstallPolicyValue[]): boolean;
+export {};

package/dist/environment/install-policy-observation.js

@@ -0,0 +1,284 @@
+import { createHash } from 'node:crypto';
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, normalize, relative, sep } from 'node:path';
+import { InstallPolicy } from '../schema.js';
+import { hasErrorCode, RefusalError, ENVIRONMENT_CODES, errorCause, isCanonicalTimestamp, snapshotJson, } from './contract.js';
+import { checkoutId as deriveCheckoutId } from './identity.js';
+const OWNER = 'install-policy-lockfile-observation';
+const CHECKOUT_ID = /^checkout:[a-f0-9]{64}$/;
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const MAX_VALIDITY_MS = 60_000;
+const issuedObservations = new WeakMap();
+const issuedProjections = new WeakMap();
+function isPromiseLike(value) {
+    if ((typeof value !== 'object' || value === null) && typeof value !== 'function')
+        return false;
+    try {
+        return typeof Reflect.get(value, 'then') === 'function';
+    }
+    catch { // A throwing getter on caller-supplied data is treated as promise-like, which the caller refuses.
+        return true;
+    }
+}
+function confined(root, candidate) {
+    const fromRoot = relative(root, candidate);
+    return fromRoot === '' || (fromRoot !== '..' && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot));
+}
+function identity(stat) {
+    return {
+        dev: stat.dev.toString(),
+        ino: stat.ino.toString(),
+        mode: stat.mode.toString(),
+        nlink: stat.nlink.toString(),
+        size: stat.size.toString(),
+        mtimeNs: stat.mtimeNs.toString(),
+        ctimeNs: stat.ctimeNs.toString(),
+    };
+}
+function sameIdentity(left, right) {
+    return Object.keys(left).every((key) => left[key] === right[key]);
+}
+function sameSource(left, right) {
+    return left.path === right.path && left.byteLength === right.byteLength && left.sha256 === right.sha256;
+}
+function validSource(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const source = value;
+    return typeof source.path === 'string' && !source.path.includes('\0')
+        && isAbsolute(source.path) && normalize(source.path) === source.path
+        && Number.isSafeInteger(source.byteLength) && source.byteLength >= 0
+        && typeof source.sha256 === 'string' && /^[a-f0-9]{64}$/.test(source.sha256);
+}
+function validRelativePath(path) {
+    return path.length > 0 && !/[\x00-\x1f\x7f]/.test(path) && !path.includes('\\') && !isAbsolute(path)
+        && !/^[A-Za-z][A-Za-z0-9+.-]*:/.test(path)
+        && path.split('/').every((part) => part.length > 0 && part !== '.' && part !== '..');
+}
+function snapshotPolicies(value) {
+    const snapshot = snapshotJson(value);
+    if (!Array.isArray(snapshot) || snapshot.length > 4_096)
+        return undefined;
+    const parsed = snapshot.map((row) => InstallPolicy.safeParse(row));
+    if (parsed.some((row) => !row.success))
+        return undefined;
+    const policies = parsed.map((row) => row.data);
+    const selectors = policies.map(({ toolchain, lockfile }) => `${toolchain}\0${lockfile}`);
+    return new Set(selectors).size === selectors.length
+        ? policies
+        : undefined;
+}
+function catalogSha256(policies) {
+    const rows = policies.map((policy) => JSON.stringify(policy)).sort();
+    return createHash('sha256').update(JSON.stringify(rows)).digest('hex');
+}
+async function stableRoot(path) {
+    try {
+        const before = await lstat(path, { bigint: true });
+        if (!before.isDirectory() || before.isSymbolicLink())
+            return { reason: 'it is not a plain directory' };
+        const canonicalPath = await realpath(path);
+        const after = await lstat(canonicalPath, { bigint: true });
+        const beforeIdentity = identity(before);
+        const afterIdentity = identity(after);
+        return canonicalPath === path && after.isDirectory() && !after.isSymbolicLink()
+            && sameIdentity(beforeIdentity, afterIdentity)
+            ? { canonicalPath, identity: afterIdentity }
+            : { reason: 'it is not canonical or changed while it was read' };
+    }
+    catch (error) {
+        return { reason: errorCause(error) };
+    }
+}
+async function inspectLockfile(root, relativePath) {
+    if (!validRelativePath(relativePath))
+        return 'invalid';
+    const ancestors = [];
+    const parts = relativePath.split('/');
+    let current = root;
+    for (let index = 0; index < parts.length; index += 1) {
+        current = join(current, parts[index]);
+        if (!confined(root, current))
+            return 'invalid';
+        try {
+            const before = await lstat(current, { bigint: true });
+            if (before.isSymbolicLink())
+                return 'invalid';
+            const canonicalPath = await realpath(current);
+            const after = await lstat(canonicalPath, { bigint: true });
+            const beforeIdentity = identity(before);
+            const afterIdentity = identity(after);
+            if (!confined(root, canonicalPath) || canonicalPath !== current
+                || after.isSymbolicLink() || !sameIdentity(beforeIdentity, afterIdentity))
+                return 'invalid';
+            if (index < parts.length - 1) {
+                if (!after.isDirectory())
+                    return 'invalid';
+                ancestors.push({ canonicalPath, identity: afterIdentity });
+                continue;
+            }
+            if (!after.isFile() || after.nlink !== 1n)
+                return 'invalid';
+            return {
+                state: 'available',
+                relativePath,
+                canonicalPath,
+                identity: afterIdentity,
+                ancestors,
+            };
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'ENOENT'))
+                return 'invalid';
+            return {
+                state: 'missing',
+                relativePath,
+                ancestors,
+            };
+        }
+    }
+    return 'invalid';
+}
+function sameObservation(left, right) {
+    if (left.state !== right.state || left.relativePath !== right.relativePath
+        || left.ancestors.length !== right.ancestors.length)
+        return false;
+    for (let index = 0; index < left.ancestors.length; index += 1) {
+        const leftAncestor = left.ancestors[index];
+        const rightAncestor = right.ancestors[index];
+        if (leftAncestor.canonicalPath !== rightAncestor.canonicalPath
+            || !sameIdentity(leftAncestor.identity, rightAncestor.identity))
+            return false;
+    }
+    return left.state === 'missing' || (right.state === 'available'
+        && left.canonicalPath === right.canonicalPath && sameIdentity(left.identity, right.identity));
+}
+function failure(state, reason) {
+    return {
+        state,
+        producer: OWNER,
+        code: state === 'unavailable'
+            ? ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_UNAVAILABLE
+            : ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_INVALID,
+        reason,
+    };
+}
+export async function observeInstallPolicyLockfiles(input) {
+    const snapshot = snapshotJson(input);
+    if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+        return failure('failed', 'install policy observation input is malformed');
+    }
+    const value = snapshot;
+    const expectedKeys = ['checkoutId', 'checkoutRoot', 'observedAt', 'policies', 'siblingIndex', 'siblingSlug', 'source'];
+    const policies = snapshotPolicies(value.policies);
+    if (Object.keys(value).sort().join('\0') !== expectedKeys.join('\0')
+        || !validSource(value.source)
+        || !Number.isSafeInteger(value.siblingIndex) || value.siblingIndex < 0
+        || typeof value.siblingSlug !== 'string' || !SLUG.test(value.siblingSlug)
+        || typeof value.checkoutRoot !== 'string' || !isAbsolute(value.checkoutRoot)
+        || normalize(value.checkoutRoot) !== value.checkoutRoot
+        || typeof value.checkoutId !== 'string' || !CHECKOUT_ID.test(value.checkoutId)
+        || !policies || !isCanonicalTimestamp(value.observedAt)) {
+        return failure('failed', 'install policy observation input is malformed');
+    }
+    const issuedAt = Date.now();
+    const observedAt = Date.parse(value.observedAt);
+    if (observedAt > issuedAt || issuedAt - observedAt > MAX_VALIDITY_MS) {
+        return failure('failed', 'install policy observation time is outside the freshness window');
+    }
+    const root = await stableRoot(value.checkoutRoot);
+    if ('reason' in root)
+        return failure('unavailable', `checkout root is unavailable: ${root.reason}`);
+    if (deriveCheckoutId({ checkoutPath: root.canonicalPath }) !== value.checkoutId) {
+        return failure('failed', 'checkout root does not match its declared identity');
+    }
+    const rows = [];
+    const lockfiles = [...new Set(policies.map((policy) => policy.lockfile))].sort();
+    for (const relativePath of lockfiles) {
+        const observed = await inspectLockfile(root.canonicalPath, relativePath);
+        if (observed === 'invalid')
+            return failure('failed', `lockfile path is invalid: ${relativePath}`);
+        rows.push(observed);
+    }
+    const binding = {
+        source: { ...value.source },
+        siblingIndex: value.siblingIndex,
+        siblingSlug: value.siblingSlug,
+        checkoutRoot: root.canonicalPath,
+        checkoutId: value.checkoutId,
+        rootIdentity: root.identity,
+        catalogSha256: catalogSha256(policies),
+        lockfiles: rows,
+        observedAt: value.observedAt,
+        validThrough: new Date(observedAt + MAX_VALIDITY_MS).toISOString(),
+    };
+    const observation = { state: 'available', producer: OWNER, ...binding };
+    issuedObservations.set(observation, binding);
+    return observation;
+}
+export async function withInstallPolicyProjection(observation, expected, use) {
+    if (observation === null || typeof observation !== 'object')
+        return undefined;
+    const binding = issuedObservations.get(observation);
+    issuedObservations.delete(observation);
+    const snapshot = snapshotJson(expected);
+    if (!binding || !snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot) || typeof use !== 'function')
+        return undefined;
+    const context = snapshot;
+    const expectedKeys = ['checkoutId', 'checkoutRoot', 'evaluatedAt', 'policies', 'siblingIndex', 'siblingSlug', 'source'];
+    const policies = snapshotPolicies(context.policies);
+    const trustedCurrentTime = Date.now();
+    if (Object.keys(context).sort().join('\0') !== expectedKeys.join('\0')
+        || !validSource(context.source) || !policies
+        || !Number.isSafeInteger(context.siblingIndex) || !Number.isSafeInteger(context.evaluatedAt)
+        || binding.siblingIndex !== context.siblingIndex || binding.siblingSlug !== context.siblingSlug
+        || binding.checkoutRoot !== context.checkoutRoot || binding.checkoutId !== context.checkoutId
+        || !sameSource(binding.source, context.source)
+        || binding.catalogSha256 !== catalogSha256(policies)
+        || context.evaluatedAt !== Date.parse(binding.observedAt)
+        || context.evaluatedAt > trustedCurrentTime
+        || trustedCurrentTime > Date.parse(binding.validThrough))
+        return undefined;
+    const root = await stableRoot(binding.checkoutRoot);
+    if ('reason' in root || !sameIdentity(root.identity, binding.rootIdentity)
+        || deriveCheckoutId({ checkoutPath: root.canonicalPath }) !== binding.checkoutId)
+        return undefined;
+    for (const lockfile of binding.lockfiles) {
+        const current = await inspectLockfile(binding.checkoutRoot, lockfile.relativePath);
+        if (current === 'invalid' || !sameObservation(lockfile, current))
+            return undefined;
+    }
+    const projection = {};
+    issuedProjections.set(projection, binding);
+    try {
+        const result = use(projection);
+        if (isPromiseLike(result)) {
+            // The caller receives the contract error immediately; observing the invalid result prevents
+            // a later rejection from becoming detached process state.
+            void Promise.resolve(result).catch(() => undefined);
+            throw new RefusalError('install policy projection callback must be synchronous');
+        }
+        return result;
+    }
+    finally {
+        issuedProjections.delete(projection);
+    }
+}
+export function consumeInstallPolicyProjection(projection) {
+    try {
+        if (projection === null || typeof projection !== 'object')
+            return undefined;
+        const binding = issuedProjections.get(projection);
+        if (!binding)
+            return undefined;
+        issuedProjections.delete(projection);
+        return binding;
+    }
+    catch { // A throwing accessor or proxy trap on the projection makes it malformed; the caller refuses it.
+        return undefined;
+    }
+}
+export function matchesInstallPolicyCatalog(observation, policies) {
+    const snapshot = snapshotPolicies(policies);
+    return snapshot !== undefined && observation.catalogSha256 === catalogSha256(snapshot);
+}

package/dist/environment/install-policy.d.ts

@@ -0,0 +1,48 @@
+import { type InstallPolicy as InstallPolicyValue, type Sibling as SiblingValue } from '../schema.js';
+import { ENVIRONMENT_CODES, type CheckoutId, type SourceProvenance } from './contract.js';
+import { type InstallPolicyProjection } from './install-policy-observation.js';
+export declare const GUARD_PROJECT_COMMAND_RENDERED_BYTES = 32768;
+export declare function renderGuardProjectCommand(argv: readonly string[]): {
+    readonly kind: 'complete';
+    readonly command: string;
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+export interface InstallPolicyResolutionInput {
+    readonly source: SourceProvenance;
+    readonly policies: readonly InstallPolicyValue[];
+    readonly siblingIndex: number;
+    readonly sibling: SiblingValue;
+    readonly checkoutRoot?: string;
+    readonly checkoutId?: CheckoutId;
+    readonly projection?: InstallPolicyProjection;
+}
+export interface ResolvedInstallPolicyBinding {
+    readonly source: SourceProvenance;
+    readonly siblingIndex: number;
+    readonly diagnostics: Readonly<{
+        readonly catalogIndex: number;
+    }>;
+    readonly siblingSlug: string;
+    readonly checkoutRoot: string;
+    readonly checkoutId: CheckoutId;
+    readonly policy: InstallPolicyValue;
+}
+export type InstallPolicyResolution = {
+    readonly kind: 'complete';
+    readonly bindings: readonly ResolvedInstallPolicyBinding[];
+} | {
+    readonly kind: 'unavailable';
+    readonly code: typeof ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_UNAVAILABLE;
+    readonly siblingIndex: number;
+    readonly siblingSlug: string;
+    readonly reason: string;
+} | {
+    readonly kind: 'refusal';
+    readonly code: typeof ENVIRONMENT_CODES.INSTALL_POLICY_MISSING | typeof ENVIRONMENT_CODES.INSTALL_POLICY_AMBIGUOUS;
+    readonly siblingIndex: number;
+    readonly siblingSlug: string;
+    readonly candidates: readonly string[];
+};
+export declare function resolveInstallPolicies(root: InstallPolicyResolutionInput): InstallPolicyResolution;

package/dist/environment/install-policy.js

@@ -0,0 +1,96 @@
+import { isAbsolute, normalize } from 'node:path';
+import { GuardCommandArgv, InstallPolicy, Sibling } from '../schema.js';
+import { ENVIRONMENT_CODES, snapshotJson } from './contract.js';
+import { consumeInstallPolicyProjection, matchesInstallPolicyCatalog, } from './install-policy-observation.js';
+export const GUARD_PROJECT_COMMAND_RENDERED_BYTES = 32_768;
+export function renderGuardProjectCommand(argv) {
+    const parsed = GuardCommandArgv.safeParse(snapshotJson(argv));
+    if (!parsed.success)
+        return { kind: 'unavailable', reason: 'project command argv exceeds the scalar or word bounds' };
+    const command = parsed.data.map(word => `'${word.replaceAll("'", "'\\''")}'`).join(' ');
+    return Buffer.byteLength(command) < GUARD_PROJECT_COMMAND_RENDERED_BYTES
+        ? { kind: 'complete', command }
+        : { kind: 'unavailable', reason: 'project command rendering exceeds the byte bound' };
+}
+function unavailable(siblingIndex, siblingSlug, reason) {
+    return {
+        kind: 'unavailable',
+        code: ENVIRONMENT_CODES.INSTALL_POLICY_OBSERVATION_UNAVAILABLE,
+        siblingIndex,
+        siblingSlug,
+        reason,
+    };
+}
+function sourceProvenance(source) {
+    return typeof source.path === 'string' && !source.path.includes('\0')
+        && isAbsolute(source.path) && normalize(source.path) === source.path
+        && Number.isSafeInteger(source.byteLength) && source.byteLength >= 0
+        && typeof source.sha256 === 'string' && /^[a-f0-9]{64}$/.test(source.sha256)
+        ? { path: source.path, byteLength: source.byteLength, sha256: source.sha256 }
+        : undefined;
+}
+export function resolveInstallPolicies(root) {
+    const source = sourceProvenance(root.source);
+    const siblingIndex = root.siblingIndex;
+    const sibling = Sibling.safeParse(root.sibling);
+    if (!source || !Array.isArray(root.policies) || !Number.isSafeInteger(siblingIndex) || siblingIndex < 0 || !sibling.success) {
+        return unavailable(Number.isSafeInteger(siblingIndex) ? siblingIndex : 0, sibling.success ? sibling.data.slug : 'configuration', 'install policy resolution input is invalid');
+    }
+    const policies = root.policies.map((policy) => InstallPolicy.safeParse(policy));
+    if (policies.some((policy) => !policy.success)) {
+        return unavailable(siblingIndex, sibling.data.slug, 'install policy catalog is invalid');
+    }
+    const catalog = policies.map((policy) => policy.data);
+    const selectors = catalog.map(({ toolchain, lockfile }) => `${toolchain}\0${lockfile}`);
+    if (new Set(selectors).size !== selectors.length) {
+        return unavailable(siblingIndex, sibling.data.slug, 'install policy catalog is invalid');
+    }
+    if (sibling.data.toolchain === 'none')
+        return { kind: 'complete', bindings: [] };
+    if (typeof root.checkoutRoot !== 'string' || typeof root.checkoutId !== 'string') {
+        return unavailable(siblingIndex, sibling.data.slug, 'authenticated lockfile evidence is unavailable');
+    }
+    const observation = consumeInstallPolicyProjection(root.projection);
+    if (!observation)
+        return unavailable(siblingIndex, sibling.data.slug, 'authenticated lockfile evidence is unavailable');
+    if (!matchesInstallPolicyCatalog(observation, catalog)
+        || observation.siblingIndex !== siblingIndex || observation.siblingSlug !== sibling.data.slug
+        || observation.checkoutRoot !== root.checkoutRoot || observation.checkoutId !== root.checkoutId
+        || observation.source.path !== source.path || observation.source.byteLength !== source.byteLength
+        || observation.source.sha256 !== source.sha256) {
+        return unavailable(siblingIndex, sibling.data.slug, 'authenticated lockfile evidence does not match the sibling');
+    }
+    const present = new Set(observation.lockfiles
+        .filter((lockfile) => lockfile.state === 'available')
+        .map(({ relativePath }) => relativePath));
+    const matches = catalog.flatMap((candidate, catalogIndex) => candidate.toolchain === sibling.data.toolchain && present.has(candidate.lockfile)
+        ? [{ catalogIndex, policy: candidate }]
+        : []);
+    if (matches.length !== 1) {
+        const candidates = matches.map(({ policy }) => `${policy.toolchain}:${policy.lockfile}`).sort();
+        return {
+            kind: 'refusal',
+            code: matches.length === 0 ? ENVIRONMENT_CODES.INSTALL_POLICY_MISSING : ENVIRONMENT_CODES.INSTALL_POLICY_AMBIGUOUS,
+            siblingIndex,
+            siblingSlug: sibling.data.slug,
+            candidates,
+        };
+    }
+    const selected = matches[0];
+    for (const kind of ['build', 'test']) {
+        const argv = selected.policy[kind];
+        if (argv && renderGuardProjectCommand(argv).kind !== 'complete') {
+            return unavailable(siblingIndex, sibling.data.slug, `${kind} project command rendering exceeds the byte bound`);
+        }
+    }
+    const binding = {
+        source,
+        siblingIndex,
+        diagnostics: { catalogIndex: selected.catalogIndex },
+        siblingSlug: sibling.data.slug,
+        checkoutRoot: observation.checkoutRoot,
+        checkoutId: observation.checkoutId,
+        policy: selected.policy,
+    };
+    return { kind: 'complete', bindings: [binding] };
+}

package/dist/environment/instance.d.ts

@@ -0,0 +1,33 @@
+import type { CheckoutId, StackId } from './contract.js';
+export interface InstanceCandidate {
+    readonly stackId: StackId;
+    readonly checkoutId: CheckoutId;
+}
+export interface ResolveInstanceInput {
+    readonly explicit?: InstanceCandidate;
+    readonly served: InstanceCandidate;
+    readonly launcher: InstanceCandidate;
+    readonly mountedSet: readonly CheckoutId[];
+}
+export interface InstanceResolution extends InstanceCandidate {
+    readonly kind: 'attach' | 'isolate';
+    readonly source: 'explicit' | 'served' | 'launcher';
+}
+export interface SelectDestructiveInstanceInput {
+    readonly explicit?: InstanceCandidate;
+    readonly served?: InstanceCandidate;
+    readonly launcher?: InstanceCandidate;
+    readonly claimInventory: readonly InstanceCandidate[];
+}
+export type DestructiveInstanceSelection = Readonly<{
+    kind: 'selected';
+    source: 'explicit' | 'served' | 'launcher';
+    stackId: StackId;
+    checkoutId: CheckoutId;
+}> | Readonly<{
+    kind: 'refusal';
+    reason: 'ambiguous' | 'identity-conflict' | 'identity-mismatch' | 'missing-authority';
+    candidates: readonly InstanceCandidate[];
+}>;
+export declare function selectDestructiveInstance(input: SelectDestructiveInstanceInput): DestructiveInstanceSelection;
+export declare function resolveInstance(input: ResolveInstanceInput): InstanceResolution;

package/dist/environment/instance.js

@@ -0,0 +1,122 @@
+import { RefusalError } from './contract.js';
+const STACK_ID = /^stack:[a-f0-9]{64}$/;
+const CHECKOUT_ID = /^checkout:[a-f0-9]{64}$/;
+function candidate(value, field, operation = 'resolveInstance') {
+    if (value === null
+        || typeof value !== 'object'
+        || typeof value.stackId !== 'string'
+        || !STACK_ID.test(value.stackId)
+        || typeof value.checkoutId !== 'string'
+        || !CHECKOUT_ID.test(value.checkoutId)) {
+        throw new RefusalError(`${operation}: ${field} candidate is malformed`);
+    }
+    return value;
+}
+function destructiveCandidate(value, field) {
+    if (value === null || typeof value !== 'object')
+        return candidate(value, field, 'selectDestructiveInstance');
+    const stackId = value.stackId;
+    const checkoutId = value.checkoutId;
+    return candidate({ stackId, checkoutId }, field, 'selectDestructiveInstance');
+}
+function candidateKey(value) {
+    return `${value.stackId}\0${value.checkoutId}`;
+}
+function canonicalCandidates(values) {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(candidateKey(value), value);
+    return Array.from(unique.values(), (value) => ({ ...value })).sort((left, right) => {
+        if (left.stackId !== right.stackId)
+            return left.stackId < right.stackId ? -1 : 1;
+        return left.checkoutId < right.checkoutId ? -1 : left.checkoutId === right.checkoutId ? 0 : 1;
+    });
+}
+function conflictingStackIds(values) {
+    const checkoutsByStack = new Map();
+    for (const value of values) {
+        const checkouts = checkoutsByStack.get(value.stackId) ?? new Set();
+        checkouts.add(value.checkoutId);
+        checkoutsByStack.set(value.stackId, checkouts);
+    }
+    return new Set(Array.from(checkoutsByStack)
+        .filter(([, checkouts]) => checkouts.size > 1)
+        .map(([stackId]) => stackId));
+}
+function destructiveRefusal(reason, candidates) {
+    return { kind: 'refusal', reason, candidates: canonicalCandidates(candidates) };
+}
+export function selectDestructiveInstance(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new RefusalError('selectDestructiveInstance: input is malformed');
+    }
+    const explicitValue = input.explicit;
+    const servedValue = input.served;
+    const launcherValue = input.launcher;
+    const inventoryValue = input.claimInventory;
+    const explicit = explicitValue === undefined ? undefined : destructiveCandidate(explicitValue, 'explicit');
+    const served = servedValue === undefined ? undefined : destructiveCandidate(servedValue, 'served');
+    const launcher = launcherValue === undefined ? undefined : destructiveCandidate(launcherValue, 'launcher');
+    if (!Array.isArray(inventoryValue)) {
+        throw new RefusalError('selectDestructiveInstance: claimInventory is malformed');
+    }
+    const inventory = canonicalCandidates(inventoryValue.map((value) => destructiveCandidate(value, 'claimInventory')));
+    const conflictingStacks = conflictingStackIds(inventory);
+    const inventoryKeys = new Set(inventory.map(candidateKey));
+    if (explicit !== undefined) {
+        if (conflictingStacks.has(explicit.stackId)) {
+            return destructiveRefusal('identity-conflict', inventory.filter((value) => value.stackId === explicit.stackId));
+        }
+        return inventoryKeys.has(candidateKey(explicit))
+            ? { kind: 'selected', source: 'explicit', ...explicit }
+            : destructiveRefusal('identity-mismatch', inventory);
+    }
+    const authorities = [
+        ...(served === undefined ? [] : [{ source: 'served', value: served }]),
+        ...(launcher === undefined ? [] : [{ source: 'launcher', value: launcher }]),
+    ];
+    if (authorities.length === 0)
+        return destructiveRefusal('missing-authority', inventory);
+    const authorityCandidates = canonicalCandidates(authorities.map(({ value }) => value));
+    const authorityConflict = conflictingStackIds(authorityCandidates);
+    if (authorityConflict.size > 0) {
+        return destructiveRefusal('identity-conflict', authorityCandidates.filter((value) => authorityConflict.has(value.stackId)));
+    }
+    const relevantStacks = new Set(authorityCandidates.map(({ stackId }) => stackId));
+    const relevantInventoryConflicts = new Set(Array.from(conflictingStacks).filter((stackId) => relevantStacks.has(stackId)));
+    if (relevantInventoryConflicts.size > 0) {
+        return destructiveRefusal('identity-conflict', inventory.filter((value) => relevantInventoryConflicts.has(value.stackId)));
+    }
+    const relevant = authorities.filter(({ value }) => inventoryKeys.has(candidateKey(value)));
+    const distinct = canonicalCandidates(relevant.map(({ value }) => value));
+    if (distinct.length === 0)
+        return destructiveRefusal('identity-mismatch', inventory);
+    if (distinct.length > 1)
+        return destructiveRefusal('ambiguous', distinct);
+    const selected = relevant[0];
+    return { kind: 'selected', source: selected.source, ...selected.value };
+}
+export function resolveInstance(input) {
+    if (input === null || typeof input !== 'object') {
+        throw new RefusalError('resolveInstance: input is malformed');
+    }
+    const served = candidate(input.served, 'served');
+    const launcher = candidate(input.launcher, 'launcher');
+    const explicit = input.explicit === undefined ? undefined : candidate(input.explicit, 'explicit');
+    if (!Array.isArray(input.mountedSet)
+        || input.mountedSet.some((value) => typeof value !== 'string' || !CHECKOUT_ID.test(value))) {
+        throw new RefusalError('resolveInstance: mountedSet contains a malformed checkout identity');
+    }
+    const mounted = new Set(input.mountedSet);
+    const selected = explicit === undefined
+        ? mounted.has(served.checkoutId)
+            ? { source: 'served', value: served }
+            : { source: 'launcher', value: launcher }
+        : { source: 'explicit', value: explicit };
+    return {
+        kind: mounted.has(selected.value.checkoutId) ? 'attach' : 'isolate',
+        source: selected.source,
+        stackId: selected.value.stackId,
+        checkoutId: selected.value.checkoutId,
+    };
+}

package/dist/environment/instruction-pointer.d.ts

@@ -0,0 +1,19 @@
+export declare const INSTRUCTION_POINTER_MARKERS: Readonly<{
+    begin: "<!-- cockpit:instruction-pointer:start -->";
+    end: "<!-- cockpit:instruction-pointer:end -->";
+}>;
+export type InstructionPointerResult = Readonly<{
+    kind: 'offered' | 'written' | 'unchanged';
+    path: string;
+    target: string;
+}> | Readonly<{
+    kind: 'refusal';
+    path: string;
+    reason: string;
+}>;
+/** Appends one bounded marked block; bytes outside that block always remain product-owned. */
+export declare function synchronizeInstructionPointer(input: Readonly<{
+    cockpitRoot: string;
+    siblingRoot: string;
+    write: boolean;
+}>): Promise<InstructionPointerResult>;