@longtable/checkpoints 0.1.9

package/README.md

@@ -0,0 +1,10 @@
+# @longtable/checkpoints
+
+Checkpoint policy and runtime guidance engine for LongTable.
+
+Current responsibilities:
+
+- structural and adaptive checkpoint resolution
+- runtime guidance generation by interaction mode
+- closure-disposition rules for provider adapters
+- question-first governance for high-ambiguity research work

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./resolve-policy.js";
+export * from "./runtime-guidance.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./resolve-policy.js";
+export * from "./runtime-guidance.js";
+export * from "./types.js";

package/dist/resolve-policy.d.ts

@@ -0,0 +1,2 @@
+import type { CheckpointSignal, ResearcherProfile, ResolvedCheckpointPolicy } from "./types.js";
+export declare function resolveCheckpointPolicy(profile: ResearcherProfile, signal: CheckpointSignal): ResolvedCheckpointPolicy;

package/dist/resolve-policy.js

@@ -0,0 +1,120 @@
+const REQUIRED_LEVELS = new Set([
+    "universal_required",
+    "adaptive_required"
+]);
+function escalate(level) {
+    switch (level) {
+        case "none":
+            return "log_only";
+        case "log_only":
+            return "recommended";
+        case "recommended":
+            return "adaptive_required";
+        default:
+            return level;
+    }
+}
+function downgrade(level) {
+    switch (level) {
+        case "adaptive_required":
+            return "recommended";
+        case "recommended":
+            return "log_only";
+        case "log_only":
+            return "none";
+        default:
+            return level;
+    }
+}
+function pickPromptStyle(level) {
+    switch (level) {
+        case "universal_required":
+            return "structured_choice";
+        case "adaptive_required":
+            return "confirm_or_revise";
+        case "recommended":
+            return "advisory_summary";
+        default:
+            return "passive_log";
+    }
+}
+function isHighStakeArtifact(artifactStakes) {
+    return artifactStakes === "study_protocol" || artifactStakes === "external_submission";
+}
+export function resolveCheckpointPolicy(profile, signal) {
+    let level = signal.baseLevel;
+    const rationale = [];
+    const unresolvedTensions = [
+        ...(signal.unresolvedTensions ?? []),
+        ...(signal.studyContract?.openTensions ?? [])
+    ];
+    if (level === "universal_required") {
+        rationale.push("Universal checkpoints stay blocking across researcher profiles.");
+    }
+    if (!signal.studyContract && (signal.mode === "commit" || signal.mode === "submit")) {
+        rationale.push("No study contract is attached to this decision context.");
+    }
+    if (level === "adaptive_required" &&
+        (signal.mode === "explore" || signal.mode === "review" || signal.mode === "critique") &&
+        signal.artifactStakes === "private_note") {
+        level = "recommended";
+        rationale.push("Exploration on a private note should not hard-stop an adaptive checkpoint.");
+    }
+    if (profile.experienceLevel === "novice" &&
+        (signal.researchStage === "theory_selection" ||
+            signal.researchStage === "measurement_design" ||
+            signal.researchStage === "analysis_planning") &&
+        level !== "universal_required") {
+        level = escalate(level);
+        rationale.push("Novice researchers receive stronger guidance on high-risk research commitments.");
+    }
+    if (profile.forceCheckpointsOn?.includes(signal.checkpointKey) && level !== "universal_required") {
+        level = escalate(level);
+        rationale.push("The researcher profile explicitly asks for stronger checkpointing here.");
+    }
+    if (profile.relaxCheckpointsOn?.includes(signal.checkpointKey) &&
+        level === "adaptive_required" &&
+        signal.mode !== "commit" &&
+        signal.mode !== "submit") {
+        level = downgrade(level);
+        rationale.push("The researcher profile allows lighter intervention on this checkpoint.");
+    }
+    if (isHighStakeArtifact(signal.artifactStakes) && level !== "universal_required" && level !== "none") {
+        level = escalate(level);
+        rationale.push("High-stakes artifacts raise checkpoint intensity before information leaves private drafting.");
+    }
+    if (!signal.studyContract &&
+        signal.artifactStakes === "external_submission" &&
+        level !== "universal_required") {
+        level = "universal_required";
+        rationale.push("External submission without an attached study contract should remain blocking.");
+    }
+    if (unresolvedTensions.length > 0 &&
+        signal.mode === "commit" &&
+        level !== "universal_required" &&
+        level !== "none") {
+        level = escalate(level);
+        rationale.push("Unresolved tensions increase the need for explicit human commitment.");
+    }
+    if (profile.preferredCheckpointIntensity === "high" && level === "recommended") {
+        level = "adaptive_required";
+        rationale.push("Researcher preference is set to high checkpoint intensity.");
+    }
+    if (profile.preferredCheckpointIntensity === "low" &&
+        level === "recommended" &&
+        signal.mode !== "commit" &&
+        signal.mode !== "submit") {
+        level = "log_only";
+        rationale.push("Low checkpoint preference keeps non-blocking guidance lightweight.");
+    }
+    const blocking = REQUIRED_LEVELS.has(level);
+    return {
+        checkpointKey: signal.checkpointKey,
+        level,
+        blocking,
+        promptStyle: pickPromptStyle(level),
+        requiresDecisionLog: blocking || level === "recommended" || isHighStakeArtifact(signal.artifactStakes),
+        updateExplicitState: blocking || signal.mode === "commit" || signal.mode === "submit",
+        rationale
+    };
+}

package/dist/runtime-guidance.d.ts

@@ -0,0 +1,2 @@
+import type { CheckpointSignal, ResearcherProfile, ResolvedCheckpointPolicy, RuntimeGuidance } from "./types.js";
+export declare function resolveRuntimeGuidance(profile: ResearcherProfile, signal: CheckpointSignal, policy?: ResolvedCheckpointPolicy): RuntimeGuidance;

package/dist/runtime-guidance.js

@@ -0,0 +1,167 @@
+import { resolveCheckpointPolicy } from "./resolve-policy.js";
+function unique(values) {
+    return [...new Set(values)];
+}
+function pushQuestion(questions, question) {
+    if (!questions.includes(question)) {
+        questions.push(question);
+    }
+}
+function createBaseGuidance(mode) {
+    switch (mode) {
+        case "explore":
+            return {
+                mode,
+                minimumQuestions: 2,
+                questionTypes: ["clarifying", "tension"],
+                mustAskBeforeClosure: true,
+                preferQuestionsFirst: true,
+                includeUnaskedQuestions: true,
+                includeOpenTensions: true,
+                includeWhyMayBeWrong: false,
+                preserveNarrativeTrace: false,
+                surfaceHumanCommitment: false,
+                closureDisposition: "delay",
+                mandatoryQuestions: [
+                    "What ambiguity here would most change the research direction if resolved differently?",
+                    "What tension is still unresolved in this framing?"
+                ],
+                rationale: ["Explore mode delays closure and surfaces ambiguity before recommendation."]
+            };
+        case "review":
+            return {
+                mode,
+                minimumQuestions: 1,
+                questionTypes: ["clarifying", "boundary", "tension"],
+                mustAskBeforeClosure: false,
+                preferQuestionsFirst: false,
+                includeUnaskedQuestions: false,
+                includeOpenTensions: true,
+                includeWhyMayBeWrong: true,
+                preserveNarrativeTrace: false,
+                surfaceHumanCommitment: false,
+                closureDisposition: "tentative",
+                mandatoryQuestions: ["What assumption is doing the most work in the current structure?"],
+                rationale: ["Review mode should challenge assumptions before settling on synthesis."]
+            };
+        case "critique":
+            return {
+                mode,
+                minimumQuestions: 1,
+                questionTypes: ["boundary", "tension"],
+                mustAskBeforeClosure: false,
+                preferQuestionsFirst: false,
+                includeUnaskedQuestions: false,
+                includeOpenTensions: true,
+                includeWhyMayBeWrong: true,
+                preserveNarrativeTrace: false,
+                surfaceHumanCommitment: false,
+                closureDisposition: "delay",
+                mandatoryQuestions: ["What would have to be false for this conclusion to change?"],
+                rationale: ["Critique mode normalizes instability rather than smoothing it away."]
+            };
+        case "draft":
+            return {
+                mode,
+                minimumQuestions: 0,
+                questionTypes: [],
+                mustAskBeforeClosure: false,
+                preferQuestionsFirst: false,
+                includeUnaskedQuestions: false,
+                includeOpenTensions: false,
+                includeWhyMayBeWrong: false,
+                preserveNarrativeTrace: true,
+                surfaceHumanCommitment: false,
+                closureDisposition: "tentative",
+                mandatoryQuestions: [],
+                rationale: ["Draft mode may structure material, but it should preserve authorial trace."]
+            };
+        case "commit":
+            return {
+                mode,
+                minimumQuestions: 0,
+                questionTypes: ["boundary"],
+                mustAskBeforeClosure: false,
+                preferQuestionsFirst: false,
+                includeUnaskedQuestions: false,
+                includeOpenTensions: true,
+                includeWhyMayBeWrong: false,
+                preserveNarrativeTrace: false,
+                surfaceHumanCommitment: true,
+                closureDisposition: "strong",
+                mandatoryQuestions: ["What choice is the researcher personally committing to here?"],
+                rationale: ["Commit mode should make human responsibility explicit."]
+            };
+        case "submit":
+            return {
+                mode,
+                minimumQuestions: 0,
+                questionTypes: ["boundary"],
+                mustAskBeforeClosure: true,
+                preferQuestionsFirst: false,
+                includeUnaskedQuestions: false,
+                includeOpenTensions: true,
+                includeWhyMayBeWrong: true,
+                preserveNarrativeTrace: false,
+                surfaceHumanCommitment: true,
+                closureDisposition: "strongest",
+                mandatoryQuestions: [
+                    "What claim or risk still requires explicit human responsibility before submission?"
+                ],
+                rationale: ["Submit mode keeps final risks visible before external release."]
+            };
+    }
+}
+function addQuestionType(types, type) {
+    return unique([...types, type]);
+}
+export function resolveRuntimeGuidance(profile, signal, policy = resolveCheckpointPolicy(profile, signal)) {
+    const guidance = createBaseGuidance(signal.mode);
+    const unresolvedTensions = [
+        ...(signal.unresolvedTensions ?? []),
+        ...(signal.studyContract?.openTensions ?? [])
+    ];
+    if (unresolvedTensions.length > 0) {
+        guidance.includeOpenTensions = true;
+        guidance.minimumQuestions = Math.max(guidance.minimumQuestions, 1);
+        guidance.questionTypes = addQuestionType(guidance.questionTypes, "tension");
+        guidance.rationale.push("Open tensions remain visible when a decision could still move.");
+        pushQuestion(guidance.mandatoryQuestions, "Which unresolved tension still matters enough to change the decision?");
+    }
+    if (!signal.studyContract && (signal.mode === "commit" || signal.mode === "submit")) {
+        guidance.minimumQuestions = Math.max(guidance.minimumQuestions, 1);
+        guidance.mustAskBeforeClosure = true;
+        guidance.questionTypes = addQuestionType(guidance.questionTypes, "clarifying");
+        guidance.rationale.push("Commitment without an attached study contract should force a clarifying question.");
+        pushQuestion(guidance.mandatoryQuestions, "What study contract commitment is still missing before this decision can be finalized?");
+    }
+    if (signal.artifactStakes === "external_submission") {
+        guidance.minimumQuestions = Math.max(guidance.minimumQuestions, 1);
+        guidance.mustAskBeforeClosure = true;
+        guidance.surfaceHumanCommitment = true;
+        guidance.includeWhyMayBeWrong = true;
+        guidance.closureDisposition = "strongest";
+        guidance.questionTypes = addQuestionType(guidance.questionTypes, "boundary");
+        guidance.rationale.push("External submission requires an explicit human responsibility check.");
+        pushQuestion(guidance.mandatoryQuestions, "What remaining risk would be unacceptable to release without direct human review?");
+    }
+    if (profile.humanAuthorshipSignal &&
+        (signal.mode === "draft" || signal.mode === "review" || signal.mode === "critique" || signal.researchStage === "writing")) {
+        guidance.preserveNarrativeTrace = true;
+        guidance.questionTypes = addQuestionType(guidance.questionTypes, "narrative");
+        guidance.rationale.push("The researcher profile asks LongTable to protect a recognizable human authorship signal.");
+        pushQuestion(guidance.mandatoryQuestions, `What in this output should preserve ${profile.humanAuthorshipSignal}?`);
+    }
+    if (policy.blocking && (signal.mode === "commit" || signal.mode === "submit")) {
+        guidance.minimumQuestions = Math.max(guidance.minimumQuestions, 1);
+        guidance.mustAskBeforeClosure = true;
+        guidance.surfaceHumanCommitment = true;
+        guidance.rationale.push("Blocking checkpoints require at least one explicit human-facing question before closure.");
+    }
+    if (signal.mode === "review" || signal.mode === "critique") {
+        guidance.includeWhyMayBeWrong = true;
+    }
+    guidance.questionTypes = unique(guidance.questionTypes);
+    guidance.mandatoryQuestions = unique(guidance.mandatoryQuestions);
+    return guidance;
+}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+import type { ArtifactStakes, CheckpointLevel, InteractionMode, PromptStyle, ResearchStage, StudyContract } from "@longtable/core";
+export interface CheckpointSignal {
+    checkpointKey: string;
+    baseLevel: CheckpointLevel;
+    mode: InteractionMode;
+    artifactStakes: ArtifactStakes;
+    researchStage: ResearchStage;
+    unresolvedTensions?: string[];
+    studyContract?: StudyContract;
+}
+export interface ResolvedCheckpointPolicy {
+    checkpointKey: string;
+    level: CheckpointLevel;
+    blocking: boolean;
+    promptStyle: PromptStyle;
+    requiresDecisionLog: boolean;
+    updateExplicitState: boolean;
+    rationale: string[];
+}
+export type { ArtifactStakes, ClosureDisposition, CheckpointLevel, GuidanceQuestionType, InteractionMode, PromptStyle, ResearcherProfile, ResearchStage, RuntimeGuidance, StudyContract } from "@longtable/core";

package/dist/types.js

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

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@longtable/checkpoints",
+  "version": "0.1.9",
+  "private": false,
+  "description": "Checkpoint policy engine for LongTable",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@longtable/core": "0.1.9"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "longtable",
+    "research",
+    "checkpoints",
+    "governance"
+  ],
+  "author": "Hosung You",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HosungYou/LongTable.git"
+  },
+  "homepage": "https://github.com/HosungYou/LongTable#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}