project-tiny-context-harness 0.8.1 → 0.8.2

package/dist/lib/long-task-root-shape.js

@@ -1,6 +1,7 @@
 import { parseGlobalCounterfactuals } from "./long-task-acceptance-shape.js";
 import { parseCheck } from "./long-task-check-shape.js";
-import { array, boolean, key, literal, object, parseKeyedPaths, parseKeyedStatements, repositoryFiles, string, strings, } from "./long-task-delivery-shape.js";
+import { array, boolean, key, literal, object, parseApplicableKeyedStatements, parseClaimApplicability, parseKeyedPaths, repositoryFiles, string, strings, } from "./long-task-delivery-shape.js";
+import { EXECUTION_TARGET_CAPABILITIES } from "./execution-target-capabilities.js";
 const RISK_FACTS = [
     "public_api_or_schema_change",
     "persistent_data_change",
@@ -51,6 +52,7 @@ export function parseTask(value) {
                 "role",
                 "runtime_family",
                 "root_entrypoint",
+                "capabilities",
             ]);
             return {
                 key: key(target.key, `${label}.key`),
@@ -65,13 +67,14 @@ export function parseTask(value) {
                     "external",
                 ], `${label}.runtime_family`),
                 root_entrypoint: string(target.root_entrypoint, `${label}.root_entrypoint`),
+                capabilities: strings(target.capabilities, `${label}.capabilities`).map((item, capabilityIndex) => literal(item, EXECUTION_TARGET_CAPABILITIES, `${label}.capabilities[${capabilityIndex}]`)),
             };
         }),
         source_paths: repositoryFiles(row.source_paths, "task.source_paths"),
         context_refs: repositoryFiles(row.context_refs, "task.context_refs"),
         context_snapshot_mode: Object.hasOwn(row, "context_snapshot_mode")
             ? literal(row.context_snapshot_mode, ["referenced", "full"], "task.context_snapshot_mode")
-            : "referenced",
+            : "full",
     };
 }
 export function parseStages(value) {
@@ -107,25 +110,28 @@ export function parseRisk(value) {
     };
 }
 export function parseGlobal(value) {
-    const row = object(value, "global", [], ["product", "technical", "acceptance"]);
+    const row = object(value, "global", [], ["applicability", "product", "technical", "acceptance"]);
     const product = object(Object.hasOwn(row, "product") ? row.product : {}, "global.product", [], ["non_goals"]);
     const technical = object(Object.hasOwn(row, "technical") ? row.technical : {}, "global.technical", [], ["constraints", "forbidden_paths", "forbidden_shortcuts"]);
     const acceptance = object(Object.hasOwn(row, "acceptance") ? row.acceptance : {}, "global.acceptance", [], ["checks", "counterfactual_controls", "external_confirmations"]);
     return {
+        applicability: Object.hasOwn(row, "applicability")
+            ? parseClaimApplicability(row.applicability, "global.applicability")
+            : [],
         product: {
             non_goals: Object.hasOwn(product, "non_goals")
-                ? parseKeyedStatements(product.non_goals, "global.product.non_goals")
+                ? parseApplicableKeyedStatements(product.non_goals, "global.product.non_goals")
                 : [],
         },
         technical: {
             constraints: Object.hasOwn(technical, "constraints")
-                ? parseKeyedStatements(technical.constraints, "global.technical.constraints")
+                ? parseApplicableKeyedStatements(technical.constraints, "global.technical.constraints")
                 : [],
             forbidden_paths: Object.hasOwn(technical, "forbidden_paths")
                 ? parseKeyedPaths(technical.forbidden_paths, "global.technical.forbidden_paths")
                 : [],
             forbidden_shortcuts: Object.hasOwn(technical, "forbidden_shortcuts")
-                ? parseKeyedStatements(technical.forbidden_shortcuts, "global.technical.forbidden_shortcuts")
+                ? parseApplicableKeyedStatements(technical.forbidden_shortcuts, "global.technical.forbidden_shortcuts")
                 : [],
         },
         acceptance: {

package/dist/lib/long-task-runner-freeze.js

@@ -7,6 +7,7 @@ import { nearestRunnerFile, npmCliPath, npxCliPath, } from "./long-task-runner-f
 import { canonicalValueJson, sha256Hex } from "./strict-codec.js";
 import { repoRelative, resolveInsideRepository, } from "./long-task-workspace.js";
 import { evidenceAdapterForRunner } from "./long-task-evidence-adapter-policy.js";
+import { freezeLocalVerifierDependencyClosure, packageScriptVerifierRoots, } from "./long-task-verifier-dependency-closure.js";
 export async function freezeDeliveryCheck(check, outcomeKey, repository, baseline, executionTarget, knownExecutionTargets, designConformanceTargets) {
     const prefix = outcomeKey ? `CHECK.${outcomeKey}` : "CHECK.GLOBAL";
     const expectedOutputs = check.expected_output_paths.map((pattern, index) => assertRepositoryPattern(repository, pattern, `${check.key}.expected_output_paths[${index}]`));
@@ -164,6 +165,21 @@ async function freezeVerificationInputs(check, repository, manifest, cwd, target
         const protectedFile = await assertProtectedRepositoryFile(repository, path.join(repository, ...relative.split("/")), `${check.key}.automatic_verification_input`);
         result[relative] = sha256Hex(await readFile(protectedFile));
     }
+    if (check.runner.type === "package_script") {
+        const packageJson = JSON.parse(await readFile(target, "utf8"));
+        const script = packageJson.scripts?.[check.runner.target];
+        if (typeof script !== "string" || !script.trim())
+            throw new Error(`package_script_not_found:${check.key}:${check.runner.target}`);
+        for (const relative of packageScriptVerifierRoots(script, repoRelative(repository, target), manifest)) {
+            const protectedFile = await assertProtectedRepositoryFile(repository, path.join(repository, ...relative.split("/")), `${check.key}.package_script_entry`);
+            result[relative] = sha256Hex(await readFile(protectedFile));
+        }
+    }
+    Object.assign(result, await freezeLocalVerifierDependencyClosure(repository, Object.keys(result), manifest, [
+        ...check.input_paths,
+        ...check.expected_output_paths,
+        ...check.artifact_globs,
+    ]));
     return sortRecord(result);
 }
 function sortRecord(value) {

package/dist/lib/long-task-runtime-types.d.ts

@@ -32,20 +32,24 @@ export interface ProductClaimV2 {
     id: string;
     outcome_key: string;
     local_key: string;
-    kind: "result" | "requirement" | "control" | "non_completing" | "obligation" | "forbidden_shortcut";
+    kind: "result" | "requirement" | "control" | "control_relation" | "non_completing" | "obligation" | "forbidden_shortcut";
     required_proof_surfaces: ProofSurface[];
+    required_polarity: "positive" | "negative";
+    applicability_refs: string[];
 }
 export interface GlobalClaimV2 {
     id: string;
     local_key: string;
     kind: "global_non_goal" | "global_constraint" | "global_forbidden_shortcut";
-    required_polarity: "any" | "negative";
+    required_polarity: "positive" | "negative";
+    applicability_refs: string[];
 }
 export interface ClaimProofV2 {
     check_key: string;
     assertion_key: string | null;
     polarity: "positive" | "negative" | "population" | "counterfactual";
     proof_surface: ProofSurface;
+    applicability_ref: string | null;
 }
 export interface ClaimCoverageSummaryV2 {
     claims_total: number;
@@ -53,6 +57,8 @@ export interface ClaimCoverageSummaryV2 {
     uncovered_claims: string[];
     claims_by_global: Record<string, {
         covered: boolean;
+        applicability_refs: string[];
+        uncovered_applicability_refs: string[];
         proofs: ClaimProofV2[];
     }>;
     claims_by_outcome: Record<string, Record<string, {
@@ -60,6 +66,8 @@ export interface ClaimCoverageSummaryV2 {
         covered_surfaces: ProofSurface[];
         missing_surfaces: ProofSurface[];
         covered: boolean;
+        applicability_refs: string[];
+        uncovered_applicability_refs: string[];
         proofs: ClaimProofV2[];
     }>>;
 }
@@ -129,6 +137,7 @@ export interface AssertionResultV2 {
     polarity: "positive" | "negative";
     passed: boolean;
     claims: string[];
+    applicability_ref?: string;
     observation: string;
     evidence_capabilities: EvidenceCapabilityV2[];
     evidence_complete: boolean;

package/dist/lib/long-task-semantic-assurance-policy.d.ts

@@ -0,0 +1,4 @@
+import type { DeliveryContractV2 } from "./long-task-delivery-types.js";
+type Reporter = (message: string) => void;
+export declare function validateSemanticAssuranceShape(contract: DeliveryContractV2, report?: Reporter): void;
+export {};

package/dist/lib/long-task-semantic-assurance-policy.js

@@ -0,0 +1,52 @@
+export function validateSemanticAssuranceShape(contract, report) {
+    if (contract.task.context_snapshot_mode !== "full")
+        issue(report, "long_task_full_context_required", contract.task.context_snapshot_mode);
+    validateApplicabilityScope("GLOBAL", contract.global.applicability, report);
+    for (const outcome of contract.outcomes)
+        validateApplicabilityScope(outcome.key, outcome.applicability, report);
+}
+function validateApplicabilityScope(scope, profiles, report) {
+    if (!profiles.length)
+        return;
+    let expectedDimensionKeys = null;
+    const cells = new Map();
+    for (const profile of profiles) {
+        if (!profile.dimensions.length)
+            issue(report, "applicability_dimensions_required", `${scope}:${profile.key}`);
+        const keys = profile.dimensions.map((dimension) => dimension.key);
+        if (new Set(keys).size !== keys.length)
+            issue(report, "applicability_dimension_duplicate", `${scope}:${profile.key}`);
+        const sortedKeys = [...keys].sort();
+        if (expectedDimensionKeys === null)
+            expectedDimensionKeys = sortedKeys;
+        else if (!same(expectedDimensionKeys, sortedKeys))
+            issue(report, "applicability_dimension_set_mismatch", `${scope}:${profile.key}:${expectedDimensionKeys.join(",")}:${sortedKeys.join(",")}`);
+        const dimensions = [...profile.dimensions]
+            .sort((left, right) => left.key.localeCompare(right.key))
+            .map((dimension) => `${dimension.key}=${dimension.value}`)
+            .join(",");
+        const cell = [
+            profile.target_ref,
+            profile.journey_role,
+            dimensions,
+            [...profile.given_refs].sort().join(","),
+            profile.when_refs.join(","),
+        ].join("|");
+        const owner = cells.get(cell);
+        if (owner)
+            issue(report, "applicability_cell_duplicate", `${scope}:${profile.key}:${owner}`);
+        else
+            cells.set(cell, profile.key);
+    }
+}
+function same(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+function issue(report, code, detail) {
+    const message = `delivery_contract_invalid:${code}:${detail}`;
+    if (report)
+        report(message);
+    else
+        throw new Error(message);
+}

package/dist/lib/long-task-semantic-contract-types.d.ts

@@ -1,7 +1,12 @@
+import type { ExecutionTargetCapabilityV2 } from "./execution-target-capabilities.js";
+export type { ExecutionTargetCapabilityV2 } from "./execution-target-capabilities.js";
 export interface KeyedStatementV2 {
     key: string;
     statement: string;
 }
+export interface ApplicableKeyedStatementV2 extends KeyedStatementV2 {
+    applicability_refs: string[];
+}
 export type ExternalConfirmationKindV2 = "functional_prerequisite" | "field_validation" | "production_release_gate" | "commercial_activation" | "expert_authority";
 export type TargetCompletionStateV2 = "implementation_complete" | "target_profile_usable" | "production_release_ready";
 export type ExecutionTargetRuntimeFamilyV2 = "browser" | "native" | "desktop" | "service" | "process" | "external";
@@ -17,6 +22,7 @@ export interface ExecutionTargetV2 {
     role: "product" | "support" | "observer";
     runtime_family: ExecutionTargetRuntimeFamilyV2;
     root_entrypoint: string;
+    capabilities: ExecutionTargetCapabilityV2[];
 }
 export interface DeliveryStageV2 {
     key: string;
@@ -25,7 +31,18 @@ export interface DeliveryStageV2 {
     gate_outcome: string;
 }
 export type DeliveryJourneyRoleV2 = "success" | "degradation" | "recovery" | "stage_gate" | "conformance";
-export type EvidenceCapabilityV2 = "presence" | "interaction_trace" | "state_delta" | "cross_surface_consistency" | "durable_readback" | "boundary_invocation" | "external_side_effect" | "failure_injection" | "visual_render" | "design_conformance" | "target_runtime" | "input_variation";
+export interface ClaimApplicabilityV2 {
+    key: string;
+    target_ref: string;
+    journey_role: DeliveryJourneyRoleV2;
+    dimensions: Array<{
+        key: string;
+        value: string;
+    }>;
+    given_refs: string[];
+    when_refs: string[];
+}
+export type EvidenceCapabilityV2 = "presence" | "interaction_trace" | "state_delta" | "cross_surface_consistency" | "durable_readback" | "boundary_invocation" | "external_side_effect" | "failure_injection" | "visual_render" | "design_conformance" | "design_method" | "target_runtime" | "input_variation";
 export interface CheckExecutionTargetV2 {
     target_ref: string;
     entrypoint: "root" | "internal";

package/dist/lib/long-task-semantic-drift-migration.js

@@ -6,7 +6,12 @@ export function semanticDriftMigrationFields(value) {
     required(root, "$", ["stages"], missing);
     const task = row(root.task);
     if (task) {
-        required(task, "task", ["target_profile", "execution_targets"], missing);
+        required(task, "task", ["target_profile", "execution_targets", "context_snapshot_mode"], missing);
+        if (Object.hasOwn(task, "context_snapshot_mode") &&
+            task.context_snapshot_mode !== "full")
+            missing.push("task.context_snapshot_mode=full");
+        for (const [index, target] of rows(task.execution_targets).entries())
+            required(target, `task.execution_targets[${index}]`, ["capabilities"], missing);
         const profile = row(task.target_profile);
         if (profile)
             required(profile, "task.target_profile", ["required_target_refs"], missing);
@@ -14,6 +19,7 @@ export function semanticDriftMigrationFields(value) {
     for (const [index, outcome] of rows(root.outcomes).entries())
         collectOutcome(outcome, `outcomes[${index}]`, missing);
     const global = row(root.global);
+    collectApplicability(global?.applicability, "global.applicability", missing);
     const globalAcceptance = row(global?.acceptance);
     collectChecks(globalAcceptance?.checks, "global.acceptance.checks", missing);
     for (const [index, confirmation] of rows(globalAcceptance?.external_confirmations).entries())
@@ -35,7 +41,8 @@ export function assertNoSemanticDriftMigration(fields) {
     throw new Error(`long_task_delivery_v2_semantic_drift_migration_required:${detail}${suffix}`);
 }
 function collectOutcome(outcome, label, missing) {
-    required(outcome, label, ["stage"], missing);
+    required(outcome, label, ["stage", "applicability"], missing);
+    collectApplicability(outcome.applicability, `${label}.applicability`, missing);
     const product = row(outcome.product);
     if (product) {
         required(product, `${label}.product`, ["success_path_required", "degradation_path_required"], missing);
@@ -43,9 +50,33 @@ function collectOutcome(outcome, label, missing) {
             product.controls.length > 0 &&
             !Object.hasOwn(product, "surface_bindings"))
             missing.push(`${label}.product.surface_bindings`);
+        const relationClosure = row(product.control_relation_closure);
+        if (relationClosure && relationClosure.state !== "unresolved")
+            required(relationClosure, `${label}.product.control_relation_closure`, ["applicability_refs"], missing);
     }
     const acceptance = row(outcome.acceptance);
     collectChecks(acceptance?.checks, `${label}.acceptance.checks`, missing);
+    const population = row(acceptance?.population);
+    if (population) {
+        required(population, `${label}.acceptance.population`, ["universe_binding_key"], missing);
+        const observations = row(population.observations);
+        if (observations)
+            required(observations, `${label}.acceptance.population.observations`, ["universe_ids"], missing);
+    }
+    for (const [bindingIndex, binding] of rows(product?.surface_bindings).entries()) {
+        for (const [blockerIndex, blocker] of rows(binding.acceptance_blockers).entries())
+            required(blocker, `${label}.product.surface_bindings[${bindingIndex}].acceptance_blockers[${blockerIndex}]`, ["required_capabilities"], missing);
+        for (const [targetIndex, target] of rows(binding.design_targets).entries())
+            for (const [methodIndex, method] of rows(target.verification_method_bindings).entries()) {
+                required(method, `${label}.product.surface_bindings[${bindingIndex}].design_targets[${targetIndex}].verification_method_bindings[${methodIndex}]`, ["evidence_artifacts"], missing);
+                for (const [artifactIndex, artifact] of rows(method.evidence_artifacts).entries())
+                    required(artifact, `${label}.product.surface_bindings[${bindingIndex}].design_targets[${targetIndex}].verification_method_bindings[${methodIndex}].evidence_artifacts[${artifactIndex}]`, ["observation_path"], missing);
+            }
+    }
+}
+function collectApplicability(value, label, missing) {
+    for (const [index, profile] of rows(value).entries())
+        required(profile, `${label}[${index}]`, ["dimensions"], missing);
 }
 function collectChecks(value, label, missing) {
     for (const [index, check] of rows(value).entries()) {

package/dist/lib/long-task-semantic-mutation.d.ts

@@ -0,0 +1,7 @@
+import type { CounterfactualMutationV2 } from "./long-task-delivery-types.js";
+type NarrowMutation = Extract<CounterfactualMutationV2, {
+    type: "replace_json_value" | "replace_text";
+}>;
+export declare function applyNarrowSemanticMutation(root: string, mutation: NarrowMutation): Promise<void>;
+export declare function mutateSemanticText(current: string, mutation: NarrowMutation, requireChange?: boolean): string;
+export {};

package/dist/lib/long-task-semantic-mutation.js

@@ -0,0 +1,81 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { canonicalValueJson } from "./strict-codec.js";
+export async function applyNarrowSemanticMutation(root, mutation) {
+    const target = path.join(root, ...mutation.path.split("/"));
+    const current = await readFile(target, "utf8");
+    const next = mutateSemanticText(current, mutation, false);
+    await writeFile(target, next, "utf8");
+}
+export function mutateSemanticText(current, mutation, requireChange = true) {
+    if (mutation.type === "replace_text") {
+        if (requireChange && mutation.match === mutation.replacement)
+            throw new Error("counterfactual_replacement_must_change_carrier");
+        const count = occurrences(current, mutation.match);
+        if (count !== 1)
+            throw new Error(`counterfactual_text_match_count:${count}`);
+        return current.replace(mutation.match, mutation.replacement);
+    }
+    let value;
+    try {
+        value = JSON.parse(current);
+    }
+    catch {
+        throw new Error("counterfactual_json_invalid");
+    }
+    const segments = mutation.pointer
+        .slice(1)
+        .split("/")
+        .map((segment) => segment.replace(/~1/gu, "/").replace(/~0/gu, "~"));
+    let owner = value;
+    for (const segment of segments.slice(0, -1))
+        owner = child(owner, segment, mutation.pointer);
+    const leaf = segments.at(-1);
+    if (!owner || typeof owner !== "object")
+        throw new Error(`counterfactual_json_pointer_unknown:${mutation.pointer}`);
+    if (Array.isArray(owner)) {
+        const index = arrayIndex(leaf, owner.length, mutation.pointer);
+        if (requireChange &&
+            canonicalValueJson(owner[index]) === canonicalValueJson(mutation.value))
+            throw new Error("counterfactual_replacement_must_change_carrier");
+        owner[index] = mutation.value;
+    }
+    else {
+        const record = owner;
+        if (!Object.hasOwn(record, leaf))
+            throw new Error(`counterfactual_json_pointer_unknown:${mutation.pointer}`);
+        if (requireChange &&
+            canonicalValueJson(record[leaf]) === canonicalValueJson(mutation.value))
+            throw new Error("counterfactual_replacement_must_change_carrier");
+        record[leaf] = mutation.value;
+    }
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function child(value, segment, pointer) {
+    if (!value || typeof value !== "object")
+        throw new Error(`counterfactual_json_pointer_unknown:${pointer}`);
+    if (Array.isArray(value))
+        return value[arrayIndex(segment, value.length, pointer)];
+    if (!Object.hasOwn(value, segment))
+        throw new Error(`counterfactual_json_pointer_unknown:${pointer}`);
+    return value[segment];
+}
+function arrayIndex(value, length, pointer) {
+    if (!/^(?:0|[1-9][0-9]*)$/u.test(value))
+        throw new Error(`counterfactual_json_pointer_unknown:${pointer}`);
+    const index = Number(value);
+    if (!Number.isSafeInteger(index) || index >= length)
+        throw new Error(`counterfactual_json_pointer_unknown:${pointer}`);
+    return index;
+}
+function occurrences(value, search) {
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        const index = value.indexOf(search, offset);
+        if (index < 0)
+            return count;
+        count += 1;
+        offset = index + search.length;
+    }
+}

package/dist/lib/long-task-shape-primitives.d.ts

@@ -16,5 +16,5 @@ export declare function key(value: unknown, label: string): string;
 export declare function nullable<T>(value: unknown, parser: (value: unknown) => T): T | null;
 export declare const PROOF_SURFACES: readonly ["ui_browser", "runtime_behavior", "api_contract", "data_state", "security_boundary", "population_coverage", "implementation_structure"];
 export declare const JOURNEY_ROLES: readonly ["success", "degradation", "recovery", "stage_gate", "conformance"];
-export declare const EVIDENCE_CAPABILITIES: readonly ["presence", "interaction_trace", "state_delta", "cross_surface_consistency", "durable_readback", "boundary_invocation", "external_side_effect", "failure_injection", "visual_render", "design_conformance", "target_runtime", "input_variation"];
+export declare const EVIDENCE_CAPABILITIES: readonly ["presence", "interaction_trace", "state_delta", "cross_surface_consistency", "durable_readback", "boundary_invocation", "external_side_effect", "failure_injection", "visual_render", "design_conformance", "design_method", "target_runtime", "input_variation"];
 export declare function fail(label: string, message: string): never;

package/dist/lib/long-task-shape-primitives.js

@@ -99,6 +99,7 @@ export const EVIDENCE_CAPABILITIES = [
     "failure_injection",
     "visual_render",
     "design_conformance",
+    "design_method",
     "target_runtime",
     "input_variation",
 ];

package/dist/lib/long-task-source-authority-types.d.ts

@@ -1,8 +1,10 @@
 import type { RiskFactName } from "./long-task-risk-types.js";
 export type SourceItemKind = "outcome_result" | "requirement" | "control" | "acceptance" | "technical_obligation" | "non_completing" | "non_goal" | "forbidden_shortcut" | "risk_fact" | "external_confirmation" | "decision";
+export type SourceItemAspect = "architecture";
 export interface CompiledSourceItemV2 {
     key: string;
     kind: SourceItemKind;
+    aspect?: SourceItemAspect;
     source_path: string;
     normalized_text: string;
     text_sha256: string;

package/dist/lib/long-task-source-item-parser.d.ts

@@ -1,3 +1,3 @@
 import type { CompiledSourceItemV2 } from "./long-task-delivery-types.js";
 export declare function parseSourceItems(sourcePath: string, content: string): CompiledSourceItemV2[];
-export declare function normalizeSourceItemText(value: string): string;
+export { normalizeSourceItemText } from "./long-task-source-markers.js";