project-tiny-context-harness 0.8.16 → 0.8.17

package/dist/lib/long-task-design-feasibility-binding.js

@@ -0,0 +1,114 @@
+import { DESIGN_RESOURCE_FEASIBILITY_DECISION_SCHEMA, deriveDesignResourceFeasibilityConditionScopeSha256, parseDesignResourceFeasibilityDecisionProjections, } from "./design-resource-implementation-feasibility-source-decision.js";
+import { createV1ImplementationFeasibilityTargetModel, createV2ImplementationFeasibilityTargetModel, } from "./design-resource-implementation-feasibility-model.js";
+import { matchingFeasibilityBindingKeys, validateFeasibilityBindingOwnerRoots, } from "./long-task-design-feasibility-binding-owners.js";
+import { validateFeasibilityBlockers, validateSelectedPlannedOwnerClaims, validateTechnicalDecisionClaim, } from "./long-task-design-feasibility-source-closure.js";
+import { invalid } from "./long-task-design-resource-method-binding.js";
+export function validateLongTaskDesignFeasibilityBindings(contract, contractTarget, preflight, sourceItems, options = {}) {
+    const document = preflight.technical_feasibility_documents.find((item) => item.target_ref === contractTarget.target.key);
+    if (!document) {
+        if (!contractTarget.binding.component_binding_refs.length)
+            invalid("componentless_surface_requires_blocker_only_feasibility", contractTarget.target.key);
+        return {
+            consumed_component_binding_refs: [
+                ...contractTarget.binding.component_binding_refs,
+            ],
+        };
+    }
+    const model = feasibilityTargetModel(preflight, contractTarget.target.key);
+    const decisions = compiledDecisionSources(document, sourceItems);
+    const outcome = contract.outcomes.find((item) => item.key === contractTarget.outcome_key);
+    const bindingsByKey = new Map(outcome.technical.bindings.map((binding) => [binding.key, binding]));
+    const componentBindings = contractTarget.binding.component_binding_refs.map((bindingRef) => {
+        const binding = bindingsByKey.get(bindingRef);
+        if (!binding)
+            invalid("feasibility_component_binding_unknown", `${contractTarget.target.key}:${bindingRef}`);
+        return binding;
+    });
+    const routeBinding = bindingsByKey.get(contractTarget.binding.route_binding_ref);
+    if (!routeBinding)
+        invalid("feasibility_route_binding_unknown", `${contractTarget.target.key}:${contractTarget.binding.route_binding_ref}`);
+    const hasCandidateCells = document.component_family_cells.some((cell) => cell.feasible_realizations.length > 0);
+    const allCellsBlockerOnly = document.component_family_cells.length > 0 &&
+        document.component_family_cells.every((cell) => cell.feasible_realizations.length === 0 && cell.blocker_refs.length > 0);
+    if (!componentBindings.length && hasCandidateCells)
+        invalid("feasibility_component_binding_required", contractTarget.target.key);
+    if (!componentBindings.length && !allCellsBlockerOnly)
+        invalid("componentless_surface_requires_blocker_only_feasibility", contractTarget.target.key);
+    validateFeasibilityBindingOwnerRoots(document, componentBindings, routeBinding);
+    const consumedComponentBindings = new Set();
+    for (const cell of document.component_family_cells) {
+        const blockerOnly = cell.feasible_realizations.length === 0 && cell.blocker_refs.length > 0;
+        if (blockerOnly)
+            continue;
+        const matching = cell.feasible_realizations
+            .map((realization) => ({
+            realization,
+            bindingKeys: matchingFeasibilityBindingKeys(realization, componentBindings),
+        }))
+            .filter((candidate) => candidate.bindingKeys.size > 0);
+        const required = cell.required_realization.realization_ref;
+        if (required !== null &&
+            (matching.length !== 1 || matching[0].realization.key !== required))
+            invalid("feasibility_required_realization_binding_mismatch", `${cell.key}:${required}:${matching.map((item) => item.realization.key).join(",")}`);
+        if (required === null && matching.length === 0)
+            invalid("feasibility_realization_binding_missing", cell.key);
+        if (required === null && matching.length > 1)
+            invalid("feasibility_realization_binding_ambiguous", `${cell.key}:${matching.map((item) => item.realization.key).join(",")}`);
+        const selected = matching.length === 1 ? matching[0] : null;
+        if (selected)
+            for (const bindingKey of selected.bindingKeys)
+                consumedComponentBindings.add(bindingKey);
+        if (required !== null)
+            validateTechnicalDecisionClaim(contract, contractTarget, decisions, cell.required_realization.technical_authority_source_refs, {
+                schema_version: DESIGN_RESOURCE_FEASIBILITY_DECISION_SCHEMA,
+                mode: "required_realization",
+                target_ref: cell.target_ref,
+                component_family_ref: cell.component_family_ref,
+                condition_scope_sha256: deriveDesignResourceFeasibilityConditionScopeSha256(document, model, cell.condition_profile_ref),
+                realization_ref: required,
+            }, `required_realization:${cell.key}`);
+        if (selected)
+            validateSelectedPlannedOwnerClaims(contract, contractTarget, document, model, decisions, selected.realization, componentBindings, cell);
+    }
+    if (!options.deferComponentBindingAttribution)
+        validateComponentBindingAttribution(contractTarget, consumedComponentBindings);
+    validateFeasibilityBlockers(contract, contractTarget, document, model, decisions);
+    return {
+        consumed_component_binding_refs: [...consumedComponentBindings].sort(),
+    };
+}
+function validateComponentBindingAttribution(contractTarget, consumedComponentBindings) {
+    for (const bindingRef of contractTarget.binding.component_binding_refs)
+        if (!consumedComponentBindings.has(bindingRef))
+            invalid("feasibility_component_binding_unattributed", `${contractTarget.target.key}:${bindingRef}`);
+}
+function feasibilityTargetModel(preflight, targetRef) {
+    if ("preflight_schema_version" in preflight) {
+        const target = preflight.handoff.targets.find((candidate) => candidate.key === targetRef);
+        return createV2ImplementationFeasibilityTargetModel(target, preflight.manifest);
+    }
+    const target = preflight.handoff.targets.find((candidate) => candidate.key === targetRef);
+    return createV1ImplementationFeasibilityTargetModel(preflight.handoff, target);
+}
+function compiledDecisionSources(document, sourceItems) {
+    const index = new Map();
+    for (const record of document.source_records) {
+        if (record.locator.kind !== "source_item")
+            continue;
+        const item = sourceItems.find((candidate) => candidate.source_path === record.path &&
+            candidate.key === record.locator.value);
+        if (!item)
+            invalid("feasibility_source_item_not_declared", `${record.key}:${record.path}#${record.locator.value}`);
+        if (item.text_sha256 !== record.locator.text_sha256)
+            invalid("feasibility_source_item_digest_mismatch", `${record.key}:${record.locator.text_sha256}:${item.text_sha256}`);
+        index.set(record.key, {
+            source_record_ref: record.key,
+            source_path: record.path,
+            source_item_key: item.key,
+            source_item_kind: item.kind,
+            text_sha256: item.text_sha256,
+            projections: parseDesignResourceFeasibilityDecisionProjections(record.path, item.key, item.normalized_text),
+        });
+    }
+    return index;
+}

package/dist/lib/long-task-design-feasibility-source-closure.d.ts

@@ -0,0 +1,11 @@
+import type { DesignResourceImplementationFeasibilityTargetModel } from "./design-resource-implementation-feasibility-model.js";
+import { type DesignResourceFeasibilityDecisionProjection, type DesignResourceFeasibilityDecisionSourceIndex } from "./design-resource-implementation-feasibility-source-decision.js";
+import type { DesignResourceImplementationFeasibilityV1 } from "./design-resource-implementation-feasibility-types.js";
+import type { DeliveryBindingV2, DeliveryContractV2 } from "./long-task-delivery-types.js";
+import type { ContractDesignTarget } from "./long-task-design-resource-handoff.js";
+type FeasibilityCell = DesignResourceImplementationFeasibilityV1["component_family_cells"][number];
+type FeasibleRealization = FeasibilityCell["feasible_realizations"][number];
+export declare function validateSelectedPlannedOwnerClaims(contract: DeliveryContractV2, contractTarget: ContractDesignTarget, document: DesignResourceImplementationFeasibilityV1, model: DesignResourceImplementationFeasibilityTargetModel, decisions: DesignResourceFeasibilityDecisionSourceIndex, realization: FeasibleRealization, bindings: DeliveryBindingV2[], cell: FeasibilityCell): void;
+export declare function validateTechnicalDecisionClaim(contract: DeliveryContractV2, contractTarget: ContractDesignTarget, decisions: DesignResourceFeasibilityDecisionSourceIndex, sourceRefs: string[], expectation: DesignResourceFeasibilityDecisionProjection, label: string): void;
+export declare function validateFeasibilityBlockers(contract: DeliveryContractV2, contractTarget: ContractDesignTarget, document: DesignResourceImplementationFeasibilityV1, model: DesignResourceImplementationFeasibilityTargetModel, decisions: DesignResourceFeasibilityDecisionSourceIndex): void;
+export {};

package/dist/lib/long-task-design-feasibility-source-closure.js

@@ -0,0 +1,78 @@
+import { DESIGN_RESOURCE_FEASIBILITY_DECISION_SCHEMA, deriveDesignResourceFeasibilityConditionScopeSha256, requireExactFeasibilityDecisionProjection, } from "./design-resource-implementation-feasibility-source-decision.js";
+import { invalid } from "./long-task-design-resource-method-binding.js";
+export function validateSelectedPlannedOwnerClaims(contract, contractTarget, document, model, decisions, realization, bindings, cell) {
+    for (const owner of realization.owner_candidates) {
+        if (owner.kind !== "planned_logical_owner")
+            continue;
+        if (!bindings.some((binding) => binding.existence === "planned" &&
+            (binding.key === owner.locator || binding.target === owner.locator)))
+            continue;
+        validateTechnicalDecisionClaim(contract, contractTarget, decisions, owner.authorization_source_refs, {
+            schema_version: DESIGN_RESOURCE_FEASIBILITY_DECISION_SCHEMA,
+            mode: "planned_owner_authorization",
+            target_ref: cell.target_ref,
+            component_family_ref: cell.component_family_ref,
+            condition_scope_sha256: deriveDesignResourceFeasibilityConditionScopeSha256(document, model, cell.condition_profile_ref),
+            owner_locator: owner.locator,
+        }, `planned_owner:${cell.key}:${owner.locator}`);
+    }
+}
+export function validateTechnicalDecisionClaim(contract, contractTarget, decisions, sourceRefs, expectation, label) {
+    const source = requireDecisionSource(sourceRefs, decisions, expectation, label, ["technical_obligation"], true);
+    const claim = exactSourceClaim(contract, source, label);
+    const validOutcomeClaim = claim.disposition.type === "claim" &&
+        claim.disposition.refs.some((ref) => ref.startsWith(`${contractTarget.outcome_key}.`));
+    if (!validOutcomeClaim && claim.disposition.type !== "global_constraint")
+        invalid("feasibility_technical_decision_claim_disposition_invalid", `${label}:${claim.key}:${claim.disposition.type}`);
+}
+export function validateFeasibilityBlockers(contract, contractTarget, document, model, decisions) {
+    for (const blocker of document.blockers) {
+        const source = requireDecisionSource(blocker.source_record_refs, decisions, {
+            schema_version: DESIGN_RESOURCE_FEASIBILITY_DECISION_SCHEMA,
+            mode: "feasibility_blocker",
+            target_ref: blocker.target_ref,
+            component_family_ref: blocker.component_family_ref,
+            condition_scope_sha256: deriveDesignResourceFeasibilityConditionScopeSha256(document, model, blocker.condition_profile_ref),
+            blocker_ref: blocker.key,
+            substrate_observation_refs: blocker.substrate_observation_refs,
+        }, `blocker:${blocker.key}`, ["decision", "external_confirmation"], false);
+        const claim = exactSourceClaim(contract, source, `blocker:${blocker.key}`);
+        if (source.source_item_kind === "decision") {
+            if (claim.disposition.type !== "decision_required")
+                invalid("feasibility_blocker_decision_required", `${blocker.key}:${claim.key}:${claim.disposition.type}`);
+            continue;
+        }
+        if (claim.disposition.type !== "external_confirmation")
+            invalid("feasibility_blocker_external_confirmation_required", `${blocker.key}:${claim.key}:${claim.disposition.type}`);
+        const impactedTargetClaims = new Set(contractTarget.target.claim_refs.map((claimRef) => `${contractTarget.outcome_key}.${claimRef}`));
+        for (const confirmationRef of claim.disposition.refs) {
+            const confirmation = contract.global.acceptance.external_confirmations.find((candidate) => candidate.key === confirmationRef);
+            if (!confirmation)
+                invalid("feasibility_blocker_confirmation_unknown", `${blocker.key}:${confirmationRef}`);
+            if (!confirmation.blocks_target)
+                invalid("feasibility_blocker_confirmation_not_blocking", `${blocker.key}:${confirmationRef}`);
+            if (!confirmation.impact_claims.some((claimRef) => impactedTargetClaims.has(claimRef)))
+                invalid("feasibility_blocker_confirmation_target_claim_missing", `${blocker.key}:${confirmationRef}`);
+        }
+    }
+}
+function requireDecisionSource(sourceRefs, decisions, expectation, label, allowedItemKinds, allReferencesMustBeSourceItems) {
+    try {
+        return requireExactFeasibilityDecisionProjection(sourceRefs, decisions, expectation, label, { allReferencesMustBeSourceItems, allowedItemKinds });
+    }
+    catch (error) {
+        invalid("feasibility_source_decision_invalid", `${label}:${message(error)}`);
+    }
+}
+function exactSourceClaim(contract, source, label) {
+    if (!contract.task.source_paths.includes(source.source_path))
+        invalid("feasibility_authority_source_not_declared", `${label}:${source.source_path}`);
+    const sourceRef = `${source.source_path}#${source.source_item_key}`;
+    const matching = contract.source_claims.filter((claim) => claim.source_ref === sourceRef);
+    if (matching.length !== 1)
+        invalid("feasibility_authority_claim_count", `${label}:${sourceRef}:${matching.length}`);
+    return matching[0];
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/long-task-design-resource-handoff.d.ts

@@ -1,6 +1,6 @@
 import type { DesignResourceHandoffPreflightV1, DesignResourceHandoffTargetV1 } from "./design-resource-handoff-types.js";
 import type { DesignResourceHandoffPreflightV2 } from "./design-resource-symbolic-fact-types.js";
-import type { DeliveryContractV2 } from "./long-task-delivery-types.js";
+import type { CompiledSourceItemV2, DeliveryContractV2 } from "./long-task-delivery-types.js";
 export interface ContractDesignTarget {
     outcome_key: string;
     binding: DeliveryContractV2["outcomes"][number]["product"]["surface_bindings"][number];
@@ -14,5 +14,5 @@ export interface LongTaskDesignHandoffConsumer {
     consume(preflight: DesignResourceHandoffPreflightV1 | DesignResourceHandoffPreflightV2): void;
     finish(): void;
 }
-export declare function validateLongTaskDesignResourceHandoffs(contract: DeliveryContractV2, repository: string): Promise<void>;
-export declare function createLongTaskDesignHandoffConsumer(contract: DeliveryContractV2): LongTaskDesignHandoffConsumer;
+export declare function validateLongTaskDesignResourceHandoffs(contract: DeliveryContractV2, repository: string, sourceItems: CompiledSourceItemV2[]): Promise<void>;
+export declare function createLongTaskDesignHandoffConsumer(contract: DeliveryContractV2, sourceItems?: CompiledSourceItemV2[]): LongTaskDesignHandoffConsumer;

package/dist/lib/long-task-design-resource-handoff.js

@@ -6,8 +6,9 @@ import { preflightParsedDesignResourceHandoffAny } from "./design-resource-hando
 import { assertSameSet, designSourceItemClaims, invalid, validateTargetIdentity, validateSymbolicTargetIdentity, validateSymbolicVerificationMethodBindings, validateVerificationMethodBindings, } from "./long-task-design-resource-method-binding.js";
 import { validateLongTaskDesignTargetCapabilities } from "./long-task-design-target-capabilities.js";
 import { assertProtectedRepositoryFile } from "./long-task-protected-files.js";
-export async function validateLongTaskDesignResourceHandoffs(contract, repository) {
-    const consumer = createLongTaskDesignHandoffConsumer(contract);
+import { validateLongTaskDesignFeasibilityBindings } from "./long-task-design-feasibility-binding.js";
+export async function validateLongTaskDesignResourceHandoffs(contract, repository, sourceItems) {
+    const consumer = createLongTaskDesignHandoffConsumer(contract, sourceItems);
     for (const sourcePath of contract.task.source_paths) {
         if (!sourcePath.toLowerCase().endsWith(".md"))
             continue;
@@ -19,7 +20,7 @@ export async function validateLongTaskDesignResourceHandoffs(contract, repositor
     }
     consumer.finish();
 }
-export function createLongTaskDesignHandoffConsumer(contract) {
+export function createLongTaskDesignHandoffConsumer(contract, sourceItems = []) {
     const contractTargets = contract.outcomes.flatMap((outcome) => outcome.product.surface_bindings.flatMap((binding) => binding.design_targets.map((target) => ({
         outcome_key: outcome.key,
         binding,
@@ -29,6 +30,7 @@ export function createLongTaskDesignHandoffConsumer(contract) {
     const indexedTargetKeys = new Set();
     const consumed = new Set();
     const validationErrors = new Map();
+    const feasibilityBindingRefsBySurface = new Map();
     let duplicate = null;
     const unbound = [];
     const handoffSetIntegrity = createDesignResourceHandoffSetIntegrity(invalid);
@@ -54,6 +56,14 @@ export function createLongTaskDesignHandoffConsumer(contract) {
                 else
                     resourcePaths.set(resource.path, identity);
             }
+            for (const input of preflight.handoff.technical_feasibility_inputs) {
+                const identity = JSON.stringify(input);
+                const previous = resourcePaths.get(input.path);
+                if (previous && previous !== identity)
+                    recordCrossVersionIssue("handoff_set_feasibility_path_conflict", input.path);
+                else
+                    resourcePaths.set(input.path, identity);
+            }
             if (!("preflight_schema_version" in preflight))
                 handoffSetIntegrity.consume(preflight);
             for (const target of preflight.handoff.targets) {
@@ -75,6 +85,8 @@ export function createLongTaskDesignHandoffConsumer(contract) {
                             target,
                         };
                         validateSymbolicTargetIdentity(contractTarget, indexedTarget);
+                        const feasibility = validateLongTaskDesignFeasibilityBindings(contract, contractTarget, preflight, sourceItems, { deferComponentBindingAttribution: true });
+                        recordFeasibilityBindingAttribution(feasibilityBindingRefsBySurface, contractTarget, feasibility.consumed_component_binding_refs);
                         validateSymbolicCoverageClaims(contract, contractTarget, indexedTarget);
                         validateBlockerBindings(contract, contractTarget, indexedTarget);
                     }
@@ -84,6 +96,8 @@ export function createLongTaskDesignHandoffConsumer(contract) {
                             target: target,
                         };
                         validateTargetIdentity(contractTarget, indexedTarget);
+                        const feasibility = validateLongTaskDesignFeasibilityBindings(contract, contractTarget, preflight, sourceItems, { deferComponentBindingAttribution: true });
+                        recordFeasibilityBindingAttribution(feasibilityBindingRefsBySurface, contractTarget, feasibility.consumed_component_binding_refs);
                         validateLongTaskDesignTargetCapabilities(contract, contractTarget, indexedTarget);
                         validateCoverageClaims(contract, contractTarget, indexedTarget);
                         validateBlockerBindings(contract, contractTarget, indexedTarget);
@@ -106,11 +120,33 @@ export function createLongTaskDesignHandoffConsumer(contract) {
                 if (validationErrors.has(contractTarget.target.key))
                     throw validationErrors.get(contractTarget.target.key);
             }
+            validateSurfaceFeasibilityBindingAttribution(contractTargets, feasibilityBindingRefsBySurface);
             if (unbound.length)
                 invalid("handoff_target_unbound", unbound[0]);
         },
     };
 }
+function recordFeasibilityBindingAttribution(bySurface, contractTarget, bindingRefs) {
+    const key = surfaceBindingIdentity(contractTarget);
+    const consumed = bySurface.get(key) ?? new Set();
+    for (const bindingRef of bindingRefs)
+        consumed.add(bindingRef);
+    bySurface.set(key, consumed);
+}
+function validateSurfaceFeasibilityBindingAttribution(contractTargets, bySurface) {
+    const surfaces = new Map();
+    for (const contractTarget of contractTargets)
+        surfaces.set(surfaceBindingIdentity(contractTarget), contractTarget);
+    for (const [surfaceKey, contractTarget] of surfaces) {
+        const consumed = bySurface.get(surfaceKey) ?? new Set();
+        for (const bindingRef of contractTarget.binding.component_binding_refs)
+            if (!consumed.has(bindingRef))
+                invalid("feasibility_component_binding_unattributed", `${contractTarget.binding.key}:${bindingRef}`);
+    }
+}
+function surfaceBindingIdentity(contractTarget) {
+    return `${contractTarget.outcome_key}\0${contractTarget.binding.key}`;
+}
 function validateSymbolicCoverageClaims(contract, contractTarget, indexed) {
     const claims = new Map(contract.source_claims.map((item) => [item.key, item]));
     const rows = indexed.preflight.handoff.coverage.filter((row) => row.target_ref === contractTarget.target.key);

package/dist/lib/long-task-design-resource-method-binding.js

@@ -10,7 +10,10 @@ export function validateTargetIdentity(contractTarget, indexed) {
     assertSameSet(target.condition_keys, handoffTarget.condition_refs, "target_conditions_mismatch", target.key);
     const resourcePaths = handoffTarget.resource_refs.map((ref) => indexed.preflight.handoff.resources.find((item) => item.key === ref)
         .path);
-    assertSameSet(target.source_paths, [indexed.preflight.handoff_path, ...resourcePaths], "target_source_paths_mismatch", target.key);
+    const feasibilityPaths = indexed.preflight.handoff.technical_feasibility_inputs
+        .filter((item) => item.target_ref === handoffTarget.key)
+        .map((item) => item.path);
+    assertSameSet(target.source_paths, [indexed.preflight.handoff_path, ...resourcePaths, ...feasibilityPaths], "target_source_paths_mismatch", target.key);
 }
 export function validateSymbolicTargetIdentity(contractTarget, indexed) {
     const { target } = contractTarget;
@@ -25,7 +28,10 @@ export function validateSymbolicTargetIdentity(contractTarget, indexed) {
         invalid("v2_ground_method_bindings_forbidden", target.key);
     const resourcePaths = handoffTarget.resource_refs.map((ref) => indexed.preflight.handoff.resources.find((item) => item.key === ref)
         .path);
-    assertSameSet(target.source_paths, [indexed.preflight.handoff_path, ...resourcePaths], "target_source_paths_mismatch", target.key);
+    const feasibilityPaths = indexed.preflight.handoff.technical_feasibility_inputs
+        .filter((item) => item.target_ref === handoffTarget.key)
+        .map((item) => item.path);
+    assertSameSet(target.source_paths, [indexed.preflight.handoff_path, ...resourcePaths, ...feasibilityPaths], "target_source_paths_mismatch", target.key);
 }
 export function validateSymbolicVerificationMethodBindings(contract, contractTarget, indexed, claimsBySourceItem) {
     const target = contractTarget.target;

package/dist/lib/long-task-freshness.js

@@ -8,7 +8,7 @@ import { parseDeliveryContractBundle } from "./long-task-delivery-parser.js";
 export async function deliveryCompileFreshness(compiled) {
     const findings = [];
     try {
-        const currentContract = await parseDeliveryContractBundle(compiled.workdir);
+        const currentContract = await parseDeliveryContractBundle(compiled.workdir, compiled.repository_root, { validate_structure: false });
         if (sha256Hex(canonicalValueJson(currentContract.contract)) !==
             compiled.contract_sha256)
             findings.push(`contract_changed_after_compile:${compiled.contract_file}`);

package/dist/lib/long-task-process-table.d.ts

@@ -0,0 +1,12 @@
+export interface ProcessInstance {
+    pid: number;
+    parent_pid: number;
+    start_identity: string | null;
+}
+export declare function processInstanceMatches(expected: Pick<ProcessInstance, "pid" | "start_identity">, current: Pick<ProcessInstance, "pid" | "start_identity">): boolean;
+export declare function processSnapshot(): Promise<ProcessInstance[]>;
+export declare function descendantsOf(rootPid: number, snapshot: readonly ProcessInstance[]): ProcessInstance[];
+export declare function liveProcessInstances(candidates: readonly ProcessInstance[], snapshot: readonly ProcessInstance[]): ProcessInstance[];
+export declare function rootProcessAlive(rootPid: number, rootInstance: ProcessInstance | null, snapshot: readonly ProcessInstance[]): boolean;
+export declare function uniqueProcessInstances(instances: readonly ProcessInstance[]): ProcessInstance[];
+export declare function processInstanceKey(instance: ProcessInstance): string;

package/dist/lib/long-task-process-table.js

@@ -0,0 +1,119 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const PROCESS_TABLE_OUTPUT_LIMIT = 2 * 1024 * 1024;
+const execFileAsync = promisify(execFile);
+export function processInstanceMatches(expected, current) {
+    if (expected.pid !== current.pid)
+        return false;
+    if (expected.start_identity === null || current.start_identity === null)
+        return true;
+    return expected.start_identity === current.start_identity;
+}
+export async function processSnapshot() {
+    let stdout;
+    try {
+        const result = process.platform === "win32"
+            ? await execFileAsync("powershell.exe", [
+                "-NoLogo",
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                '$rows = Get-CimInstance Win32_Process; foreach ($row in $rows) { $started = if ($null -eq $row.CreationDate) { "unknown" } else { $row.CreationDate.ToUniversalTime().Ticks }; "$($row.ProcessId) $($row.ParentProcessId) $started" }',
+            ], {
+                encoding: "utf8",
+                windowsHide: true,
+                timeout: 5_000,
+                maxBuffer: PROCESS_TABLE_OUTPUT_LIMIT,
+            })
+            : await execFileAsync("ps", ["-A", "-o", "pid=,ppid="], {
+                encoding: "utf8",
+                timeout: 5_000,
+                maxBuffer: PROCESS_TABLE_OUTPUT_LIMIT,
+            });
+        stdout = result.stdout;
+    }
+    catch (error) {
+        throw new Error(`process_observer_process_tree_inspection_unavailable:${message(error)}`);
+    }
+    const rows = [];
+    for (const line of stdout.split(/\r?\n/u)) {
+        const [pidText, parentText, startText] = line.trim().split(/\s+/u);
+        const pid = Number.parseInt(pidText ?? "", 10);
+        const parent = Number.parseInt(parentText ?? "", 10);
+        if (!Number.isSafeInteger(pid) || !Number.isSafeInteger(parent))
+            continue;
+        rows.push({
+            pid,
+            parent_pid: parent,
+            start_identity: process.platform === "win32" && startText ? startText : null,
+        });
+    }
+    return rows;
+}
+export function descendantsOf(rootPid, snapshot) {
+    const children = new Map();
+    for (const processInstance of snapshot) {
+        const row = children.get(processInstance.parent_pid);
+        if (row)
+            row.push(processInstance);
+        else
+            children.set(processInstance.parent_pid, [processInstance]);
+    }
+    const result = [];
+    const pending = [...(children.get(rootPid) ?? [])];
+    const seen = new Set();
+    while (pending.length) {
+        const processInstance = pending.shift();
+        const key = processInstanceKey(processInstance);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(processInstance);
+        pending.push(...(children.get(processInstance.pid) ?? []));
+    }
+    return result;
+}
+export function liveProcessInstances(candidates, snapshot) {
+    if (process.platform !== "win32")
+        return candidates.filter((candidate) => processIdExists(candidate.pid));
+    const currentByPid = new Map(snapshot.map((entry) => [entry.pid, entry]));
+    return candidates.filter((candidate) => {
+        const current = currentByPid.get(candidate.pid);
+        return current ? processInstanceMatches(candidate, current) : false;
+    });
+}
+export function rootProcessAlive(rootPid, rootInstance, snapshot) {
+    if (process.platform !== "win32")
+        return processIdExists(rootPid);
+    const current = snapshot.find((entry) => entry.pid === rootPid);
+    if (!current)
+        return false;
+    return rootInstance ? processInstanceMatches(rootInstance, current) : true;
+}
+export function uniqueProcessInstances(instances) {
+    return [
+        ...new Map(instances.map((instance) => [processInstanceKey(instance), instance])).values(),
+    ];
+}
+export function processInstanceKey(instance) {
+    return `${instance.pid}:${instance.start_identity ?? "pid-only"}`;
+}
+function processIdExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (nodeErrorCode(error) === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+function nodeErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/lib/long-task-process-tree.d.ts

@@ -0,0 +1,9 @@
+export { processInstanceMatches } from "./long-task-process-table.js";
+export interface ProcessTreeObserver {
+    stop(): void;
+    wait(): Promise<void>;
+    terminate(force: boolean): Promise<void>;
+    forceQuiescence(): Promise<void>;
+    assertQuiescent(): Promise<void>;
+}
+export declare function createProcessTreeObserver(rootPid: number): ProcessTreeObserver;

package/dist/lib/long-task-process-tree.js

@@ -0,0 +1,138 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { descendantsOf, liveProcessInstances, processInstanceKey, processInstanceMatches, processSnapshot, rootProcessAlive, uniqueProcessInstances, } from "./long-task-process-table.js";
+export { processInstanceMatches } from "./long-task-process-table.js";
+const PROCESS_TREE_GRACE_MS = 1_000;
+const execFileAsync = promisify(execFile);
+export function createProcessTreeObserver(rootPid) {
+    let stopped = false;
+    let rootInstance = null;
+    const observed = new Map();
+    const monitor = observe();
+    return {
+        stop() {
+            stopped = true;
+        },
+        wait() {
+            return monitor;
+        },
+        terminate(force) {
+            return terminateProcessTree(rootPid, rootInstance, force, [...observed.values()], true);
+        },
+        forceQuiescence() {
+            return forceProcessTreeQuiescence(rootPid, rootInstance, observed);
+        },
+        assertQuiescent() {
+            return assertProcessTreeQuiescent(rootPid, rootInstance, observed);
+        },
+    };
+    async function observe() {
+        do {
+            const snapshot = await processSnapshot();
+            const currentRoot = snapshot.find((entry) => entry.pid === rootPid);
+            if (currentRoot &&
+                (!rootInstance || processInstanceMatches(rootInstance, currentRoot))) {
+                rootInstance ??= currentRoot;
+                for (const descendant of descendantsOf(rootPid, snapshot))
+                    observed.set(processInstanceKey(descendant), descendant);
+            }
+            if (stopped)
+                return;
+            await delay(process.platform === "win32" ? 100 : 25);
+        } while (!stopped);
+    }
+}
+async function forceProcessTreeQuiescence(rootPid, rootInstance, observed) {
+    await terminateProcessTree(rootPid, rootInstance, true, [...observed.values()], true);
+    const deadline = Date.now() + PROCESS_TREE_GRACE_MS;
+    while (Date.now() < deadline) {
+        const snapshot = await processSnapshot();
+        const rootAlive = rootProcessAlive(rootPid, rootInstance, snapshot);
+        const descendantsAlive = liveProcessInstances([...observed.values()], snapshot).length;
+        const groupAlive = process.platform !== "win32" && processGroupExists(rootPid);
+        if (!rootAlive && descendantsAlive === 0 && !groupAlive)
+            return;
+        await delay(process.platform === "win32" ? 100 : 25);
+    }
+    throw new Error("process_observer_descendant_process_alive");
+}
+async function assertProcessTreeQuiescent(rootPid, rootInstance, observed) {
+    const snapshot = await processSnapshot();
+    const currentRoot = snapshot.find((entry) => entry.pid === rootPid);
+    const finalDescendants = currentRoot &&
+        (!rootInstance || processInstanceMatches(rootInstance, currentRoot))
+        ? descendantsOf(rootPid, snapshot)
+        : [];
+    const candidates = uniqueProcessInstances([
+        ...observed.values(),
+        ...finalDescendants,
+    ]);
+    const descendants = liveProcessInstances(candidates, snapshot);
+    const processGroupAlive = process.platform !== "win32" && processGroupExists(rootPid);
+    if (!descendants.length && !processGroupAlive)
+        return;
+    await terminateProcessTree(rootPid, rootInstance, true, descendants, false);
+    throw new Error("process_observer_descendant_process_alive");
+}
+async function terminateProcessTree(rootPid, rootInstance, force, knownDescendants, includeRoot) {
+    if (!Number.isSafeInteger(rootPid) || rootPid <= 0)
+        return;
+    if (process.platform === "win32") {
+        const snapshot = await processSnapshot();
+        const currentRoot = snapshot.find((entry) => entry.pid === rootPid);
+        const rootTarget = includeRoot &&
+            currentRoot &&
+            (!rootInstance || processInstanceMatches(rootInstance, currentRoot))
+            ? currentRoot
+            : null;
+        const currentDescendants = rootTarget
+            ? descendantsOf(rootPid, snapshot)
+            : [];
+        const descendants = liveProcessInstances(uniqueProcessInstances([...knownDescendants, ...currentDescendants]), snapshot).reverse();
+        const targets = rootTarget ? [...descendants, rootTarget] : descendants;
+        for (const target of targets)
+            await execFileAsync("taskkill.exe", ["/PID", String(target.pid), "/T", "/F"], {
+                windowsHide: true,
+                timeout: PROCESS_TREE_GRACE_MS,
+            }).catch(() => undefined);
+        return;
+    }
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    if (includeRoot)
+        try {
+            process.kill(-rootPid, signal);
+        }
+        catch (error) {
+            if (nodeErrorCode(error) !== "ESRCH")
+                throw error;
+        }
+    const snapshot = await processSnapshot();
+    const descendants = liveProcessInstances(knownDescendants, snapshot);
+    for (const descendant of descendants.reverse())
+        try {
+            process.kill(descendant.pid, signal);
+        }
+        catch (error) {
+            if (nodeErrorCode(error) !== "ESRCH")
+                throw error;
+        }
+}
+function processGroupExists(rootPid) {
+    try {
+        process.kill(-rootPid, 0);
+        return true;
+    }
+    catch (error) {
+        if (nodeErrorCode(error) === "ESRCH")
+            return false;
+        throw error;
+    }
+}
+function nodeErrorCode(error) {
+    return error && typeof error === "object" && "code" in error
+        ? String(error.code)
+        : null;
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/lib/long-task-protected-files.d.ts

@@ -1 +1 @@
-export { assertProtectedRepositoryFile } from "./repository-path-safety.js";
+export { assertProtectedRepositoryDirectory, assertProtectedRepositoryFile, } from "./repository-path-safety.js";

package/dist/lib/long-task-protected-files.js

@@ -1 +1 @@
-export { assertProtectedRepositoryFile } from "./repository-path-safety.js";
+export { assertProtectedRepositoryDirectory, assertProtectedRepositoryFile, } from "./repository-path-safety.js";

package/dist/lib/long-task-ui-surface-policy.d.ts

@@ -1,4 +1,5 @@
 import type { CompiledClaimsV2 } from "./long-task-claims.js";
 import type { DeliveryContractV2 } from "./long-task-delivery-types.js";
 import { type Reporter } from "./long-task-ui-surface-validation.js";
-export declare function validateUiSurfaceBindings(contract: DeliveryContractV2, claims: CompiledClaimsV2, report?: Reporter): void;
+import type { DeliveryContractStructureValidationOptions } from "./long-task-delivery-validation.js";
+export declare function validateUiSurfaceBindings(contract: DeliveryContractV2, claims: CompiledClaimsV2, report?: Reporter, options?: DeliveryContractStructureValidationOptions): void;