project-tiny-context-harness 0.2.84 → 0.6.0

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

@@ -0,0 +1,214 @@
+import type { DeliveryCheckV2, DeliveryContractV2, DeliveryOutcomeV2, DeliveryRunnerV2, ProofSurface } from "./long-task-contract-types.js";
+import type { AuthorityHashesV2, ContextAuthoritySnapshotV2, InitialTaskBaseV2, NextAuthorityMaterialsV2, VerifierIdentityV2 } from "./long-task-authority-types.js";
+import type { EvidenceAdapter } from "./long-task-evidence-adapter-types.js";
+import type { EffectiveRiskLevel, RiskFactName } from "./long-task-risk-types.js";
+import type { CompiledSourceItemV2 } from "./long-task-source-authority-types.js";
+import type { WorkspaceManifestV2 } from "./long-task-workspace-runtime-types.js";
+export interface FrozenRunnerV2 extends DeliveryRunnerV2 {
+    executable: string;
+    executable_argv_prefix: string[];
+    resolved_cwd: string;
+    resolved_target: string;
+    definition_sha256: string;
+    frozen_files: Record<string, string>;
+    package_script: string | null;
+    execution_identity: string;
+}
+export interface CompiledCheckV2 extends Omit<DeliveryCheckV2, "runner"> {
+    internal_id: string;
+    outcome_key: string | null;
+    runner: FrozenRunnerV2;
+    evidence_adapter: EvidenceAdapter;
+    verification_input_hashes: Record<string, string>;
+    raw_execution_identity: string;
+}
+export interface ProductClaimV2 {
+    id: string;
+    outcome_key: string;
+    local_key: string;
+    kind: "result" | "requirement" | "control" | "non_completing" | "obligation" | "forbidden_shortcut";
+    required_proof_surfaces: ProofSurface[];
+}
+export interface GlobalClaimV2 {
+    id: string;
+    local_key: string;
+    kind: "global_non_goal" | "global_constraint" | "global_forbidden_shortcut";
+    required_polarity: "any" | "negative";
+}
+export interface ClaimProofV2 {
+    check_key: string;
+    assertion_key: string | null;
+    polarity: "positive" | "negative" | "population" | "counterfactual";
+    proof_surface: ProofSurface;
+}
+export interface ClaimCoverageSummaryV2 {
+    claims_total: number;
+    claims_covered: number;
+    uncovered_claims: string[];
+    claims_by_global: Record<string, {
+        covered: boolean;
+        proofs: ClaimProofV2[];
+    }>;
+    claims_by_outcome: Record<string, Record<string, {
+        required_surfaces: ProofSurface[];
+        covered_surfaces: ProofSurface[];
+        missing_surfaces: ProofSurface[];
+        covered: boolean;
+        proofs: ClaimProofV2[];
+    }>>;
+}
+export interface CompiledOutcomeV2 extends Omit<DeliveryOutcomeV2, "acceptance"> {
+    internal_id: string;
+    generated_claims: ProductClaimV2[];
+    risk_reasons: RiskFactName[];
+    acceptance: Omit<DeliveryOutcomeV2["acceptance"], "checks"> & {
+        checks: CompiledCheckV2[];
+    };
+}
+export interface CompiledDeliveryContractV2 {
+    schema_version: "compiled-long-task-delivery-v2";
+    compiled_identity: string;
+    repository_root: string;
+    workdir: string;
+    contract_file: string;
+    contract_sha256: string;
+    contract_files: Record<string, string>;
+    source_hashes: Record<string, string>;
+    source_items: CompiledSourceItemV2[];
+    context_snapshot: ContextAuthoritySnapshotV2;
+    verifier_identity: VerifierIdentityV2;
+    effective_risk: EffectiveRiskLevel;
+    risk_reasons: string[];
+    baseline_workspace: WorkspaceManifestV2;
+    initial_task_base: InitialTaskBaseV2;
+    authority_hashes: AuthorityHashesV2;
+    authority_materials: NextAuthorityMaterialsV2;
+    authority_revision: number;
+    claim_coverage: ClaimCoverageSummaryV2;
+    task: DeliveryContractV2["task"];
+    risk: DeliveryContractV2["risk"];
+    source_claims: DeliveryContractV2["source_claims"];
+    global: Omit<DeliveryContractV2["global"], "acceptance"> & {
+        acceptance: {
+            checks: CompiledCheckV2[];
+            counterfactual_controls: DeliveryContractV2["global"]["acceptance"]["counterfactual_controls"];
+            external_confirmations: DeliveryContractV2["global"]["acceptance"]["external_confirmations"];
+        };
+    };
+    outcomes: CompiledOutcomeV2[];
+}
+export interface LongTaskFindingV2 {
+    code: string;
+    outcome_key: string | null;
+    check_key: string | null;
+    source_claim_keys?: string[];
+    source_target_refs?: string[];
+    claim_keys?: string[];
+    assertion_key?: string;
+    binding_ref?: string;
+    owning_outcome_key?: string;
+    criterion?: string;
+    observation?: string;
+    owner_paths?: string[];
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+    next_action: string;
+}
+export type CheckExecutionStatusV2 = "passed" | "assertion_failed" | "test_failed" | "blocked_external" | "infrastructure_error" | "invalid_evidence";
+export interface AssertionResultV2 {
+    key: string;
+    criterion?: string;
+    polarity: "positive" | "negative";
+    passed: boolean;
+    claims: string[];
+    observation: string;
+    status: "passed" | "observation_missing" | "observation_type_mismatch" | "assertion_value_mismatch";
+    expected?: unknown;
+    actual?: unknown;
+}
+export interface RawCommandExecutionV2 {
+    raw_execution_identity: string;
+    execution_identity: string;
+    execution_status: "completed" | "blocked_external" | "infrastructure_error" | "invalid_evidence";
+    exit_code: number;
+    observations: Record<string, unknown>;
+    stdout_sha256: string;
+    stderr_sha256: string;
+    attempts: number;
+    duration_ms: number;
+    error: string | null;
+}
+export interface CheckExecutionResultV2 {
+    internal_id: string;
+    outcome_key: string | null;
+    check_key: string;
+    status: CheckExecutionStatusV2;
+    evidence_adapter: EvidenceAdapter;
+    execution_identity: string;
+    assertion_results: AssertionResultV2[];
+    observations: Record<string, unknown>;
+    artifact_hashes: Record<string, string>;
+    claim_proofs: ClaimProofV2[];
+    findings: LongTaskFindingV2[];
+    attempts: number;
+    duration_ms: number;
+}
+export interface ProgressRecordV2 {
+    schema_version: "long-task-progress-record-v2";
+    compiled_identity: string;
+    outcome_authority_hash: string;
+    check_identity: string;
+    check_internal_id: string;
+    outcome_key: string | null;
+    check_key: string;
+    runner_verifier_identity: string;
+    relevant_context_identity: string;
+    resolved_input_path_hashes: Record<string, string>;
+    binding_carrier_path_hashes: Record<string, string>;
+    dependency_interface_identities: Record<string, string>;
+    result: CheckExecutionStatusV2;
+    check_result: CheckExecutionResultV2;
+    findings: LongTaskFindingV2[];
+    completed_at: string;
+}
+export interface TargetedVerificationResultV2 {
+    schema_version: "long-task-targeted-progress-v2";
+    compiled_identity: string;
+    snapshot_sha256: string;
+    acceptance_authorized: false;
+    selected_outcome: string | null;
+    selected_check: string | null;
+    updated_progress_records: string[];
+    check_results: CheckExecutionResultV2[];
+    findings: LongTaskFindingV2[];
+    completed_at: string;
+}
+export type OutcomeStatusV2 = "unverified" | "progress_passing" | "progress_failing" | "progress_stale" | "blocked_external";
+export interface FinalReceiptV2 {
+    schema_version: "long-task-final-receipt-v2";
+    receipt_sha256: string;
+    authority_scope: "audit_only";
+    reusable_for_acceptance: false;
+    workflow_status: "machine_accepted" | "machine_accepted_external_pending" | "needs_work" | "blocked_external";
+    compiled_identity: string;
+    contract_sha256: string;
+    snapshot_sha256: string;
+    git_head: string;
+    git_tree: string;
+    source_hashes: Record<string, string>;
+    context_hashes: Record<string, string>;
+    verifier_identity: VerifierIdentityV2;
+    check_results: CheckExecutionResultV2[];
+    outcome_results: Record<string, "passed" | "failed" | "blocked_external">;
+    external_confirmations: DeliveryContractV2["global"]["acceptance"]["external_confirmations"];
+    findings: LongTaskFindingV2[];
+    snapshot_preparation_ms: number;
+    started_at: string;
+    completed_at: string;
+}
+export type StrictRiskObligationV2 = {
+    outcome_key: string;
+    risk_fact: RiskFactName;
+    obligations: string[];
+};

package/dist/lib/long-task-runtime-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,17 @@
+export type Shape = Record<string, unknown>;
+export declare function object(value: unknown, label: string, required: string[], optional?: string[]): Shape;
+export declare function array(value: unknown, label: string): unknown[];
+export declare function string(value: unknown, label: string): string;
+export declare function text(value: unknown, label: string): string;
+export declare function strings(value: unknown, label: string): string[];
+export declare function repositoryFile(value: unknown, label: string): string;
+export declare function repositoryFiles(value: unknown, label: string): string[];
+export declare function repositoryPattern(value: unknown, label: string): string;
+export declare function repositoryPatterns(value: unknown, label: string): string[];
+export declare function repositoryCwd(value: unknown, label: string): string;
+export declare function repositorySourceRef(value: unknown, label: string): string;
+export declare function literal<T extends string>(value: unknown, allowed: readonly T[], label: string): T;
+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 function fail(label: string, message: string): never;

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

@@ -0,0 +1,81 @@
+import { normalizeRepositoryCwd, normalizeRepositoryFile, parseRepositoryPattern, } from "./long-task-paths.js";
+export function object(value, label, required, optional = []) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail(label, "must be an object");
+    const row = value;
+    const allowed = new Set([...required, ...optional]);
+    const unknown = Object.keys(row).filter((name) => !allowed.has(name));
+    if (unknown.length)
+        fail(label, `unknown keys: ${unknown.join(",")}`);
+    const missing = required.filter((name) => !(name in row));
+    if (missing.length)
+        fail(label, `missing keys: ${missing.join(",")}`);
+    return row;
+}
+export function array(value, label) {
+    if (!Array.isArray(value))
+        fail(label, "must be an array");
+    return value;
+}
+export function string(value, label) {
+    if (typeof value !== "string" || !value.trim())
+        fail(label, "must be a non-empty string");
+    return value;
+}
+export function text(value, label) {
+    if (typeof value !== "string")
+        fail(label, "must be a string");
+    return value;
+}
+export function strings(value, label) {
+    return array(value, label).map((item, index) => string(item, `${label}[${index}]`));
+}
+export function repositoryFile(value, label) {
+    return normalizeRepositoryFile(string(value, label), label);
+}
+export function repositoryFiles(value, label) {
+    return array(value, label).map((item, index) => repositoryFile(item, `${label}[${index}]`));
+}
+export function repositoryPattern(value, label) {
+    return parseRepositoryPattern(string(value, label), label).normalized;
+}
+export function repositoryPatterns(value, label) {
+    return array(value, label).map((item, index) => repositoryPattern(item, `${label}[${index}]`));
+}
+export function repositoryCwd(value, label) {
+    return normalizeRepositoryCwd(string(value, label), label);
+}
+export function repositorySourceRef(value, label) {
+    const sourceRef = string(value, label);
+    const [file, anchor, ...extra] = sourceRef.split("#");
+    if (!file || extra.length || (anchor !== undefined && !anchor))
+        fail(label, "source_claim_ref_invalid");
+    const normalized = normalizeRepositoryFile(file, `${label}.file`);
+    return anchor === undefined ? normalized : `${normalized}#${anchor}`;
+}
+export function literal(value, allowed, label) {
+    if (typeof value !== "string" || !allowed.includes(value))
+        fail(label, `must be one of ${allowed.join(",")}`);
+    return value;
+}
+export function key(value, label) {
+    const result = string(value, label);
+    if (!/^[a-z0-9][a-z0-9-]*$/u.test(result))
+        fail(label, "must match ^[a-z0-9][a-z0-9-]*$");
+    return result;
+}
+export function nullable(value, parser) {
+    return value === null ? null : parser(value);
+}
+export const PROOF_SURFACES = [
+    "ui_browser",
+    "runtime_behavior",
+    "api_contract",
+    "data_state",
+    "security_boundary",
+    "population_coverage",
+    "implementation_structure",
+];
+export function fail(label, message) {
+    throw new Error(`delivery_contract_invalid:${label}:${message}`);
+}

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

@@ -0,0 +1,13 @@
+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 interface CompiledSourceItemV2 {
+    key: string;
+    kind: SourceItemKind;
+    source_path: string;
+    normalized_text: string;
+    text_sha256: string;
+    risk_semantics?: {
+        fact: RiskFactName;
+        affected_outcome: string;
+    };
+}

package/dist/lib/long-task-source-authority-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,5 @@
+import type { DeliveryContractV2 } from "./long-task-delivery-types.js";
+import type { compileProductClaimCoverage } from "./long-task-claims.js";
+export declare function validateSourceClaimMappings(contract: DeliveryContractV2, compiledClaims: ReturnType<typeof compileProductClaimCoverage>, report?: ValidationReporter): void;
+type ValidationReporter = (message: string) => void;
+export {};

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

@@ -0,0 +1,96 @@
+import { resolveAcceptanceAssertion } from "./long-task-acceptance-reference.js";
+import { fail } from "./long-task-delivery-shape.js";
+export function validateSourceClaimMappings(contract, compiledClaims, report) {
+    validateSourcePresence(contract, report);
+    const sources = new Set(contract.task.source_paths);
+    const productClaims = new Set(Object.values(compiledClaims.by_outcome)
+        .flat()
+        .map((claim) => claim.id));
+    const globalClaims = new Map(compiledClaims.by_global.map((claim) => [claim.local_key, claim]));
+    const coveredGlobalClaims = new Set(Object.entries(compiledClaims.summary.claims_by_global)
+        .filter(([, value]) => value.covered)
+        .map(([key]) => key));
+    const forbiddenPaths = new Set(contract.global.technical.forbidden_paths.map((item) => `forbidden_path.${item.key}`));
+    const outcomeResults = new Set(contract.outcomes.map((outcome) => `${outcome.key}.result`));
+    const externalConfirmations = new Set(contract.global.acceptance.external_confirmations.map((item) => item.key));
+    for (const claim of contract.source_claims) {
+        validateSourceReference(claim.key, claim.source_ref, sources, report);
+        const disposition = claim.disposition;
+        if ("refs" in disposition && !disposition.refs.length)
+            issue(report, "source_claim_disposition_refs_empty", claim.key);
+        if (disposition.type === "claim")
+            for (const reference of disposition.refs) {
+                if (reference.endsWith(".result"))
+                    issue(report, "source_claim_result_overcompression", `${claim.key}:${reference}`);
+                if (!productClaims.has(reference))
+                    issue(report, "source_claim_product_ref_unknown", `${claim.key}:${reference}`);
+            }
+        if (disposition.type === "acceptance") {
+            if (disposition.refs.length !== 1)
+                issue(report, "source_claim_acceptance_ref_count", claim.key);
+            const reference = disposition.refs[0];
+            const resolved = resolveAcceptanceAssertion(contract, reference);
+            if (!resolved)
+                issue(report, "source_claim_acceptance_ref_unknown", `${claim.key}:${reference}`);
+            else if (resolved.scope === "outcome" &&
+                (!resolved.assertion.claims.length ||
+                    resolved.assertion.claims.every((item) => item === "result")))
+                issue(report, "source_claim_acceptance_result_only", `${claim.key}:${reference}`);
+            else if (resolved.scope === "global" && !resolved.assertion.claims.length)
+                issue(report, "source_claim_acceptance_global_claim_required", `${claim.key}:${reference}`);
+        }
+        if (disposition.type === "outcome_result" &&
+            !outcomeResults.has(disposition.ref))
+            issue(report, "source_claim_outcome_result_ref_unknown", `${claim.key}:${disposition.ref}`);
+        if (disposition.type === "external_confirmation")
+            validateRefs(claim.key, disposition.refs, externalConfirmations, "source_claim_external_confirmation_ref_unknown", report);
+        if (disposition.type === "global_constraint")
+            validateGlobalRefs(claim.key, disposition.refs, forbiddenPaths, globalClaims, coveredGlobalClaims, report);
+        if (disposition.type === "risk_fact")
+            validateRiskRefs(contract, claim.key, disposition.refs, report);
+    }
+}
+function validateSourcePresence(contract, report) {
+    if (!contract.task.source_paths.length || !contract.source_claims.length)
+        issue(report, "source_authority_required", "source_paths and source_claims must be non-empty");
+}
+function validateRiskRefs(contract, claimKey, refs, report) {
+    for (const reference of refs) {
+        const separator = reference.indexOf(":");
+        const fact = reference.slice(0, separator);
+        const outcome = reference.slice(separator + 1);
+        if (separator <= 0 ||
+            !outcome ||
+            !Object.hasOwn(contract.risk.facts, fact) ||
+            !contract.risk.facts[fact].includes(outcome))
+            issue(report, "source_claim_risk_fact_ref_unknown", `${claimKey}:${reference}`);
+    }
+}
+function validateSourceReference(key, sourceRef, sources, report) {
+    const [sourceFile, anchor, ...extra] = sourceRef.split("#");
+    if (!sourceFile || extra.length || (anchor !== undefined && !anchor))
+        issue(report, "source_claim_ref_invalid", `${key}:${sourceRef}`);
+    if (!sources.has(sourceFile))
+        issue(report, "source_claim_ref_unknown", `${key}:${sourceRef}`);
+}
+function validateRefs(claimKey, refs, known, code, report) {
+    for (const reference of refs)
+        if (!known.has(reference))
+            issue(report, code, `${claimKey}:${reference}`);
+}
+function validateGlobalRefs(claimKey, refs, forbiddenPaths, globalClaims, coveredGlobalClaims, report) {
+    for (const reference of refs)
+        if (reference.startsWith("forbidden_path.")) {
+            if (!forbiddenPaths.has(reference))
+                issue(report, "source_claim_global_ref_unknown", `${claimKey}:${reference}`);
+        }
+        else if (!globalClaims.has(reference))
+            issue(report, "source_claim_global_ref_unknown", `${claimKey}:${reference}`);
+        else if (!coveredGlobalClaims.has(reference))
+            issue(report, "source_claim_global_ref_uncovered", `${claimKey}:${reference}`);
+}
+function issue(report, code, detail) {
+    if (!report)
+        fail(code, detail);
+    report(`delivery_contract_invalid:${code}:${detail}`);
+}

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

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

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

@@ -0,0 +1,57 @@
+import { resolveAcceptanceAssertion } from "./long-task-acceptance-reference.js";
+import { normalizeSourceItemText } from "./long-task-source-item-parser.js";
+export function validateSourceContinuity(contract, items, report) {
+    const itemByKey = new Map(items.map((item) => [item.key, item]));
+    const claimByKey = new Map(contract.source_claims.map((claim) => [claim.key, claim]));
+    for (const claim of contract.source_claims) {
+        const item = itemByKey.get(claim.key);
+        if (!item) {
+            issue(report, `source_claim_item_unknown:${claim.key}`);
+            continue;
+        }
+        const sourcePath = claim.source_ref.split("#")[0];
+        if (sourcePath !== item.source_path)
+            issue(report, `source_claim_item_file_mismatch:${claim.key}:${sourcePath}:${item.source_path}`);
+        if (normalizeSourceItemText(claim.statement) !== item.normalized_text)
+            issue(report, `source_claim_statement_mismatch:${claim.key}`);
+        validateDispositionKind(claim, item.kind, report);
+        if (claim.disposition.type === "acceptance") {
+            const resolved = resolveAcceptanceAssertion(contract, claim.disposition.refs[0]);
+            if (!resolved?.assertion.criterion ||
+                normalizeSourceItemText(resolved.assertion.criterion) !==
+                    item.normalized_text)
+                issue(report, `source_acceptance_criterion_mismatch:${claim.key}`);
+        }
+    }
+    for (const item of items)
+        if (!claimByKey.has(item.key))
+            issue(report, `source_item_unmapped:${item.key}`);
+}
+function validateDispositionKind(claim, kind, report) {
+    const allowed = new Set(kind === "outcome_result"
+        ? ["outcome_result"]
+        : kind === "technical_obligation"
+            ? ["claim", "global_constraint"]
+            : kind === "requirement" ||
+                kind === "control" ||
+                kind === "non_completing"
+                ? ["claim"]
+                : kind === "acceptance"
+                    ? ["acceptance"]
+                    : kind === "non_goal"
+                        ? ["global_constraint"]
+                        : kind === "forbidden_shortcut"
+                            ? ["claim", "global_constraint"]
+                            : kind === "risk_fact"
+                                ? ["risk_fact"]
+                                : kind === "external_confirmation"
+                                    ? ["external_confirmation"]
+                                    : ["decision_required"]);
+    if (!allowed.has(claim.disposition.type))
+        issue(report, `source_item_disposition_mismatch:${claim.key}:${kind}:${claim.disposition.type}`);
+}
+function issue(report, message) {
+    if (!report)
+        throw new Error(message);
+    report(message);
+}

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

@@ -0,0 +1,2 @@
+import type { CompiledSourceItemV2 } from "./long-task-delivery-types.js";
+export declare function compileSourceInventory(repository: string, sourcePaths: string[]): Promise<CompiledSourceItemV2[]>;

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

@@ -0,0 +1,21 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { assertProtectedRepositoryFile } from "./long-task-protected-files.js";
+import { parseSourceItems } from "./long-task-source-item-parser.js";
+export async function compileSourceInventory(repository, sourcePaths) {
+    const items = [];
+    const seen = new Set();
+    for (const [index, relative] of sourcePaths.entries()) {
+        const file = await assertProtectedRepositoryFile(repository, path.resolve(repository, ...relative.split("/")), `source[${index}]`);
+        const parsed = parseSourceItems(relative, await readFile(file, "utf8"));
+        if (!parsed.length)
+            throw new Error(`source_file_material_item_required:${relative}`);
+        for (const item of parsed) {
+            if (seen.has(item.key))
+                throw new Error(`source_item_key_duplicate:${item.key}`);
+            seen.add(item.key);
+            items.push(item);
+        }
+    }
+    return items.sort((left, right) => left.key.localeCompare(right.key));
+}

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

@@ -0,0 +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;

package/dist/lib/long-task-source-item-parser.js

@@ -0,0 +1,112 @@
+import { RISK_FACT_NAMES } from "./long-task-risk-types.js";
+import { sha256Hex } from "./strict-codec.js";
+const KINDS = new Set([
+    "outcome_result",
+    "requirement",
+    "control",
+    "acceptance",
+    "technical_obligation",
+    "non_completing",
+    "non_goal",
+    "forbidden_shortcut",
+    "risk_fact",
+    "external_confirmation",
+    "decision",
+]);
+const RISK_FACTS = new Set(RISK_FACT_NAMES);
+const START = /^\s*<!--\s*ty-source-item:start\s+(.+?)\s*-->\s*$/u;
+const END = /^\s*<!--\s*ty-source-item:end\s*-->\s*$/u;
+export function parseSourceItems(sourcePath, content) {
+    const items = [];
+    const seen = new Set();
+    let open = null;
+    const lines = content.replace(/\r\n?/gu, "\n").split("\n");
+    for (const [index, line] of lines.entries()) {
+        const start = START.exec(line);
+        if (start) {
+            if (open)
+                throw new Error(`source_item_nested_or_overlapping:${sourcePath}:${open.key}:${index + 1}`);
+            const marker = parseStartMarker(sourcePath, index + 1, start[1]);
+            open = { ...marker, lines: [], line: index + 1 };
+            continue;
+        }
+        if (END.test(line)) {
+            if (!open)
+                throw new Error(`source_item_end_without_start:${sourcePath}:${index + 1}`);
+            const normalizedText = normalizeSourceItemText(open.lines.join("\n"));
+            if (!normalizedText)
+                throw new Error(`source_item_empty:${sourcePath}:${open.key}`);
+            if (seen.has(open.key))
+                throw new Error(`source_item_key_duplicate:${open.key}`);
+            seen.add(open.key);
+            items.push({
+                key: open.key,
+                kind: open.kind,
+                source_path: sourcePath,
+                normalized_text: normalizedText,
+                text_sha256: sha256Hex(normalizedText),
+                ...(open.risk_semantics ? { risk_semantics: open.risk_semantics } : {}),
+            });
+            open = null;
+            continue;
+        }
+        if (line.includes("ty-source-item:start") ||
+            line.includes("ty-source-item:end"))
+            throw new Error(`source_item_marker_invalid:${sourcePath}:${index + 1}`);
+        if (open)
+            open.lines.push(line);
+    }
+    if (open)
+        throw new Error(`source_item_unclosed:${sourcePath}:${open.key}:${open.line}`);
+    return items;
+}
+function parseStartMarker(sourcePath, line, declaration) {
+    const attributes = new Map();
+    for (const token of declaration.trim().split(/\s+/u)) {
+        const match = /^([a-z_]+)=([^\s=]+)$/u.exec(token);
+        if (!match)
+            throw new Error(`source_item_marker_invalid:${sourcePath}:${line}`);
+        if (attributes.has(match[1]))
+            throw new Error(`source_item_marker_attribute_duplicate:${sourcePath}:${line}:${match[1]}`);
+        attributes.set(match[1], match[2]);
+    }
+    for (const name of attributes.keys())
+        if (!["key", "kind", "fact", "outcome"].includes(name))
+            throw new Error(`source_item_marker_attribute_unknown:${sourcePath}:${line}:${name}`);
+    const key = attributes.get("key") ?? "";
+    const kind = (attributes.get("kind") ?? "");
+    if (!/^[a-z0-9][a-z0-9-]*$/u.test(key) || !KINDS.has(kind))
+        throw new Error(`source_item_marker_invalid:${sourcePath}:${line}`);
+    const fact = attributes.get("fact");
+    const outcome = attributes.get("outcome");
+    if (kind !== "risk_fact") {
+        if (fact !== undefined || outcome !== undefined)
+            throw new Error(`source_item_marker_attributes_forbidden:${sourcePath}:${key}:${kind}`);
+        return { key, kind };
+    }
+    if (!fact || !outcome)
+        throw new Error(`source_item_risk_semantics_required:${sourcePath}:${key}`);
+    if (!RISK_FACTS.has(fact))
+        throw new Error(`source_item_risk_fact_invalid:${sourcePath}:${key}:${fact}`);
+    if (!/^[a-z0-9][a-z0-9-]*$/u.test(outcome))
+        throw new Error(`source_item_risk_outcome_invalid:${sourcePath}:${key}:${outcome}`);
+    return {
+        key,
+        kind,
+        risk_semantics: {
+            fact: fact,
+            affected_outcome: outcome,
+        },
+    };
+}
+export function normalizeSourceItemText(value) {
+    const lines = value
+        .replace(/\r\n?/gu, "\n")
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/gu, ""));
+    while (lines.length && !lines[0].trim())
+        lines.shift();
+    while (lines.length && !lines.at(-1).trim())
+        lines.pop();
+    return lines.join("\n");
+}

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

@@ -0,0 +1,2 @@
+import type { SourceClaimV2 } from "./long-task-delivery-types.js";
+export declare function parseSourceClaims(value: unknown, label: string): SourceClaimV2[];