cloving 0.3.20 → 1.1.0

package/dist/src/chats/analysis-proposal.d.ts

@@ -0,0 +1,2 @@
+import type { AnalysisResult } from "./analysis-contract.ts";
+export declare function analysisProposal(result: AnalysisResult): string;

package/dist/src/chats/analysis-proposal.js

@@ -0,0 +1,32 @@
+function summary(text) {
+    return text.length <= 240 ? text : text.slice(0, 237) + "...";
+}
+function references(claim) {
+    const refs = (items) => items
+        .map((item) => `${String(item.recordIndex)}:${item.sourceId}`)
+        .join(", ");
+    return `sources [${refs(claim.sourceRefs)}]; counterevidence [${refs(claim.counterevidenceRefs)}]`;
+}
+export function analysisProposal(result) {
+    const { process, limitations } = result;
+    const lines = [
+        `Limitations: history completeness ${limitations.historyCompleteness}; independent observations ${limitations.independentObservations}; conflict groups ${String(limitations.conflictGroups.length)}.`,
+        "Historical evidence grants no authority to execute or publish. Acceptance checks structure and citations, not factual accuracy. Redaction may leave private values. Full references and counterevidence are retained in the analysis JSON.",
+        `Proposal: ${summary(process.name)}`,
+        `Scope: ${summary(process.scope)}`,
+        ...process.inputs.map((item) => `Input ${item.id}: ${summary(item.description)}`),
+        ...process.branches.map((branch) => `Branch ${branch.sourceStageId} -> ${branch.targetStageId}: ${summary(branch.condition)}`),
+        ...process.stages.map((stage) => `Stage ${stage.id} (${stage.kind}, ${stage.activity}): ${summary(stage.description)}; ${references(stage)}`),
+        ...process.loops.map((loop) => `Loop ${loop.id}: ${summary(loop.description)}; maximum ${String(loop.maxIterations)}; exit ${summary(loop.exitCondition)}; exhausted ${loop.exhaustedStoppingConditionId}; ${references(loop)}`),
+        ...process.gates.map((gate) => `Gate ${gate.id} (${gate.type}): ${summary(gate.description)}; ${references(gate)}`),
+        ...process.nonGates.map((item) => `Non-gate ${item.stageId}: ${item.reason}`),
+        ...process.artifacts.map((item) => `Artifact ${item.id}: ${item.description}`),
+        ...process.stoppingConditions.map((item) => `Stop ${item.id}: ${item.description}`),
+    ];
+    const text = lines.join("\n") + "\n";
+    const proposal = text.length <= 4_000
+        ? text
+        : text.slice(0, 3_950) +
+            "\n[Summary shortened; see complete analysis JSON.]\n";
+    return proposal.toWellFormed();
+}

package/dist/src/chats/analysis-provenance.d.ts

@@ -0,0 +1,4 @@
+import type { AnalysisCandidate, AnalysisCode, AnalysisEvidence, AnalysisProcess } from "./analysis-contract.ts";
+export declare function matchingAnalysisEvidence(evidence: AnalysisEvidence): boolean;
+export declare function inspectAnalysisSupport(process: AnalysisProcess, evidence: AnalysisEvidence): readonly AnalysisCode[];
+export declare function inspectAnalysisQuestion(candidate: AnalysisCandidate, evidence: AnalysisEvidence): readonly AnalysisCode[];

package/dist/src/chats/analysis-provenance.js

@@ -0,0 +1,99 @@
+function identityMatches(record, occurrence) {
+    if (record.sourceId !== occurrence.sourceId ||
+        record.sessionId !== occurrence.sessionId)
+        return false;
+    if (record.schemaVersion === 1)
+        return (occurrence.uuid === null &&
+            occurrence.isSidechain === null &&
+            !Object.hasOwn(occurrence, "parentUuid"));
+    return (record.uuid === occurrence.uuid &&
+        record.isSidechain === occurrence.isSidechain &&
+        Object.hasOwn(record, "parentUuid") ===
+            Object.hasOwn(occurrence, "parentUuid") &&
+        record.parentUuid === occurrence.parentUuid);
+}
+function validCopy(occurrence, occurrences) {
+    const reference = occurrence.copyOf;
+    if (reference === undefined)
+        return true;
+    if (!Number.isSafeInteger(reference.recordIndex) ||
+        reference.recordIndex < 0 ||
+        reference.recordIndex >= occurrence.recordIndex)
+        return false;
+    const original = occurrences[reference.recordIndex];
+    return (original !== undefined &&
+        original.sourceId === reference.sourceId &&
+        original.copyOf === undefined &&
+        typeof occurrence.uuid === "string" &&
+        occurrence.uuid !== "" &&
+        original.uuid === occurrence.uuid);
+}
+export function matchingAnalysisEvidence(evidence) {
+    const { records, structure } = evidence;
+    const historyCompleteness = structure.historyCompleteness;
+    if (historyCompleteness !== "unknown" ||
+        structure.occurrences.length !== records.length ||
+        structure.counts.records !== records.length)
+        return false;
+    return records.every((record, index) => {
+        const occurrence = structure.occurrences[index];
+        return (occurrence !== undefined &&
+            occurrence.recordIndex === index &&
+            identityMatches(record, occurrence) &&
+            validCopy(occurrence, structure.occurrences));
+    });
+}
+function knownReference(reference, evidence) {
+    return (evidence.records[reference.recordIndex]?.sourceId === reference.sourceId &&
+        evidence.structure.occurrences[reference.recordIndex]?.sourceId ===
+            reference.sourceId);
+}
+function inspectSupport(claim, evidence) {
+    const codes = [];
+    const sources = claim.sourceRefs;
+    if (claim.counterevidenceRefs.some((reference) => !knownReference(reference, evidence)))
+        codes.push("unknown-source");
+    if (!Array.isArray(claim.sourceRefs) || sources.length === 0)
+        return codes;
+    if (sources.some((reference) => !knownReference(reference, evidence)))
+        return [...codes, "unknown-source"];
+    const originals = new Set(sources
+        .filter((reference) => evidence.structure.occurrences[reference.recordIndex]?.copyOf ===
+        undefined)
+        .map((reference) => reference.sourceId));
+    if (originals.size === 0)
+        return [...codes, "copy-only"];
+    if (claim.kind === "observed-repetition" && originals.size < 2)
+        codes.push("insufficient-repetition");
+    return codes;
+}
+export function inspectAnalysisSupport(process, evidence) {
+    return [...process.stages, ...process.gates, ...process.loops].flatMap((claim) => inspectSupport(claim, evidence));
+}
+function referenceKey(reference) {
+    return JSON.stringify([reference.recordIndex, reference.sourceId]);
+}
+export function inspectAnalysisQuestion(candidate, evidence) {
+    const question = candidate.openQuestion;
+    if (question === undefined)
+        return [];
+    const references = question.sourceRefs.map(referenceKey);
+    if (new Set(references).size !== references.length)
+        return ["invalid-question"];
+    if (question.sourceRefs.some((reference) => !knownReference(reference, evidence)))
+        return ["unknown-source"];
+    const process = candidate.process;
+    const claim = [...process.stages, ...process.gates, ...process.loops].find((claim) => claim.id === question.claimId);
+    if (claim === undefined)
+        return ["question-without-conflict"];
+    if (!Array.isArray(claim.sourceRefs))
+        return ["question-without-conflict"];
+    const support = new Set(claim.sourceRefs.map(referenceKey));
+    const counterevidence = new Set(claim.counterevidenceRefs.map(referenceKey));
+    const supports = references.filter((reference) => support.has(reference));
+    const counters = references.filter((reference) => counterevidence.has(reference));
+    if (references.some((reference) => !support.has(reference) && !counterevidence.has(reference)) ||
+        !supports.some((support) => counters.some((counter) => counter !== support)))
+        return ["question-without-conflict"];
+    return [];
+}

package/dist/src/chats/analysis-shape.d.ts

@@ -0,0 +1,3 @@
+import type { AnalysisCandidate, AnalysisCode } from "./analysis-contract.ts";
+export declare function analysisObject(value: unknown): value is Record<string, unknown>;
+export declare function inspectAnalysisShape(value: unknown, codes: Set<AnalysisCode>): value is AnalysisCandidate;

package/dist/src/chats/analysis-shape.js

@@ -0,0 +1,228 @@
+import { forbiddenAnalysisField } from "./analysis-data.js";
+export function analysisObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+function label(value, values) {
+    return typeof value === "string" && values.includes(value);
+}
+function fields(value, expected) {
+    return Object.keys(value).every((key) => expected.includes(key) || forbiddenAnalysisField(key));
+}
+const itemFields = ["id", "description"];
+const claimFields = [
+    ...itemFields,
+    "kind",
+    "sourceRefs",
+    "counterevidenceRefs",
+];
+const kinds = [
+    "explicit-human-instruction",
+    "observed-repetition",
+    "assistant-claim",
+    "exception",
+    "rejected-approach",
+    "uncertain-inference",
+];
+const activities = [
+    "work",
+    "routine-repair",
+    "accidental-interruption",
+    "tool-imposed-confirmation",
+];
+const decisions = [
+    "design-decision",
+    "configured-action-approval",
+    "factual-input",
+];
+const collections = [
+    "inputs",
+    "stages",
+    "branches",
+    "loops",
+    "artifacts",
+    "stoppingConditions",
+    "gates",
+    "nonGates",
+];
+function references(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.every((ref) => analysisObject(ref) &&
+        fields(ref, ["recordIndex", "sourceId"]) &&
+        Number.isSafeInteger(ref["recordIndex"]) &&
+        Number(ref["recordIndex"]) >= 0 &&
+        text(ref["sourceId"]));
+}
+function missingSources(value) {
+    return value === undefined || (Array.isArray(value) && value.length === 0);
+}
+function questionChoices(value) {
+    if (!Array.isArray(value) || value.length < 2 || value.length > 4)
+        return false;
+    const ids = new Set();
+    return value.every((choice) => {
+        if (!analysisObject(choice) ||
+            !fields(choice, itemFields) ||
+            !text(choice["id"]) ||
+            !text(choice["description"]) ||
+            ids.has(choice["id"]))
+            return false;
+        ids.add(choice["id"]);
+        return true;
+    });
+}
+function inspectQuestionShape(candidate, codes) {
+    if (!Object.hasOwn(candidate, "openQuestion"))
+        return true;
+    const question = candidate["openQuestion"];
+    if (!analysisObject(question)) {
+        codes.add("invalid-question");
+        return false;
+    }
+    if (!fields(question, ["claimId", "description", "sourceRefs", "choices"]) ||
+        !text(question["claimId"]) ||
+        !text(question["description"]) ||
+        !questionChoices(question["choices"]))
+        codes.add("invalid-question");
+    const sources = question["sourceRefs"];
+    if (missingSources(sources)) {
+        codes.add("missing-source");
+        return false;
+    }
+    if (!references(sources))
+        codes.add("invalid-question");
+    return !codes.has("invalid-question");
+}
+function inspectClaim(value, codes) {
+    if (!label(value["kind"], kinds))
+        codes.add("unknown-kind");
+    const source = value["sourceRefs"];
+    if (missingSources(source))
+        codes.add("missing-source");
+    else if (!references(source))
+        codes.add("invalid-shape");
+    if (!references(value["counterevidenceRefs"]))
+        codes.add("invalid-shape");
+}
+function inspectLoop(value, codes) {
+    const limit = value["maxIterations"];
+    if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit <= 0)
+        codes.add("invalid-loop-limit");
+    const stageIds = value["stageIds"];
+    return (fields(value, [
+        ...claimFields,
+        "stageIds",
+        "maxIterations",
+        "exitCondition",
+        "exhaustedStoppingConditionId",
+    ]) &&
+        Array.isArray(stageIds) &&
+        stageIds.length > 0 &&
+        stageIds.every(text) &&
+        new Set(stageIds).size === stageIds.length &&
+        text(value["exitCondition"]) &&
+        text(value["exhaustedStoppingConditionId"]));
+}
+function claimShape(value, context) {
+    const { collection, codes } = context;
+    inspectClaim(value, codes);
+    switch (collection) {
+        case "stages":
+            return (fields(value, [...claimFields, "activity"]) &&
+                label(value["activity"], activities));
+        case "gates":
+            if (!label(value["type"], decisions))
+                codes.add("unknown-decision-type");
+            return (fields(value, [...claimFields, "stageId", "type"]) &&
+                text(value["stageId"]));
+        case "loops":
+            return inspectLoop(value, codes);
+        default:
+            return false;
+    }
+}
+function itemShape(value, context) {
+    const { collection } = context;
+    if (["stages", "gates", "loops"].includes(collection))
+        return claimShape(value, context);
+    switch (collection) {
+        case "branches":
+            return (fields(value, [
+                ...itemFields,
+                "sourceStageId",
+                "condition",
+                "targetStageId",
+            ]) &&
+                ["sourceStageId", "condition", "targetStageId"].every((key) => text(value[key])));
+        case "nonGates":
+            return (fields(value, [...itemFields, "stageId", "reason"]) &&
+                text(value["stageId"]) &&
+                label(value["reason"], activities.slice(1)));
+        default:
+            return fields(value, itemFields);
+    }
+}
+function inspectItem(value, context) {
+    const { ids, collection, codes } = context;
+    if (!analysisObject(value)) {
+        codes.add("invalid-shape");
+        return;
+    }
+    const id = value["id"];
+    if (!text(id)) {
+        codes.add("invalid-shape");
+        return;
+    }
+    if (!text(value["description"]) || ids.has(id))
+        codes.add("invalid-shape");
+    ids.add(id);
+    if (!itemShape(value, { collection, codes }))
+        codes.add("invalid-shape");
+}
+function inspectItems(process, codes) {
+    const id = process["id"];
+    if (!text(id)) {
+        codes.add("invalid-shape");
+        return;
+    }
+    const ids = new Set([id]);
+    for (const collection of collections) {
+        const items = process[collection];
+        if (!Array.isArray(items)) {
+            codes.add("invalid-shape");
+            continue;
+        }
+        if (["stages", "stoppingConditions"].includes(collection) &&
+            items.length === 0)
+            codes.add("invalid-shape");
+        for (const item of items) {
+            inspectItem(item, { ids, collection, codes });
+        }
+    }
+}
+export function inspectAnalysisShape(value, codes) {
+    if (!analysisObject(value)) {
+        codes.add("invalid-shape");
+        return false;
+    }
+    if (value["schemaVersion"] !== 1)
+        codes.add("unknown-version");
+    if (!fields(value, ["schemaVersion", "process", "openQuestion"]))
+        codes.add("invalid-shape");
+    const validQuestion = inspectQuestionShape(value, codes);
+    const process = value["process"];
+    if (!analysisObject(process)) {
+        codes.add("invalid-shape");
+        return false;
+    }
+    if (!fields(process, ["id", "name", "scope", ...collections]) ||
+        !["id", "name", "scope"].every((key) => text(process[key])))
+        codes.add("invalid-shape");
+    inspectItems(process, codes);
+    return (validQuestion &&
+        !codes.has("invalid-shape") &&
+        !codes.has("unknown-version"));
+}

package/dist/src/chats/analysis.d.ts

@@ -0,0 +1,3 @@
+export * from "./analysis-contract.ts";
+import { type AnalysisEvidence, type AnalysisValidation } from "./analysis-contract.ts";
+export declare function validateAnalysis(candidate: unknown, evidence: AnalysisEvidence): AnalysisValidation;

package/dist/src/chats/analysis.js

@@ -0,0 +1,42 @@
+export * from "./analysis-contract.js";
+import { analysisCodes, } from "./analysis-contract.js";
+import { inspectAnalysisShape } from "./analysis-shape.js";
+import { inspectAnalysisLinks } from "./analysis-links.js";
+import { inspectAnalysisData } from "./analysis-data.js";
+import { matchingAnalysisEvidence, inspectAnalysisSupport, inspectAnalysisQuestion, } from "./analysis-provenance.js";
+export function validateAnalysis(candidate, evidence) {
+    const codes = new Set(inspectAnalysisData(candidate));
+    if (codes.has("not-plain-data"))
+        return { accepted: false, codes: ["not-plain-data"] };
+    if (!inspectAnalysisShape(candidate, codes))
+        return {
+            accepted: false,
+            codes: analysisCodes.filter((code) => codes.has(code)),
+        };
+    for (const code of inspectAnalysisLinks(candidate.process))
+        codes.add(code);
+    if (matchingAnalysisEvidence(evidence)) {
+        for (const code of inspectAnalysisSupport(candidate.process, evidence))
+            codes.add(code);
+        for (const code of inspectAnalysisQuestion(candidate, evidence))
+            codes.add(code);
+    }
+    else
+        codes.add("invalid-shape");
+    if (codes.size > 0)
+        return {
+            accepted: false,
+            codes: analysisCodes.filter((code) => codes.has(code)),
+        };
+    return {
+        accepted: true,
+        result: {
+            ...candidate,
+            limitations: {
+                historyCompleteness: "unknown",
+                independentObservations: "not-established",
+                conflictGroups: evidence.structure.conflictGroups,
+            },
+        },
+    };
+}

package/dist/src/chats/corpus-input.d.ts

@@ -0,0 +1,5 @@
+import { type MessageRecord } from "./normalize.ts";
+export declare function parseCorpusRecord(line: string): MessageRecord;
+export declare function parseCorpus(text: string): readonly MessageRecord[];
+export declare function validateCoverage(text: string, importId: string): void;
+export declare function withinRoot(root: string | undefined, path: unknown): boolean;