project-tiny-context-harness 0.2.84 → 0.6.0

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

@@ -0,0 +1,56 @@
+import { array, fail, key, literal, object, repositorySourceRef, string, strings, } from "./long-task-shape-primitives.js";
+export function parseSourceClaims(value, label) {
+    return array(value, label).map((item, index) => {
+        const itemLabel = `${label}[${index}]`;
+        const row = object(item, itemLabel, [
+            "key",
+            "source_ref",
+            "statement",
+            "disposition",
+        ]);
+        const disposition = object(row.disposition, `${itemLabel}.disposition`, ["type"], ["refs", "ref", "reason"]);
+        const type = literal(disposition.type, [
+            "claim",
+            "acceptance",
+            "outcome_result",
+            "global_constraint",
+            "risk_fact",
+            "external_confirmation",
+            "out_of_scope",
+            "decision_required",
+        ], `${itemLabel}.disposition.type`);
+        if (type === "out_of_scope")
+            fail("out_of_scope_requires_non_goal_or_decision", key(row.key, `${itemLabel}.key`));
+        const claimKey = key(row.key, `${itemLabel}.key`);
+        return {
+            key: claimKey,
+            source_ref: repositorySourceRef(row.source_ref, `${itemLabel}.source_ref`),
+            statement: string(row.statement, `${itemLabel}.statement`),
+            disposition: type === "decision_required"
+                ? {
+                    type,
+                    reason: string(disposition.reason, `${itemLabel}.disposition.reason`),
+                }
+                : type === "outcome_result"
+                    ? {
+                        type,
+                        ref: string(disposition.ref, `${itemLabel}.disposition.ref`),
+                    }
+                    : type === "acceptance"
+                        ? {
+                            type,
+                            refs: acceptanceRefs(disposition.refs, `${itemLabel}.disposition.refs`),
+                        }
+                        : {
+                            type,
+                            refs: strings(disposition.refs, `${itemLabel}.disposition.refs`),
+                        },
+        };
+    });
+}
+function acceptanceRefs(value, label) {
+    const refs = strings(value, label);
+    if (refs.length !== 1)
+        fail("source_claim_acceptance_ref_count", label);
+    return [refs[0]];
+}

package/dist/lib/long-task-source-target-continuity.d.ts

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

package/dist/lib/long-task-source-target-continuity.js

@@ -0,0 +1,80 @@
+import { resolveAcceptanceAssertion } from "./long-task-acceptance-reference.js";
+import { buildCanonicalSourceTargetIndex, sourceKindForTarget, } from "./long-task-source-target-index.js";
+export function validateSourceTargetContinuity(contract, items, report) {
+    const itemByKey = new Map(items.map((item) => [item.key, item]));
+    const targets = buildCanonicalSourceTargetIndex(contract);
+    const owners = new Map();
+    const sourceBackedOutcomeClaims = new Set();
+    const sourceBackedGlobalClaims = new Set();
+    const acceptanceBindings = [];
+    for (const claim of contract.source_claims) {
+        const item = itemByKey.get(claim.key);
+        if (!item || claim.disposition.type === "decision_required")
+            continue;
+        const refs = dispositionRefs(claim.disposition);
+        if (refs.length !== 1) {
+            issue(report, `source_claim_target_ref_count:${claim.key}:${refs.length}`);
+            continue;
+        }
+        const ref = refs[0];
+        const target = targets.get(ref);
+        if (!target || sourceKindForTarget(target) !== item.kind) {
+            issue(report, `source_target_kind_mismatch:${claim.key}:${item.kind}:${target ? sourceKindForTarget(target) : "unknown"}:${ref}`);
+            continue;
+        }
+        if (item.kind === "risk_fact" &&
+            (target.risk_fact !== item.risk_semantics?.fact ||
+                target.affected_outcome !== item.risk_semantics?.affected_outcome)) {
+            issue(report, `source_risk_target_mismatch:${claim.key}:${item.risk_semantics?.fact ?? "missing"}:${item.risk_semantics?.affected_outcome ?? "missing"}:${ref}`);
+            continue;
+        }
+        if (target.normalized_text !== undefined &&
+            target.normalized_text !== item.normalized_text) {
+            issue(report, `source_target_statement_mismatch:${claim.key}:${ref}`);
+            continue;
+        }
+        const owner = owners.get(ref);
+        if (owner) {
+            issue(report, `source_target_already_owned:${claim.key}:${ref}:${owner}`);
+            continue;
+        }
+        owners.set(ref, claim.key);
+        if (target.outcome_key &&
+            [
+                "requirement",
+                "control",
+                "technical_obligation",
+                "non_completing",
+                "forbidden_shortcut",
+            ].includes(target.kind))
+            sourceBackedOutcomeClaims.add(ref);
+        if (!target.outcome_key &&
+            ["global_constraint", "non_goal", "forbidden_shortcut"].includes(target.kind))
+            sourceBackedGlobalClaims.add(ref);
+        if (target.kind === "acceptance")
+            acceptanceBindings.push({ claim, target });
+    }
+    for (const { claim, target } of acceptanceBindings) {
+        const resolved = resolveAcceptanceAssertion(contract, target.ref);
+        const sourceBacked = resolved?.scope === "outcome" && target.outcome_key
+            ? resolved.assertion.claims.some((localKey) => localKey !== "result" &&
+                sourceBackedOutcomeClaims.has(`${target.outcome_key}.${localKey}`))
+            : resolved?.scope === "global"
+                ? resolved.assertion.claims.some((localKey) => sourceBackedGlobalClaims.has(localKey))
+                : false;
+        if (!sourceBacked)
+            issue(report, `source_acceptance_without_source_backed_claim:${claim.key}:${target.ref}`);
+    }
+}
+function dispositionRefs(disposition) {
+    if (disposition.type === "decision_required")
+        return [];
+    if (disposition.type === "outcome_result")
+        return [disposition.ref];
+    return disposition.refs;
+}
+function issue(report, message) {
+    if (!report)
+        throw new Error(message);
+    report(message);
+}

package/dist/lib/long-task-source-target-index.d.ts

@@ -0,0 +1,12 @@
+import type { DeliveryContractV2, SourceItemKind } from "./long-task-delivery-types.js";
+export interface CanonicalSourceTarget {
+    ref: string;
+    kind: "outcome_result" | "requirement" | "control" | "technical_obligation" | "non_completing" | "global_constraint" | "non_goal" | "forbidden_shortcut" | "acceptance" | "risk_fact" | "external_confirmation";
+    normalized_text?: string;
+    scope?: "global" | "outcome";
+    outcome_key?: string;
+    risk_fact?: keyof DeliveryContractV2["risk"]["facts"];
+    affected_outcome?: string;
+}
+export declare function buildCanonicalSourceTargetIndex(contract: DeliveryContractV2): Map<string, CanonicalSourceTarget>;
+export declare function sourceKindForTarget(target: CanonicalSourceTarget): SourceItemKind | null;

package/dist/lib/long-task-source-target-index.js

@@ -0,0 +1,76 @@
+import { normalizeSourceItemText } from "./long-task-source-item-parser.js";
+export function buildCanonicalSourceTargetIndex(contract) {
+    const targets = [];
+    for (const outcome of contract.outcomes) {
+        targets.push(target(`${outcome.key}.result`, "outcome_result", outcome.product.observable_result, outcome.key));
+        for (const requirement of outcome.product.requirements)
+            targets.push(target(`${outcome.key}.requirement.${requirement.key}`, "requirement", requirement.statement, outcome.key));
+        for (const control of outcome.product.controls)
+            for (const [field, value] of controlFields(control))
+                if (value.trim())
+                    targets.push(target(`${outcome.key}.control.${control.key}.${field}`, "control", value, outcome.key));
+        for (const obligation of outcome.technical.obligations)
+            targets.push(target(`${outcome.key}.obligation.${obligation.key}`, "technical_obligation", obligation.statement, outcome.key));
+        for (const item of outcome.product.non_completing_outcomes)
+            targets.push(target(`${outcome.key}.non_completing.${item.key}`, "non_completing", item.statement, outcome.key));
+        for (const shortcut of outcome.technical.forbidden_shortcuts)
+            targets.push(target(`${outcome.key}.forbidden_shortcut.${shortcut.key}`, "forbidden_shortcut", shortcut.statement, outcome.key));
+        for (const check of outcome.acceptance.checks)
+            for (const assertion of [
+                ...check.positive_assertions,
+                ...check.negative_assertions,
+            ])
+                targets.push(target(`${outcome.key}.${check.key}.${assertion.key}`, "acceptance", assertion.criterion, outcome.key, "outcome"));
+    }
+    for (const item of contract.global.product.non_goals)
+        targets.push(target(`non_goal.${item.key}`, "non_goal", item.statement));
+    for (const item of contract.global.technical.constraints)
+        targets.push(target(`constraint.${item.key}`, "global_constraint", item.statement));
+    for (const item of contract.global.technical.forbidden_shortcuts)
+        targets.push(target(`forbidden_shortcut.${item.key}`, "forbidden_shortcut", item.statement));
+    for (const check of contract.global.acceptance.checks)
+        for (const assertion of [
+            ...check.positive_assertions,
+            ...check.negative_assertions,
+        ])
+            targets.push(target(`GLOBAL.${check.key}.${assertion.key}`, "acceptance", assertion.criterion, undefined, "global"));
+    for (const [fact, outcomes] of Object.entries(contract.risk.facts))
+        for (const outcome of outcomes)
+            targets.push({
+                ref: `${fact}:${outcome}`,
+                kind: "risk_fact",
+                risk_fact: fact,
+                affected_outcome: outcome,
+            });
+    for (const item of contract.global.acceptance.external_confirmations)
+        targets.push(target(item.key, "external_confirmation", item.description));
+    return new Map(targets.map((item) => [item.ref, item]));
+}
+function target(ref, kind, text, outcomeKey, scope) {
+    return {
+        ref,
+        kind,
+        ...(text !== undefined
+            ? { normalized_text: normalizeSourceItemText(text) }
+            : {}),
+        ...(outcomeKey ? { outcome_key: outcomeKey } : {}),
+        ...(scope ? { scope } : {}),
+    };
+}
+function controlFields(control) {
+    return [
+        ["location", control.location],
+        ["trigger", control.trigger],
+        ["input", control.input],
+        ["loading", control.loading_state],
+        ["empty", control.empty_state],
+        ["success", control.success_state],
+        ["failure", control.failure_state],
+        ["feedback", control.feedback],
+    ];
+}
+export function sourceKindForTarget(target) {
+    return target.kind === "global_constraint"
+        ? "technical_obligation"
+        : target.kind;
+}

package/dist/lib/long-task-source-validation.d.ts

@@ -0,0 +1,3 @@
+import type { SourceClaimV2 } from "./long-task-delivery-types.js";
+export declare function validateSourceAnchors(repository: string, sourceClaims: SourceClaimV2[]): Promise<void>;
+export declare function markdownAnchors(content: string): Set<string>;

package/dist/lib/long-task-source-validation.js

@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryFile } from "./long-task-protected-files.js";
+export async function validateSourceAnchors(repository, sourceClaims) {
+    const anchorsByFile = new Map();
+    for (const [index, claim] of sourceClaims.entries()) {
+        const [relative, anchor] = claim.source_ref.split("#");
+        if (!anchor)
+            continue;
+        let anchors = anchorsByFile.get(relative);
+        if (!anchors) {
+            const file = await assertProtectedRepositoryFile(repository, path.resolve(repository, ...relative.split("/")), `source[${index}]`);
+            anchors = markdownAnchors(await readFile(file, "utf8"));
+            anchorsByFile.set(relative, anchors);
+        }
+        if (!anchors.has(anchor))
+            throw new Error(`source_claim_anchor_not_found:${claim.key}:${claim.source_ref}`);
+    }
+}
+export function markdownAnchors(content) {
+    const anchors = new Set();
+    const slugCounts = new Map();
+    for (const line of content.split(/\r?\n/u)) {
+        const heading = /^(?: {0,3})#{1,6}\s+(.+?)\s*#*\s*$/u.exec(line);
+        if (heading) {
+            const base = githubSlug(heading[1]);
+            if (base) {
+                const count = slugCounts.get(base) ?? 0;
+                anchors.add(count === 0 ? base : `${base}-${count}`);
+                slugCounts.set(base, count + 1);
+            }
+        }
+        for (const match of line.matchAll(/(?:\{#([A-Za-z0-9._:-]+)\}|(?:id|name)=["']([^"']+)["'])/gu))
+            anchors.add(match[1] ?? match[2]);
+    }
+    return anchors;
+}
+function githubSlug(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/<[^>]*>/gu, "")
+        .replace(/[^\p{L}\p{N}\s_-]/gu, "")
+        .replace(/\s+/gu, "-")
+        .replace(/-+/gu, "-");
+}

package/dist/lib/long-task-state.d.ts

@@ -0,0 +1,91 @@
+import type { AuthorityMaterialHashesV2, AuthorityHashesV2, CompiledDeliveryContractV2, FinalReceiptV2, InitialTaskBaseV2, NextAuthorityMaterialsV2, ProgressRecordV2, VerifierIdentityV2 } from "./long-task-delivery-types.js";
+export interface ActiveLongTaskAuthorityV3 {
+    schema_version: "active-long-task-authority-v3";
+    task_id: string;
+    repository_root: string;
+    worktree_identity: string;
+    workdir: string;
+    active_authority_identity: string;
+    authority_revision: number;
+    initial_task_base: InitialTaskBaseV2;
+    verifier_identity: VerifierIdentityV2;
+    activated_at: string;
+    authority_snapshot: CompiledDeliveryContractV2;
+    authority_snapshot_sha256: string;
+}
+export type CompiledCacheStatusV3 = "compiled_cache_matching" | "compiled_cache_missing_repairable" | "compiled_cache_mismatched_ignored";
+export interface ActiveAuthorityLoadResultV3 {
+    authority: ActiveLongTaskAuthorityV3 | null;
+    source: "none" | "active_authority_v3";
+    migrated: boolean;
+}
+export type ActiveAuthorityLockOperation = "commit" | "clear" | "abandon" | "migrate";
+export interface ActiveAuthorityIdentityExpectation {
+    task_id: string;
+    authority_revision: number;
+    compiled_identity: string;
+    worktree_identity?: string;
+}
+export interface ClearActiveBindingCasOptions extends ActiveAuthorityIdentityExpectation {
+    repository_root: string;
+    workdir: string;
+}
+export interface StagedCompiledDeliveryContractV2 {
+    publish(): Promise<void>;
+    discard(): Promise<void>;
+}
+export interface PendingAuthorityRevisionV2 {
+    schema_version: "long-task-authority-revision-pending-v2";
+    previous_hashes: AuthorityHashesV2;
+    next_hashes: AuthorityHashesV2;
+    previous_materials: NextAuthorityMaterialsV2;
+    next_materials: NextAuthorityMaterialsV2;
+    previous_material_hashes: AuthorityMaterialHashesV2;
+    next_material_hashes: AuthorityMaterialHashesV2;
+    changed_authority_sections: string[];
+    revision_diff: Record<string, unknown> & {
+        reduction_reasons: string[];
+    };
+    new_risk_floor: "standard" | "strict";
+    affected_outcomes_or_contracts: string[];
+    revision_identity: string;
+    created_at: string;
+}
+export declare function runtimePath(workdir: string, file?: string): string;
+export declare function worktreeIdentity(repositoryRoot: string): string;
+export declare function activeRecordPath(repositoryRoot: string): Promise<string>;
+export declare function activeAuthorityLockPath(repositoryRoot: string): Promise<string>;
+export declare function activeAuthorityLockExists(repositoryRoot: string): Promise<boolean>;
+export declare function withActiveAuthorityLock<T>(repositoryRoot: string, operation: ActiveAuthorityLockOperation, action: () => Promise<T>): Promise<T>;
+export declare function writeCompiledDeliveryContract(compiled: CompiledDeliveryContractV2): Promise<void>;
+export declare function stageCompiledDeliveryContract(compiled: CompiledDeliveryContractV2): Promise<StagedCompiledDeliveryContractV2>;
+export declare function readCompiledDeliveryContract(workdir: string): Promise<CompiledDeliveryContractV2>;
+export declare function loadActiveLongTaskAuthority(repositoryRoot: string, _options?: {
+    migrate_legacy?: boolean;
+}): Promise<ActiveAuthorityLoadResultV3>;
+export declare function loadActiveCompiledAuthority(repositoryRoot: string, workdir?: string, options?: {
+    migrate_legacy?: boolean;
+}): Promise<CompiledDeliveryContractV2 | null>;
+export declare function readActiveLongTaskBinding(repositoryRoot: string): Promise<ActiveLongTaskAuthorityV3 | null>;
+export declare function inspectCompiledCache(authority: ActiveLongTaskAuthorityV3): Promise<CompiledCacheStatusV3>;
+export declare function commitActiveAuthority(options: {
+    candidate: CompiledDeliveryContractV2;
+    expected_previous_identity: string | null;
+}): Promise<ActiveLongTaskAuthorityV3>;
+export declare function activateDeliveryContract(compiled: CompiledDeliveryContractV2): Promise<ActiveLongTaskAuthorityV3>;
+export declare function assertMatchingActiveBinding(compiled: CompiledDeliveryContractV2): Promise<ActiveLongTaskAuthorityV3>;
+export declare function writeProgressRecord(workdir: string, record: ProgressRecordV2): Promise<void>;
+export declare function readProgressRecords(workdir: string): Promise<Record<string, ProgressRecordV2>>;
+export declare function writePendingAuthorityRevision(workdir: string, pending: PendingAuthorityRevisionV2): Promise<void>;
+export declare function readPendingAuthorityRevision(workdir: string): Promise<PendingAuthorityRevisionV2 | null>;
+export declare function approvePendingAuthorityRevision(workdir: string, revision: string): Promise<void>;
+export declare function authorityRevisionApproved(workdir: string, revision: string): Promise<boolean>;
+export declare function clearAuthorityRevision(workdir: string): Promise<void>;
+export declare function invalidateDerivedProgress(workdir: string): Promise<void>;
+export declare function writeFinalReceipt(repositoryRoot: string, workdir: string, unsigned: Omit<FinalReceiptV2, "receipt_sha256">): Promise<FinalReceiptV2>;
+export declare function readFinalReceipt(_repositoryRoot: string, workdir: string): Promise<FinalReceiptV2 | null>;
+export declare function activeAuthorityIdentityMatches(authority: ActiveLongTaskAuthorityV3, expected: ActiveAuthorityIdentityExpectation): boolean;
+export declare function clearActiveBindingCas(options: ClearActiveBindingCasOptions): Promise<boolean>;
+export declare function abandonLongTaskState(repositoryRoot: string, workdir: string): Promise<void>;
+export declare function forceClearCorruptActiveState(repositoryRoot: string, workdir: string): Promise<void>;
+export declare function clearFinalReceipt(repositoryRoot: string, workdir: string): Promise<void>;