project-tiny-context-harness 0.2.84 → 0.6.0

package/dist/lib/long-task-authoring-authority-preview.js

@@ -0,0 +1,85 @@
+import { computeAuthorityHashes } from "./long-task-authority.js";
+import { computeAuthorityMaterials, compiledAuthorityMaterials, } from "./long-task-authority-materials.js";
+import { addDiagnosticError } from "./long-task-authoring-preflight-diagnostics.js";
+import { loadActiveLongTaskAuthority, } from "./long-task-state.js";
+import { canonicalValueJson, sha256Hex } from "./strict-codec.js";
+export async function loadAuthoringActiveAuthority(repository, workdir, diagnostics) {
+    try {
+        const active = (await loadActiveLongTaskAuthority(repository)).authority;
+        if (active && active.workdir !== workdir)
+            diagnostics.push({
+                level: "error",
+                code: "active_task_exists",
+                message: `Another workdir owns Active Authority: ${active.workdir}`,
+            });
+        return active;
+    }
+    catch (error) {
+        addDiagnosticError(diagnostics, error);
+        return null;
+    }
+}
+export function authoringRevisionPreview(contract, sourceHashes, sourceItems, context, active) {
+    if (!active)
+        return {
+            active: false,
+            authority_revision: null,
+            contract_changed: false,
+            source_or_context_changed: false,
+            declared_authority_sections_changed: [],
+        };
+    const hashes = computeAuthorityHashes(contract);
+    const previousDeclaredHashes = computeAuthorityHashes({
+        schema_version: "long-task-delivery-v2",
+        task: active.authority_snapshot.task,
+        source_claims: active.authority_snapshot.source_claims,
+        risk: active.authority_snapshot.risk,
+        global: active.authority_snapshot.global,
+        outcomes: active.authority_snapshot.outcomes,
+    });
+    const declaredChanged = new Set(Object.keys(hashes)
+        .filter((key) => hashes[key] !== previousDeclaredHashes[key])
+        .map((key) => key.replace(/_authority_hash$/u, "")));
+    let sourceChanged = false;
+    let contextChanged = false;
+    if (sourceHashes && sourceItems && context) {
+        const next = computeAuthorityMaterials(contract, sourceHashes, sourceItems, context);
+        const previous = compiledAuthorityMaterials(active.authority_snapshot);
+        sourceChanged =
+            canonicalValueJson({
+                source_hashes: next.source_hashes,
+                source_items: next.source_items,
+            }) !==
+                canonicalValueJson({
+                    source_hashes: previous.source_hashes,
+                    source_items: previous.source_items,
+                });
+        contextChanged =
+            canonicalValueJson({
+                context_snapshot: next.context_snapshot,
+            }) !==
+                canonicalValueJson({
+                    context_snapshot: previous.context_snapshot,
+                });
+        if (sourceChanged)
+            declaredChanged.add("source");
+        if (contextChanged)
+            declaredChanged.add("context");
+    }
+    const sectionOrder = [
+        "source",
+        "product",
+        "technical",
+        "acceptance",
+        "risk",
+        "context",
+    ];
+    return {
+        active: true,
+        authority_revision: active.authority_revision,
+        contract_changed: sha256Hex(canonicalValueJson(contract)) !==
+            active.authority_snapshot.contract_sha256,
+        source_or_context_changed: sourceChanged || contextChanged,
+        declared_authority_sections_changed: sectionOrder.filter((section) => declaredChanged.has(section)),
+    };
+}

package/dist/lib/long-task-authoring-preflight-diagnostics.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedDeliveryContractV2 } from "./long-task-delivery-parser.js";
+import type { DeliveryContractV2 } from "./long-task-delivery-types.js";
+import type { AuthoringPreflightDiagnosticV1, SourceCoverageV1 } from "./long-task-authoring-preflight-types.js";
+export declare function addAuthoringDiagnostics(contract: DeliveryContractV2, parsed: ParsedDeliveryContractV2, diagnostics: AuthoringPreflightDiagnosticV1[]): void;
+export declare function sourceCoverage(contract: DeliveryContractV2): SourceCoverageV1;
+export declare function captureDiagnostic(diagnostics: AuthoringPreflightDiagnosticV1[], action: () => Promise<unknown>): Promise<void>;
+export declare function addDiagnosticError(diagnostics: AuthoringPreflightDiagnosticV1[], error: unknown, outcomeKey?: string | null, checkKey?: string): void;
+export declare function normalizeAuthoringDiagnostics(diagnostics: AuthoringPreflightDiagnosticV1[]): AuthoringPreflightDiagnosticV1[];

package/dist/lib/long-task-authoring-preflight-diagnostics.js

@@ -0,0 +1,179 @@
+import { applyDiagnosticRepairOrder } from "./long-task-authoring-preflight-repair-order.js";
+export function addAuthoringDiagnostics(contract, parsed, diagnostics) {
+    if (parsed.outcome_files.length)
+        diagnostics.push({
+            level: "warning",
+            code: "outcome_files_compatibility_only",
+            message: "outcome_files is supported only as physical compatibility; new authoring should use inline Outcomes.",
+            repair_hint: "Keep compatibility files only when required; use inline Outcomes for new authoring.",
+        });
+    for (const claim of contract.source_claims)
+        if (claim.disposition.type === "decision_required")
+            diagnostics.push({
+                level: "decision_required",
+                code: "source_claim_decision_required",
+                message: `${claim.key}: ${claim.disposition.reason}`,
+                refs: [claim.key],
+                repair_hint: "Resolve this product decision from the user or an authoritative Source before Compile; do not infer it from implementation convenience.",
+            });
+}
+export function sourceCoverage(contract) {
+    const counts = {
+        claim: 0,
+        acceptance: 0,
+        outcome_result: 0,
+        global_constraint: 0,
+        risk_fact: 0,
+        external_confirmation: 0,
+        decision_required: 0,
+    };
+    for (const item of contract.source_claims)
+        counts[item.disposition.type] += 1;
+    return {
+        total: contract.source_claims.length,
+        resolved: contract.source_claims.length - counts.decision_required,
+        mapped_to_product_claims: counts.claim,
+        mapped_to_acceptance: counts.acceptance,
+        mapped_to_outcome_results: counts.outcome_result,
+        mapped_to_global_constraints: counts.global_constraint,
+        mapped_to_risk_facts: counts.risk_fact,
+        mapped_to_external_confirmations: counts.external_confirmation,
+        decision_required: counts.decision_required,
+        unresolved: contract.source_claims
+            .filter((item) => item.disposition.type === "decision_required")
+            .map((item) => item.key),
+    };
+}
+export async function captureDiagnostic(diagnostics, action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        addDiagnosticError(diagnostics, error);
+    }
+}
+export function addDiagnosticError(diagnostics, error, outcomeKey, checkKey) {
+    const message = error instanceof Error ? error.message : String(error);
+    const rows = message.startsWith("delivery_contract_preflight_failed:\n")
+        ? message.split(/\r?\n/u).slice(1)
+        : [message];
+    for (const row of rows) {
+        const code = diagnosticCode(row);
+        const refs = diagnosticRefs(code, row);
+        const repairHint = diagnosticRepairHint(code);
+        diagnostics.push({
+            level: "error",
+            code,
+            message: row,
+            ...(outcomeKey ? { outcome_key: outcomeKey } : {}),
+            ...(checkKey ? { check_key: checkKey } : {}),
+            ...(refs.length ? { refs } : {}),
+            ...(repairHint ? { repair_hint: repairHint } : {}),
+        });
+    }
+}
+export function normalizeAuthoringDiagnostics(diagnostics) {
+    const normalized = [];
+    const positions = new Map();
+    for (const diagnostic of diagnostics) {
+        const refs = diagnostic.refs?.length
+            ? [...new Set(diagnostic.refs)].sort()
+            : undefined;
+        const next = {
+            ...diagnostic,
+            ...(refs ? { refs } : {}),
+        };
+        delete next.occurrences;
+        delete next.diagnostic_id;
+        delete next.repair_group;
+        delete next.repair_priority;
+        delete next.blocked_by;
+        const key = JSON.stringify([
+            next.level,
+            next.code,
+            next.message,
+            next.outcome_key ?? null,
+            next.check_key ?? null,
+            next.refs ?? [],
+            next.repair_hint ?? null,
+        ]);
+        const position = positions.get(key);
+        if (position === undefined) {
+            positions.set(key, normalized.length);
+            normalized.push(next);
+            continue;
+        }
+        const existing = normalized[position];
+        existing.occurrences = (existing.occurrences ?? 1) + 1;
+    }
+    return applyDiagnosticRepairOrder(normalized);
+}
+function diagnosticCode(message) {
+    if (message.startsWith("delivery_contract_invalid:"))
+        return message.split(":")[1] || "delivery_contract_invalid";
+    return message.split(":")[0] || "authoring_preflight_error";
+}
+function diagnosticPayload(code, message) {
+    const parts = message.split(":");
+    if (message.startsWith("delivery_contract_invalid:"))
+        return parts.slice(2);
+    if (parts[0] === code)
+        return parts.slice(1);
+    return parts.slice(1);
+}
+function diagnosticRefs(code, message) {
+    const payload = diagnosticPayload(code, message).filter(Boolean);
+    switch (code) {
+        case "owner_context_ref_unknown":
+        case "path_outside_owner_boundary":
+        case "source_claim_anchor_not_found":
+        case "binding_carrier_path_not_found":
+        case "binding_carrier_outside_change_paths":
+        case "binding_target_not_found":
+        case "binding_target_outside_carrier":
+            return payload.slice(0, 2);
+        case "requirement_key_duplicate":
+        case "binding_key_duplicate":
+        case "control_key_duplicate":
+        case "obligation_key_duplicate":
+        case "forbidden_shortcut_key_duplicate":
+            return payload.slice(0, 2);
+        case "owner_path_globs_empty":
+            return payload.slice(0, 1);
+        case "product_claim_uncovered":
+        case "global_claim_uncovered":
+        case "source_claim_decision_required":
+            return payload.flatMap((value) => value.split(",")).filter(Boolean);
+        case "assertion_criterion_required":
+            return payload.length ? [payload.join(":")] : [];
+        default:
+            if (code.endsWith("_path_not_found"))
+                return payload.slice(0, 2);
+            return [];
+    }
+}
+function diagnosticRepairHint(code) {
+    switch (code) {
+        case "owner_context_ref_unknown":
+            return "Add the existing Context path to task.context_refs or correct owner.context_refs; do not invent a Context owner.";
+        case "requirement_key_duplicate":
+        case "binding_key_duplicate":
+        case "control_key_duplicate":
+        case "obligation_key_duplicate":
+        case "forbidden_shortcut_key_duplicate":
+            return "Remove an accidental duplicate or assign distinct stable keys while preserving each distinct semantic item.";
+        case "product_claim_uncovered":
+        case "global_claim_uncovered":
+            return "Add claim-bearing Assertion coverage for every required proof surface or correct the Claim mapping; do not weaken or delete the uncovered Claim.";
+        case "assertion_criterion_required":
+            return "Add a named falsifiable criterion that states what the Assertion accepts.";
+        case "source_claim_anchor_not_found":
+            return "Correct source_ref or add the matching non-rendering Source marker/anchor without rewriting the Source statement.";
+        case "source_claim_decision_required":
+            return "Resolve the stated product decision from the user or authoritative Source before Compile.";
+        default:
+            if (code.endsWith("_path_not_found"))
+                return "Create or correct the declared repository path, runner target or Binding carrier, then rerun Preflight.";
+            return null;
+    }
+}

package/dist/lib/long-task-authoring-preflight-repair-order.d.ts

@@ -0,0 +1,8 @@
+import type { AuthoringPreflightDiagnosticV1 } from "./long-task-authoring-preflight-types.js";
+/**
+ * Adds repair-order metadata only when a structural duplicate makes the
+ * identity of an uncovered Claim ambiguous. The structural diagnostic must be
+ * reviewed first, but the coverage finding is never treated as automatically
+ * resolved. No diagnostic is hidden, merged, reclassified or removed.
+ */
+export declare function applyDiagnosticRepairOrder(diagnostics: AuthoringPreflightDiagnosticV1[]): AuthoringPreflightDiagnosticV1[];

package/dist/lib/long-task-authoring-preflight-repair-order.js

@@ -0,0 +1,95 @@
+import { canonicalJson, sha256Hex } from "./strict-codec.js";
+const STRUCTURAL_BLOCKERS = new Set([
+    "requirement_key_duplicate",
+    "control_key_duplicate",
+    "obligation_key_duplicate",
+    "forbidden_shortcut_key_duplicate",
+]);
+const COVERAGE_FOLLOW_UPS = new Set([
+    "product_claim_uncovered",
+    "global_claim_uncovered",
+]);
+/**
+ * Adds repair-order metadata only when a structural duplicate makes the
+ * identity of an uncovered Claim ambiguous. The structural diagnostic must be
+ * reviewed first, but the coverage finding is never treated as automatically
+ * resolved. No diagnostic is hidden, merged, reclassified or removed.
+ */
+export function applyDiagnosticRepairOrder(diagnostics) {
+    const groups = diagnostics.map((diagnostic) => ({
+        diagnostic,
+        entity: repairEntity(diagnostic),
+    }));
+    const blockersByEntity = new Map();
+    for (const [index, item] of groups.entries()) {
+        if (!item.entity || !STRUCTURAL_BLOCKERS.has(item.diagnostic.code))
+            continue;
+        const blockers = blockersByEntity.get(item.entity) ?? [];
+        blockers.push({ index, id: stableDiagnosticId(item.diagnostic) });
+        blockersByEntity.set(item.entity, blockers);
+    }
+    const linkedBlockerIndexes = new Set();
+    const dependencies = new Map();
+    for (const [index, item] of groups.entries()) {
+        if (!item.entity || !COVERAGE_FOLLOW_UPS.has(item.diagnostic.code))
+            continue;
+        const blockers = blockersByEntity.get(item.entity);
+        if (!blockers?.length)
+            continue;
+        blockers.forEach((blocker) => linkedBlockerIndexes.add(blocker.index));
+        dependencies.set(index, [...new Set(blockers.map((blocker) => blocker.id))].sort());
+    }
+    return diagnostics.map((diagnostic, index) => {
+        const blockedBy = dependencies.get(index);
+        if (blockedBy)
+            return {
+                ...diagnostic,
+                diagnostic_id: stableDiagnosticId(diagnostic),
+                repair_group: groups[index].entity,
+                repair_priority: "dependent",
+                blocked_by: blockedBy,
+            };
+        if (linkedBlockerIndexes.has(index))
+            return {
+                ...diagnostic,
+                diagnostic_id: stableDiagnosticId(diagnostic),
+                repair_group: groups[index].entity,
+                repair_priority: "primary",
+            };
+        return diagnostic;
+    });
+}
+function stableDiagnosticId(diagnostic) {
+    return `diag-${sha256Hex(canonicalJson({
+        level: diagnostic.level,
+        code: diagnostic.code,
+        message: diagnostic.message,
+        outcome_key: diagnostic.outcome_key ?? null,
+        check_key: diagnostic.check_key ?? null,
+        refs: diagnostic.refs ?? [],
+        repair_hint: diagnostic.repair_hint ?? null,
+    })).slice(0, 16)}`;
+}
+function repairEntity(diagnostic) {
+    const refs = diagnostic.refs ?? [];
+    switch (diagnostic.code) {
+        case "requirement_key_duplicate":
+            return scopedClaim(refs, "requirement");
+        case "control_key_duplicate":
+            return scopedClaim(refs, "control");
+        case "obligation_key_duplicate":
+            return scopedClaim(refs, "obligation");
+        case "forbidden_shortcut_key_duplicate":
+            return scopedClaim(refs, "forbidden_shortcut");
+        case "product_claim_uncovered":
+            return refs.length === 1 ? refs[0] : null;
+        case "global_claim_uncovered":
+            return refs.length === 1 ? refs[0] : null;
+        default:
+            return null;
+    }
+}
+function scopedClaim(refs, kind) {
+    const [scope, key] = refs;
+    return scope && key ? `${scope}.${kind}.${key}` : null;
+}

package/dist/lib/long-task-authoring-preflight-types.d.ts

@@ -0,0 +1,46 @@
+import type { ClaimCoverageSummaryV2 } from "./long-task-delivery-types.js";
+export interface AuthoringPreflightDiagnosticV1 {
+    level: "error" | "decision_required" | "warning" | "info";
+    code: string;
+    message: string;
+    outcome_key?: string;
+    check_key?: string;
+    refs?: string[];
+    repair_hint?: string;
+    occurrences?: number;
+    diagnostic_id?: string;
+    repair_group?: string;
+    repair_priority?: "primary" | "dependent";
+    blocked_by?: string[];
+}
+export interface SourceCoverageV1 {
+    total: number;
+    resolved: number;
+    mapped_to_product_claims: number;
+    mapped_to_acceptance: number;
+    mapped_to_outcome_results: number;
+    mapped_to_global_constraints: number;
+    mapped_to_risk_facts: number;
+    mapped_to_external_confirmations: number;
+    decision_required: number;
+    unresolved: string[];
+}
+export interface AuthoringRevisionPreviewV1 {
+    active: boolean;
+    authority_revision: number | null;
+    contract_changed: boolean;
+    source_or_context_changed: boolean;
+    declared_authority_sections_changed: string[];
+}
+export interface AuthoringPreflightResultV1 {
+    schema_version: "long-task-authoring-preflight-v1";
+    status: "ready" | "not_ready";
+    would_create_authority_lock: boolean;
+    outcomes: string[];
+    source_coverage: SourceCoverageV1;
+    claim_coverage: ClaimCoverageSummaryV2;
+    revision_preview: AuthoringRevisionPreviewV1;
+    diagnostics: AuthoringPreflightDiagnosticV1[];
+}
+export declare function emptyClaimCoverage(): ClaimCoverageSummaryV2;
+export declare function emptyPreflightResult(diagnostics: AuthoringPreflightDiagnosticV1[]): AuthoringPreflightResultV1;

package/dist/lib/long-task-authoring-preflight-types.js

@@ -0,0 +1,38 @@
+export function emptyClaimCoverage() {
+    return {
+        claims_total: 0,
+        claims_covered: 0,
+        uncovered_claims: [],
+        claims_by_global: {},
+        claims_by_outcome: {},
+    };
+}
+export function emptyPreflightResult(diagnostics) {
+    return {
+        schema_version: "long-task-authoring-preflight-v1",
+        status: "not_ready",
+        would_create_authority_lock: false,
+        outcomes: [],
+        source_coverage: {
+            total: 0,
+            resolved: 0,
+            mapped_to_product_claims: 0,
+            mapped_to_acceptance: 0,
+            mapped_to_outcome_results: 0,
+            mapped_to_global_constraints: 0,
+            mapped_to_risk_facts: 0,
+            mapped_to_external_confirmations: 0,
+            decision_required: 0,
+            unresolved: [],
+        },
+        claim_coverage: emptyClaimCoverage(),
+        revision_preview: {
+            active: false,
+            authority_revision: null,
+            contract_changed: false,
+            source_or_context_changed: false,
+            declared_authority_sections_changed: [],
+        },
+        diagnostics,
+    };
+}

package/dist/lib/long-task-authoring-preflight.d.ts

@@ -0,0 +1,3 @@
+import { type AuthoringPreflightResultV1 } from "./long-task-authoring-preflight-types.js";
+export type { AuthoringPreflightDiagnosticV1, AuthoringPreflightResultV1, SourceCoverageV1, } from "./long-task-authoring-preflight-types.js";
+export declare function preflightDeliveryContract(workdirInput: string, projectRootInput?: string): Promise<AuthoringPreflightResultV1>;

package/dist/lib/long-task-authoring-preflight.js

@@ -0,0 +1,44 @@
+import path from "node:path";
+import { authoringRevisionPreview, loadAuthoringActiveAuthority, } from "./long-task-authoring-authority-preview.js";
+import { addAuthoringDiagnostics, addDiagnosticError, normalizeAuthoringDiagnostics, sourceCoverage, } from "./long-task-authoring-preflight-diagnostics.js";
+import { emptyClaimCoverage, emptyPreflightResult, } from "./long-task-authoring-preflight-types.js";
+import { validateContractForActivation } from "./long-task-activation-validation.js";
+import { parseDeliveryContractBundle } from "./long-task-delivery-parser.js";
+import { repositoryRoot } from "./long-task-workspace.js";
+export async function preflightDeliveryContract(workdirInput, projectRootInput = process.cwd()) {
+    const diagnostics = [];
+    const repository = await repositoryRoot(projectRootInput);
+    const workdir = path.resolve(workdirInput);
+    let parsed;
+    try {
+        parsed = await parseDeliveryContractBundle(workdir, repository, {
+            validate_structure: false,
+        });
+    }
+    catch (error) {
+        addDiagnosticError(diagnostics, error);
+        return emptyPreflightResult(normalizeAuthoringDiagnostics(diagnostics));
+    }
+    const contract = parsed.contract;
+    addAuthoringDiagnostics(contract, parsed, diagnostics);
+    const validation = await validateContractForActivation({
+        repository,
+        workdir,
+        contract,
+        mode: "collect",
+        diagnostics,
+    });
+    const active = await loadAuthoringActiveAuthority(repository, workdir, diagnostics);
+    const normalizedDiagnostics = normalizeAuthoringDiagnostics(diagnostics);
+    const ready = !normalizedDiagnostics.some((item) => item.level === "error" || item.level === "decision_required");
+    return {
+        schema_version: "long-task-authoring-preflight-v1",
+        status: ready ? "ready" : "not_ready",
+        would_create_authority_lock: active === null,
+        outcomes: contract.outcomes.map((outcome) => outcome.key),
+        source_coverage: sourceCoverage(contract),
+        claim_coverage: validation.claims?.summary ?? emptyClaimCoverage(),
+        revision_preview: authoringRevisionPreview(contract, validation.source_hashes, validation.source_items, validation.context_snapshot, active),
+        diagnostics: normalizedDiagnostics,
+    };
+}

package/dist/lib/long-task-authority-material-diff.d.ts

@@ -0,0 +1,17 @@
+import type { CompiledDeliveryContractV2, DeliveryContractV2, NextAuthorityMaterialsV2, SourceClaimV2 } from "./long-task-delivery-types.js";
+export interface AuthorityMaterialRevisionDiffV2 {
+    product_semantics_changed: string[];
+    global_semantics_changed: string[];
+    source_files_added: string[];
+    source_files_removed: string[];
+    source_files_changed: string[];
+    context_snapshot_mode_changed: boolean;
+    context_topology_changed: boolean;
+    context_files_added: string[];
+    context_files_removed: string[];
+    context_files_changed: string[];
+    reduction_reasons: string[];
+}
+export declare function authorityMaterialRevisionDiff(previous: CompiledDeliveryContractV2, nextMaterials: NextAuthorityMaterialsV2): AuthorityMaterialRevisionDiffV2;
+export declare function sourceClaimAdditions(beforeClaims: SourceClaimV2[], afterClaims: SourceClaimV2[]): string[];
+export declare function changedProductClaimSemantics(previous: CompiledDeliveryContractV2, next: DeliveryContractV2): string[];