perttool 0.9.3 → 0.10.0

package/dist/cli.js

@@ -7,14 +7,15 @@ import { createNodeHost } from "./node/host.js";
 import { createHistoricalGraphGitEvidenceHost } from "./node/historical-host.js";
 import { exportMermaid, } from "./conversion/mermaid.js";
 import { importMermaid } from "./conversion/mermaid-import.js";
-import { getAssuranceGuide, renderAssuranceGuideResult, serializeAssuranceGuideResult, } from "./help/assurance-guide.js";
+import { getContract9Guide as getAssuranceGuide, renderContract9GuideResult as renderAssuranceGuideResult, serializeContract9GuideResult as serializeAssuranceGuideResult, } from "./help/contract9-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { ASSURANCE_COMMAND_REGISTRY, getAssuranceCommandDiscovery, renderAssuranceCommandHelpResult, serializeAssuranceCommandHelpResult, } from "./command/assurance-discovery.js";
+import { CONTRACT9_COMMAND_REGISTRY as ASSURANCE_COMMAND_REGISTRY, getContract9CommandDiscovery as getAssuranceCommandDiscovery, renderContract9CommandHelpResult as renderAssuranceCommandHelpResult, serializeContract9CommandHelpResult as serializeAssuranceCommandHelpResult, } from "./command/contract9-discovery.js";
 import { handlerCommandUsageError, } from "./command/usage.js";
-import { renderAssuranceCommandUsageError, serializeAssuranceCommandUsageError, validateAssuranceCommandInvocation, } from "./command/assurance-usage.js";
+import { renderContract9CommandUsageError as renderAssuranceCommandUsageError, serializeContract9CommandUsageError as serializeAssuranceCommandUsageError, validateContract9CommandInvocation as validateAssuranceCommandInvocation, } from "./command/contract9-usage.js";
 import { agentGuidanceResultToJson } from "./guidance/projection.js";
 import { agentGuidanceExitCode, renderAgentGuidanceText, } from "./guidance/text.js";
 import { SafeWriteConflictError, SafeWriteVerificationError, } from "./io/safe-write.js";
+import { limitDiagnostics, sortDiagnostics, } from "./model/diagnostics.js";
 import { formatDecimal } from "./model/rational.js";
 import { convertWithVelocity, durationSuffix } from "./model/units.js";
 import { recommendationInvariantExitCode } from "./recommendation/failure.js";
@@ -26,8 +27,13 @@ import { TARGET_GRAMMAR_6_CAPABILITY, } from "./parser/document-parser.js";
 import { exportPlanAssuranceMermaid, importPlanAssuranceMermaid, } from "./assurance/mermaid.js";
 import { getJsonSchemaResult, renderJsonSchemaResult, serializeJsonSchemaResult, } from "./schema/registry.js";
 import { TOOL_VERSION } from "./version.js";
-import { analyzeDocument as analyzeContract8Document, checkDocument as checkContract8Document, selectNextTasks as selectContract8NextTasks, } from "./application/contract8-milestone-acceptance.js";
-import { persistMilestoneAcceptanceMutation, planAcceptanceReceiptMutation, planCriterionSetReplacement, showMilestoneAcceptance, } from "./milestone-acceptance/mutation.js";
+import { analyzeDocument as analyzeContract8Document, checkDocument as checkContract8Document, selectNextTasks as selectContract8NextTasks, } from "./application/contract9-temporal.js";
+import { contract9CheckResultToJson, contract9ProjectResultToJson, liftContract9AnalysisResultJson, liftContract9NextResultJson, renderContract9ScheduleAlerts, contract9WireJson, } from "./application/contract9-projection.js";
+import { planContract9GrammarMigration } from "./application/contract9-format-migration.js";
+import { planContract9TemporalMutation } from "./application/contract9-temporal-mutation.js";
+import { composeContract9MixedMutation, composeContract9TemporalMutation } from "./application/contract9-mixed-mutation.js";
+import { planAcceptanceReceiptMutation, planCriterionSetReplacement, showMilestoneAcceptance, } from "./milestone-acceptance/mutation.js";
+import { scanTemporalDeclarationBlocks, temporalScheduleBaseText, } from "./temporal-schedule/source-lexical.js";
 import { planMilestoneAcceptanceMigration, recheckCommittedMigrationProof, } from "./milestone-acceptance/migration.js";
 import { MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY, milestoneAcceptanceBaseText, parseMilestoneAcceptanceSource } from "./milestone-acceptance/source.js";
 import { coalesceMilestoneAcceptanceDeletionOverlaps, planMilestoneAcceptanceAdvance, preserveMilestoneAcceptanceRecords, } from "./milestone-acceptance/advance.js";
@@ -35,11 +41,11 @@ const { analyzeDocument: _analyzeContract7Document, checkDocument: _checkContrac
 const analyzeDocument = analyzeContract8Document;
 const checkDocument = checkContract8Document;
 const selectNextTasks = selectContract8NextTasks;
-function contract8MutationResultToJson(result, ...args) {
+function contract9MutationResultToJson(result, ...args) {
     return Object.freeze({
         ...contract7MutationResultToJson(result, ...args),
-        schema_version: "Perttool.MutationResult.v5",
-        cli_contract_version: 8,
+        schema_version: "Perttool.MutationResult.v6",
+        cli_contract_version: 9,
     });
 }
 class UsageError extends Error {
@@ -215,7 +221,7 @@ async function readStdin() {
 function writeJson(value) {
     const contract8Value = typeof value === "object" && value !== null && !Array.isArray(value) &&
         "cli_contract_version" in value
-        ? { ...value, cli_contract_version: 8 }
+        ? { ...value, cli_contract_version: 9 }
         : value;
     process.stdout.write(`${JSON.stringify(contract8Value)}\n`);
 }
@@ -288,30 +294,7 @@ async function runCheck(args) {
     const warningFailure = warningsAsErrors && result.summary.warnings > 0;
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson({
-            schema_version: result.schemaVersion,
-            cli_contract_version: 8,
-            tool_version: TOOL_VERSION,
-            operation: "document.check",
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            grammar_version: result.grammarVersion,
-            summary: result.summary,
-            temporal_inputs: snakeJson(result.temporalInputs),
-            actuals_inputs: result.actualsInputs === null
-                ? null
-                : {
-                    model_version: result.actualsInputs.modelVersion,
-                    events: result.actualsInputs.events.map(contract6WorkEventToJson),
-                },
-            assurance: contract7SnakeJson(result.assurance),
-            assurance_state_counts: contract7SnakeJson(result.assuranceStateCounts),
-            acceptance: snakeJson(result.acceptance),
-        });
+        writeJson(contract9CheckResultToJson(result, { source, sourceDigest: input.digest, ok }));
     }
     else {
         if (ok) {
@@ -320,6 +303,7 @@ async function runCheck(args) {
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
         }
+        process.stdout.write(renderContract9ScheduleAlerts(result.scheduleAlerts));
         if (result.diagnosticsTruncated) {
             process.stderr.write(`DIAGNOSTICS_TRUNCATED true limit=${maxDiagnostics}\n`);
         }
@@ -349,7 +333,7 @@ async function runProjectShow(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson(contract7ProjectResultToJson(result, source, input.digest, ok));
+        writeJson(contract9ProjectResultToJson(result, { source, sourceDigest: input.digest, ok }));
     }
     else {
         if (ok && result.project !== null) {
@@ -548,10 +532,15 @@ async function persistContract8CandidateResult(result, request) {
     if (!result.ok || !result.governance?.writeAuthorized || result.updatedText === null) {
         throw new TypeError("authorized Contract 8 result does not contain a digest-bound candidate");
     }
-    const validator = (candidate) => {
-        const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
-        return { ok: parsed.ok, diagnostics: [] };
-    };
+    const validator = /^  version 8$/mu.test(result.updatedText)
+        ? (candidate) => {
+            const checked = checkDocument(candidate);
+            return { ok: checked.ok, diagnostics: checked.diagnostics };
+        }
+        : (candidate) => {
+            const parsed = parseMilestoneAcceptanceSource(candidate, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
+            return { ok: parsed.ok, diagnostics: [] };
+        };
     if (request.mode === "in_place") {
         await replaceValidatedDocumentFile(request.target, result.updatedText, {
             initialDigest: result.originalDigest,
@@ -574,6 +563,20 @@ async function commitCandidate(request, candidateText, initialDigest) {
     if (candidateText === null) {
         throw new SafeWriteVerificationError("invalid_candidate", "successful editing result has no candidate text");
     }
+    if (/^  version 8$/mu.test(candidateText)) {
+        const validator = (candidate) => {
+            const checked = checkDocument(candidate);
+            return { ok: checked.ok, diagnostics: checked.diagnostics };
+        };
+        return request.mode === "in_place"
+            ? replaceValidatedDocumentFile(request.target, candidateText, {
+                initialDigest,
+                ...(request.expectedDigest === undefined
+                    ? {}
+                    : { expectedDigest: request.expectedDigest }),
+            }, validator)
+            : createValidatedDocumentFile(request.target, candidateText, validator);
+    }
     const acceptanceSource = parseMilestoneAcceptanceSource(candidateText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
     if (acceptanceSource.grammarVersion === 7) {
         const validator = (candidate) => {
@@ -613,6 +616,26 @@ function renderWriteSummary(operation, result) {
 function renderGovernanceWriteSummary(operation, result, digest) {
     return `WRITE ${operation} mode=${result.mode} target=${result.target ?? "-"} digest=${digest ?? "-"} written=${result.written}\n`;
 }
+async function runContract9DocumentMigration(args) {
+    const parsed = parseCommandOptions("document.migrate", args);
+    if (parsed.positionals.length !== 1 || parsed.values.get("target-grammar") !== "8")
+        throw new UsageError("document migrate requires <file> --target-grammar 8");
+    const sourceOperand = parsed.positionals[0];
+    const format = outputFormat(parsed.values.get("format"));
+    const input = await readDocument(sourceOperand);
+    const result = planContract9GrammarMigration(input.text);
+    if (result.ok && result.updatedText !== null && parsed.flags.has("write")) {
+        if (sourceOperand === "-")
+            throw new UsageError("document migrate --write requires a file");
+        await replaceValidatedDocumentFile(sourceOperand, result.updatedText, { initialDigest: input.digest, ...(parsed.values.get("expect-digest") === undefined ? {} : { expectedDigest: parsed.values.get("expect-digest") }) }, (candidate) => ({ ok: checkDocument(candidate).ok, diagnostics: [] }));
+    }
+    if (format === "json")
+        writeJson({ schema_version: "Perttool.UnitMigrationResult.v4", cli_contract_version: 9,
+            tool_version: TOOL_VERSION, operation: "document.migrate", ...snakeJson(result) });
+    else if (result.updatedText !== null)
+        process.stdout.write(parsed.flags.has("diff") ? result.diff ?? "" : result.updatedText);
+    return result.ok ? 0 : 1;
+}
 async function runFormat(args) {
     const parsed = parseCommandOptions("document.format", args);
     if (parsed.positionals.length !== 1) {
@@ -656,7 +679,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 8,
+            cli_contract_version: 9,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -1240,11 +1263,21 @@ async function runMutation(resource, action, args) {
         updatedLabel: "candidate",
         governance: governanceRequest(parsed, writeRequest),
     };
-    const result = lifecycleMutation !== null
-        ? planFinishActuals(input.text, lifecycleMutation, mutationOptions)
+    const legacyPlanner = (text) => lifecycleMutation !== null
+        ? planFinishActuals(text, lifecycleMutation, mutationOptions)
         : resource === "batch"
-            ? planBatchMutation(input.text, mutation, mutationOptions)
-            : planMutation(input.text, mutation, mutationOptions);
+            ? planBatchMutation(text, mutation, mutationOptions)
+            : planMutation(text, mutation, mutationOptions);
+    const contract9Invocation = validateAssuranceCommandInvocation([resource, action, ...args]);
+    const temporalRequest = contract9Invocation.ok
+        ? planContract9TemporalMutation(input.text, contract9Invocation, { maxDiagnostics })
+        : null;
+    const legacyPreview = legacyPlanner(input.text);
+    const result = temporalRequest === null
+        ? legacyPreview
+        : !legacyPreview.ok
+            ? composeContract9TemporalMutation(input.text, (candidate) => planContract9TemporalMutation(candidate, contract9Invocation, { maxDiagnostics }), { originalLabel: source, updatedLabel: "candidate" })
+            : composeContract9MixedMutation(input.text, (base) => legacyPlanner(base), (candidate) => planContract9TemporalMutation(candidate, contract9Invocation, { maxDiagnostics }), { originalLabel: source, updatedLabel: "candidate" });
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
@@ -1265,7 +1298,7 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson(contract8MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract9MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1348,7 +1381,7 @@ async function runLifecycleMutation(action, args) {
         }
     }
     if (format === "json") {
-        writeJson(contract8MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
+        writeJson(contract9MutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
@@ -1387,7 +1420,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 8,
+        cli_contract_version: 9,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1677,6 +1710,22 @@ function renderAdvanceSummary(details) {
         "",
     ].join("\n");
 }
+function mergeAdvanceCandidateDiagnostics(candidateDiagnostics, operationDiagnostics, maximum) {
+    const identities = new Set();
+    const unique = [...candidateDiagnostics, ...operationDiagnostics].filter((diagnostic) => {
+        const identity = [
+            diagnostic.code,
+            diagnostic.severity,
+            diagnostic.message,
+            diagnostic.entityId ?? "",
+        ].join("\u0000");
+        if (identities.has(identity))
+            return false;
+        identities.add(identity);
+        return true;
+    });
+    return limitDiagnostics(sortDiagnostics(unique), maximum);
+}
 function renderAssuranceGuard(guard) {
     const list = (values) => values.join(",") || "-";
     return [
@@ -1768,18 +1817,21 @@ async function runAdvance(args) {
     const combinedEdits = contract7Planned.updatedText === null
         ? contract7Planned.edits
         : normalizeTextEdits(input.text, coalesceMilestoneAcceptanceDeletionOverlaps([
-            ...preserveMilestoneAcceptanceRecords(input.text, contract7Planned.edits, acceptancePlan.provisional.advance.stateChangedMilestoneIds),
+            ...preserveMilestoneAcceptanceRecords(input.text, contract7Planned.edits, acceptancePlan.provisional.advance.keptMilestoneIds),
             ...acceptancePlan.provisional.edits,
         ]), "Contract 8 acceptance-aware advance");
     const combinedText = contract7Planned.updatedText === null
         ? null
         : applyTextEdits(input.text, combinedEdits);
-    const combinedSource = combinedText === null
+    const combinedCheck = combinedText === null
         ? null
-        : parseMilestoneAcceptanceSource(combinedText, MILESTONE_ACCEPTANCE_SOURCE_CAPABILITY);
-    if (combinedSource !== null && !combinedSource.ok) {
-        throw new Error("acceptance-aware assurance advance lost Grammar 7 validation");
+        : checkContract8Document(combinedText, { maxDiagnostics });
+    if (combinedCheck !== null && !combinedCheck.ok) {
+        throw new Error("acceptance-aware assurance advance lost Contract 8 validation");
     }
+    const combinedDiagnostics = combinedCheck === null
+        ? null
+        : mergeAdvanceCandidateDiagnostics(combinedCheck.diagnostics, contract7Planned.diagnostics, maxDiagnostics);
     const planned = Object.freeze({
         ...contract7Planned,
         schemaVersion: "Perttool.AdvanceResult.v3",
@@ -1791,11 +1843,15 @@ async function runAdvance(args) {
             updatedLabel: "candidate",
         }),
         edits: combinedEdits,
+        diagnostics: combinedDiagnostics?.diagnostics ?? contract7Planned.diagnostics,
+        diagnosticsTruncated: contract7Planned.diagnosticsTruncated ||
+            (combinedCheck?.diagnosticsTruncated ?? false) ||
+            (combinedDiagnostics?.truncated ?? false),
         acceptanceGuard: acceptancePlan.acceptanceGuard,
     });
     const initialWarningFailure = parsed.flags.has("warnings-as-errors") &&
-        (planned.diagnosticsTruncated ||
-            planned.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
+        (contract7Planned.diagnosticsTruncated ||
+            contract7Planned.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const preparedBase = await prepareAdvanceHistory(input.text, planned, {
         mode: writeRequest.mode === "out"
             ? "out"
@@ -2237,8 +2293,8 @@ async function runAnalyze(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson({
-            schema_version: result.schemaVersion,
+        writeJson(liftContract9AnalysisResultJson({
+            schema_version: "Perttool.AnalysisResult.v6",
             cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
@@ -2273,7 +2329,7 @@ async function runAnalyze(args) {
             temporal: snakeJson(result.temporal),
             assurance: contract7SnakeJson(result.assurance),
             acceptance: snakeJson(result.acceptance),
-        });
+        }, result));
     }
     else {
         if (ok)
@@ -2809,7 +2865,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 8,
+                cli_contract_version: 9,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2828,8 +2884,8 @@ async function runNext(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson({
-            schema_version: result.schemaVersion,
+        writeJson(liftContract9NextResultJson({
+            schema_version: "Perttool.NextResult.v7",
             cli_contract_version: 8,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
@@ -2845,7 +2901,7 @@ async function runNext(args) {
             temporal: snakeJson(result.temporal),
             assurance: contract7SnakeJson(result.assurance),
             acceptance: snakeJson(result.acceptance),
-        });
+        }, result));
     }
     else {
         if (ok)
@@ -2859,6 +2915,49 @@ async function runNext(args) {
     }
     return ok ? 0 : 1;
 }
+function parseMilestoneAcceptanceCriteria(values) {
+    return values.map((value) => {
+        const [criterionId, requiredText, evidenceKind, ...description] = value.split(":");
+        if (criterionId === undefined || !["required", "optional"].includes(requiredText ?? "") || !["test", "command", "artifact", "observation", "owner"].includes(evidenceKind ?? "") || description.length === 0)
+            throw new UsageError("--criterion must be ID:required|optional:kind:description");
+        return {
+            criterionId,
+            required: requiredText === "required",
+            evidenceKind: evidenceKind,
+            description: description.join(":"),
+        };
+    });
+}
+function planContract9AcceptanceMutation(text, planner) {
+    if (!/^  version 8$/mu.test(text))
+        return planner(text);
+    const base = temporalScheduleBaseText(text, scanTemporalDeclarationBlocks(text));
+    const planned = planner(base);
+    const originalDigest = sha256DigestUtf8(text);
+    if (!planned.ok || planned.updatedText === null) {
+        return Object.freeze({ ...planned, originalDigest });
+    }
+    let prefix = 0;
+    while (prefix < base.length &&
+        prefix < planned.updatedText.length &&
+        base[prefix] === planned.updatedText[prefix])
+        prefix += 1;
+    let suffix = 0;
+    while (suffix < base.length - prefix &&
+        suffix < planned.updatedText.length - prefix &&
+        base[base.length - 1 - suffix] ===
+            planned.updatedText[planned.updatedText.length - 1 - suffix])
+        suffix += 1;
+    const candidate = text.slice(0, prefix) +
+        planned.updatedText.slice(prefix, planned.updatedText.length - suffix) +
+        text.slice(text.length - suffix);
+    const checked = checkDocument(candidate);
+    if (!checked.ok)
+        return Object.freeze({ ...planned, ok: false, changed: false,
+            originalDigest, updatedDigest: null, updatedText: null });
+    return Object.freeze({ ...planned, originalDigest, changed: candidate !== text,
+        updatedDigest: sha256DigestUtf8(candidate), updatedText: candidate });
+}
 async function runMilestoneAcceptance(action, args) {
     const operation = `milestone-acceptance.${action}`;
     const parsed = parseCommandOptions(operation, args);
@@ -2885,16 +2984,11 @@ async function runMilestoneAcceptance(action, args) {
     const governance = governanceRequest(parsed, request);
     let result;
     if (action === "replace") {
-        const criteria = (parsed.repeatedValues.get("criterion") ?? []).map((value) => {
-            const [criterionId, requiredText, evidenceKind, ...description] = value.split(":");
-            if (criterionId === undefined || !["required", "optional"].includes(requiredText ?? "") || !["test", "command", "artifact", "observation", "owner"].includes(evidenceKind ?? "") || description.length === 0)
-                throw new UsageError("--criterion must be ID:required|optional:kind:description");
-            return { criterionId, required: requiredText === "required", evidenceKind: evidenceKind, description: description.join(":") };
-        });
-        result = planCriterionSetReplacement(input.text, { milestoneId: parsed.positionals[1], setId: parsed.positionals[2], revisionId: parsed.positionals[3], criteria }, { governance });
+        const criteria = parseMilestoneAcceptanceCriteria(parsed.repeatedValues.get("criterion") ?? []);
+        result = planContract9AcceptanceMutation(input.text, (text) => planCriterionSetReplacement(text, { milestoneId: parsed.positionals[1], setId: parsed.positionals[2], revisionId: parsed.positionals[3], criteria }, { governance }));
     }
     else {
-        result = planAcceptanceReceiptMutation(input.text, {
+        result = planContract9AcceptanceMutation(input.text, (text) => planAcceptanceReceiptMutation(text, {
             setId: parsed.positionals[1], criterionId: parsed.positionals[2], receiptId: parsed.positionals[3], action: action,
             ...(parsed.values.get("evidence-kind") === undefined ? {} : { evidenceKind: parsed.values.get("evidence-kind") }),
             ...(parsed.values.get("evidence-reference") === undefined ? {} : { evidenceReference: parsed.values.get("evidence-reference") }),
@@ -2903,16 +2997,16 @@ async function runMilestoneAcceptance(action, args) {
             ...(parsed.values.get("occurred-at") === undefined ? {} : { occurredAt: parsed.values.get("occurred-at") }),
             ...(parsed.values.get("reason") === undefined ? {} : { reason: parsed.values.get("reason") }),
             ...(parsed.values.get("revokes") === undefined ? {} : { revokes: parsed.values.get("revokes") }),
-        }, { governance });
+        }, { governance }));
     }
     let written = false;
     if (result.ok && request.mode === "in_place" && result.changed) {
-        await persistMilestoneAcceptanceMutation(sourceOperand, result, request.expectedDigest);
+        await commitCandidate(request, result.updatedText, input.digest);
         written = true;
     }
     if (format === "json")
         writeJson({
-            schema_version: "Perttool.MutationResult.v5",
+            schema_version: "Perttool.MutationResult.v6",
             cli_contract_version: 8,
             tool_version: TOOL_VERSION,
             operation,
@@ -2948,39 +3042,36 @@ async function runMilestoneAcceptance(action, args) {
     return result.ok ? 0 : 1;
 }
 async function runDocumentMigration(args) {
+    const target = args.includes("--target-grammar")
+        ? args[args.indexOf("--target-grammar") + 1]
+        : args.find((value) => value.startsWith("--target-grammar="))?.slice("--target-grammar=".length);
+    if (target === "8")
+        return runContract9DocumentMigration(args);
     const parsed = parseCommandOptions("document.migrate", args);
     if (parsed.positionals.length !== 1 || parsed.values.get("target-grammar") !== "7")
-        throw new UsageError("document migrate requires <file> --target-grammar 7");
+        throw new UsageError("document migrate requires <file> --target-grammar 8");
     const sourceOperand = parsed.positionals[0];
     if (sourceOperand === "-")
         throw new UsageError("document migrate requires a repository file");
     const format = outputFormat(parsed.values.get("format"));
     const input = await readDocument(sourceOperand);
     const baseline = await captureAdvanceHistoryBaseline({ targetPath: sourceOperand, expectedSourceDigest: input.digest });
-    const toProof = (value) => value.status === "complete" && value.repositorySnapshotId !== null &&
-        value.repositoryRelativePath !== null && value.objectFormat !== null &&
-        value.headCommitId !== null && value.headBlobId !== null &&
+    const toProof = (value) => value.status === "complete" && value.repositorySnapshotId !== null && value.repositoryRelativePath !== null &&
+        value.objectFormat !== null && value.headCommitId !== null && value.headBlobId !== null &&
         value.indexBlobId !== null && value.currentSourceDigest !== null
-        ? {
-            repositoryId: value.repositorySnapshotId,
-            repositoryRelativePath: value.repositoryRelativePath,
-            objectFormat: value.objectFormat,
-            headCommit: value.headCommitId,
-            headBlob: value.headBlobId,
-            stage0Blob: value.indexBlobId,
-            sourceDigest: value.currentSourceDigest,
-        }
+        ? { repositoryId: value.repositorySnapshotId, repositoryRelativePath: value.repositoryRelativePath,
+            objectFormat: value.objectFormat, headCommit: value.headCommitId, headBlob: value.headBlobId,
+            stage0Blob: value.indexBlobId, sourceDigest: value.currentSourceDigest }
         : null;
     const proof = toProof(baseline);
     let result = proof === null
-        ? { ok: false, modelVersion: 1, changed: false, sourceGrammarVersion: null, targetGrammarVersion: null, sourceDigest: input.digest, candidateDigest: null, grandfatheredMilestoneIds: Object.freeze([]), candidateText: null, diagnostics: Object.freeze(["PTMAC-109"]) }
+        ? { ok: false, modelVersion: 1, changed: false, sourceGrammarVersion: null, targetGrammarVersion: null,
+            sourceDigest: input.digest, candidateDigest: null, grandfatheredMilestoneIds: Object.freeze([]),
+            candidateText: null, diagnostics: Object.freeze(["PTMAC-109"]) }
         : planMilestoneAcceptanceMigration(input.text, proof);
     let race = false;
     if (result.ok && result.changed && result.candidateText !== null && parsed.flags.has("write")) {
-        const current = toProof(await captureAdvanceHistoryBaseline({
-            targetPath: sourceOperand,
-            expectedSourceDigest: input.digest,
-        }));
+        const current = toProof(await captureAdvanceHistoryBaseline({ targetPath: sourceOperand, expectedSourceDigest: input.digest }));
         if (proof === null || current === null || !recheckCommittedMigrationProof(proof, current)) {
             result = Object.freeze({ ...result, ok: false, diagnostics: Object.freeze(["PTMAC-110"]) });
             race = true;
@@ -2990,7 +3081,8 @@ async function runDocumentMigration(args) {
         }
     }
     if (format === "json")
-        writeJson({ schema_version: "Perttool.MilestoneAcceptanceMigrationResult.v1", cli_contract_version: 8, tool_version: TOOL_VERSION, operation: "document.migrate", ...snakeJson(result) });
+        writeJson({ schema_version: "Perttool.MilestoneAcceptanceMigrationResult.v1", cli_contract_version: 8,
+            tool_version: TOOL_VERSION, operation: "document.migrate", ...snakeJson(result) });
     else if (result.candidateText !== null)
         process.stdout.write(result.candidateText);
     return result.ok ? 0 : race ? 5 : 1;
@@ -3164,7 +3256,8 @@ async function runPlanAssuranceInspection(action, args) {
         (result.diagnosticsTruncated || result.diagnostics.some(({ severity }) => severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson(contract7InspectionResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), source));
+        writeJson({ ...contract9WireJson(ok ? result : Object.freeze({ ...result, ok: false })),
+            source, cli_contract_version: 9 });
     }
     else if (ok) {
         if (action === "hash") {
@@ -3312,7 +3405,7 @@ async function runAssuranceMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson(contract8MutationResultToJson(result, operation, source, writeResult));
+        writeJson(contract9MutationResultToJson(result, operation, source, writeResult));
     }
     else {
         if (result.ok) {
@@ -3340,6 +3433,32 @@ async function runAssuranceMutation(resource, action, args) {
     }
     return result.ok ? 0 : 1;
 }
+async function runCalendarMutation(action, args) {
+    const operation = `calendar.${action}`;
+    const validation = validateAssuranceCommandInvocation(["calendar", action, ...args]);
+    if (!validation.ok)
+        return emitCommandUsage(validation.error, jsonRequested(args));
+    const parsed = parseCommandOptions(operation, args);
+    const format = outputFormat(parsed.values.get("format"));
+    const sourceOperand = parsed.positionals[0];
+    const source = sourceOperand === "-" ? "<stdin>" : sourceOperand;
+    const input = await readDocument(sourceOperand);
+    const temporal = (candidate) => planContract9TemporalMutation(candidate, validation);
+    const result = composeContract9TemporalMutation(input.text, temporal, { originalLabel: source, updatedLabel: "candidate" });
+    const writeRequest = editingWriteRequest(parsed, sourceOperand);
+    let writeResult = Object.freeze({ mode: writeRequest.mode, target: writeRequest.target, written: false });
+    if (result.ok && writeRequest.mode !== "preview") {
+        writeResult = await persistContract8CandidateResult(result, writeRequest);
+    }
+    if (format === "json") {
+        writeJson({ ...contract9WireJson(result), operation,
+            source, write: contract9WireJson(writeResult), cli_contract_version: 9 });
+    }
+    else if (result.ok) {
+        process.stdout.write(parsed.flags.has("diff") ? result.diff ?? "" : result.updatedText ?? "");
+    }
+    return result.ok ? 0 : 1;
+}
 async function dispatchCommand(descriptor, args) {
     switch (descriptor.operation) {
         case "help":
@@ -3378,6 +3497,10 @@ async function dispatchCommand(descriptor, args) {
             return runHistoricalGraph(args);
         case "dag.import":
             return runImport(args);
+        case "calendar.add":
+        case "calendar.set":
+        case "calendar.remove":
+            return runCalendarMutation(descriptor.path[1], args);
         case "task.start":
             return runLifecycleMutation("start", args);
         case "task.suspend":