Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(ok): stop checkpoint cleanup destroying consolidated history (#3005)
Nick Gomezafbf40ea7cd3
diff --git a/.changeset/checkpoint-chain-anchoring.md b/.changeset/checkpoint-chain-anchoring.mdnew file mode 100644index 000000000..3f17437c3--- /dev/null+++ b/.changeset/checkpoint-chain-anchoring.md@@ -0,0 +1,7 @@+---+"@inkeep/open-knowledge": patch+---++Version history that a consolidation had folded away could be destroyed by routine checkpoint cleanup. Consolidation picked the single newest checkpoint to chain onto, without regard to what kind it was. The silent rescue checkpoints written when the editor bridge detects content loss are parentless, so whenever one of them happened to be newest, the new consolidation chained onto a dead end and the previous consolidation was left dangling. The next cleanup pass then deleted that dangling checkpoint's ref, and with nothing else pointing at it, its full content snapshot and every edit it had folded in became unreachable and were lost at the next git garbage collection. A same-second pair of consolidations could fork the chain the same way with no rescue checkpoint involved at all.++Consolidation now adopts every dangling anchor rather than the single newest one, and only checkpoints whose retention cannot be emptied are eligible to anchor. Cleanup is non-destructive again. Two side effects of the old behavior are also fixed: a rescue checkpoint is no longer kept alive forever by being chained onto, so the retention budget that expires it now genuinely does, and the per-document activity history no longer goes silently empty after a rescue checkpoint lands following a consolidation.diff --git a/knip.config.ts b/knip.config.tsindex 563d574d8..64bfa20a9 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -122,7 +122,9 @@ export default {'packages/server': {entry: ['src/**/*.test.ts', 'src/parse-worker.ts'],project: 'src/**',- ignoreDependencies: ['@types/shell-quote'],+ ignoreDependencies: [+ '@types/shell-quote',+ ],},'packages/cli': {entry: ['src/**/*.test.ts', 'scripts/*.ts', 'tests/**/*.ts', 'src/parse-worker.ts'],diff --git a/packages/core/src/bridge/bind-frontmatter-doc.ts b/packages/core/src/bridge/bind-frontmatter-doc.tsindex c014b1413..8f9d95287 100644--- a/packages/core/src/bridge/bind-frontmatter-doc.ts+++ b/packages/core/src/bridge/bind-frontmatter-doc.ts@@ -1,3 +1,4 @@+import type * as Y from 'yjs';import type { Err, Ok, Result } from '../config/result.ts';import { type FrontmatterValidationError, toFrontmatterIssue } from '../frontmatter/errors.ts';diff --git a/packages/core/src/bridge/bridge-invariant.ts b/packages/core/src/bridge/bridge-invariant.tsindex 005627195..8bfdb40cd 100644--- a/packages/core/src/bridge/bridge-invariant.ts+++ b/packages/core/src/bridge/bridge-invariant.ts@@ -1,3 +1,4 @@+import { fnv1aDigest } from './hash-util.ts';export type BridgeInvariantSite = 'observer-b' | 'persistence' | 'test-harness';diff --git a/packages/core/src/bridge/doc-boundary-space.ts b/packages/core/src/bridge/doc-boundary-space.tsindex 8890f6739..c18c086d5 100644--- a/packages/core/src/bridge/doc-boundary-space.ts+++ b/packages/core/src/bridge/doc-boundary-space.ts@@ -1,3 +1,4 @@+import { FRONTMATTER_RE, stripFrontmatter } from '../extensions/frontmatter.ts';const LEADING_BOUNDARY_RE = /^(?:\r?\n)+/;diff --git a/packages/core/src/bridge/growth-detect.ts b/packages/core/src/bridge/growth-detect.tsindex 9d9c244b0..463e89595 100644--- a/packages/core/src/bridge/growth-detect.ts+++ b/packages/core/src/bridge/growth-detect.ts@@ -1,3 +1,4 @@+const DEFAULT_MIN_SUBSTANTIVE_LINE_LENGTH = 16;export const DUPLICATION_GATE_MIN_LINE_LENGTH = 8;diff --git a/packages/core/src/bridge/intraline-predicate.ts b/packages/core/src/bridge/intraline-predicate.tsindex c43fdd7e7..0939885bb 100644--- a/packages/core/src/bridge/intraline-predicate.ts+++ b/packages/core/src/bridge/intraline-predicate.ts@@ -1,3 +1,4 @@+export function rawLineCounts(doc: string): Map<string, number> {const counts = new Map<string, number>();for (const line of doc.split('\n')) {diff --git a/packages/core/src/bridge/merge-three-way.ts b/packages/core/src/bridge/merge-three-way.tsindex 251560a35..c0dc65705 100644--- a/packages/core/src/bridge/merge-three-way.ts+++ b/packages/core/src/bridge/merge-three-way.ts@@ -65,6 +65,7 @@ export function tryLineLevelCombine(return { clean: true, merged };}+export type BridgeMergeContentLossSide = 'user' | 'agent';export type BridgeMergeContentLossWhich = 'substring' | 'order' | 'growth';diff --git a/packages/core/src/bridge/normalize.ts b/packages/core/src/bridge/normalize.tsindex 4b8890476..3f0880aa5 100644--- a/packages/core/src/bridge/normalize.ts+++ b/packages/core/src/bridge/normalize.ts@@ -1,3 +1,4 @@+const COMMONMARK_ESCAPE_RE = /\\([!"#$%&'()*+,\-./:;<=>?@[\]^_`{|}~])/g;const TABLE_ALIGN_ROW_RE = /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?\s*$/;diff --git a/packages/core/src/bridge/pm-structural-equivalence.ts b/packages/core/src/bridge/pm-structural-equivalence.tsindex 754dc5cc2..0be5203e4 100644--- a/packages/core/src/bridge/pm-structural-equivalence.ts+++ b/packages/core/src/bridge/pm-structural-equivalence.ts@@ -32,6 +32,7 @@ const BR_SENTINEL: PmStructuralNode = { type: '__br__' };const BR_LITERAL_RE = /^<br\s*\/?>$/i;+interface DegradeEntry {readonly label: string;readonly severity: ToleranceClassSeverity;@@ -127,6 +128,7 @@ export interface ComparePmStructuralOptions {ignoreAttrs?: (attrKey: string) => boolean;}+/** Rebuild a node with `fn` applied to each child; identity when childless.* Shared by the degrade canonicalizers so none re-implements the walk. */function mapChildren(@@ -248,6 +250,7 @@ function applyDegrades(tree: PmStructuralNode): {return { normalized: current, fired };}+export function comparePmStructural(expected: PmStructuralNode,actual: PmStructuralNode,diff --git a/packages/core/src/bridge/subsequence.ts b/packages/core/src/bridge/subsequence.tsindex af20de1e2..dca644141 100644--- a/packages/core/src/bridge/subsequence.ts+++ b/packages/core/src/bridge/subsequence.ts@@ -1,3 +1,4 @@+/** True when `needle` is a subsequence of `haystack` (two-pointer, O(n+m)):* insertions in `haystack` are free; any dropped or substituted `needle` byte* fails. */diff --git a/packages/core/src/checkpoint-kinds.ts b/packages/core/src/checkpoint-kinds.tsindex 6e4c339c9..acdc193b9 100644--- a/packages/core/src/checkpoint-kinds.ts+++ b/packages/core/src/checkpoint-kinds.ts@@ -441,6 +441,21 @@ export interface CheckpointKindAttributes {gcBucket: CheckpointKind;/** How rows of this kind may appear in a consent-gated diagnostic bundle. */bundleExposure: CheckpointBundleExposure;+ /**+ * Whether a checkpoint of this kind may anchor the consolidation chain — the+ * set a new checkpoint adopts as parents so that reaping an older checkpoint+ * ref leaves its commit reachable.+ *+ * Only a kind GC cannot empty qualifies. A count-only bucket always retains+ * its newest N, so at least one survives to carry the ancestry; every+ * TTL-bounded bucket can be reaped to nothing, and a chain routed through one+ * would be severed the moment it was.+ *+ * `false` is also what keeps a kind whose metadata embeds verbatim document+ * content from being adopted: a parent edge would make it reachable for as+ * long as the chain lives and silently outlast the budget that expires it.+ */+ chainAnchor: boolean;}/**@@ -461,58 +476,69 @@ export const CHECKPOINT_KIND_REGISTRY = {visibility: 'surfaced',gcBucket: 'bridge-merge-loss',bundleExposure: 'subject-only',+ chainAnchor: false,},'producer-guard-loss': {visibility: 'surfaced',gcBucket: 'producer-guard-loss',bundleExposure: 'metadata',+ chainAnchor: false,},'observer-a-duplication': {visibility: 'surfaced',gcBucket: 'observer-a-duplication',bundleExposure: 'metadata',+ chainAnchor: false,},'external-change-rescue': {visibility: 'surfaced',gcBucket: 'external-change-rescue',bundleExposure: 'metadata',+ chainAnchor: false,},'defer-exhaustion-loss': {visibility: 'surfaced',gcBucket: 'defer-exhaustion-loss',bundleExposure: 'metadata',+ chainAnchor: false,},// `lostSubstrings` is verbatim document content — subject-only.'observer-a-apply-loss': {visibility: 'surfaced',gcBucket: 'observer-a-apply-loss',bundleExposure: 'subject-only',+ chainAnchor: false,},// `lostSubstrings` is verbatim document content — subject-only.'bridge-derive-loss': {visibility: 'surfaced',gcBucket: 'bridge-derive-loss',bundleExposure: 'subject-only',+ chainAnchor: false,},'bridge-backstop-trip': {visibility: 'surfaced',gcBucket: 'bridge-backstop-trip',bundleExposure: 'metadata',+ chainAnchor: false,},'persistence-reconcile-loss': {visibility: 'surfaced',gcBucket: 'persistence-reconcile-loss',bundleExposure: 'metadata',+ chainAnchor: false,},'persistence-duplication-reset': {visibility: 'surfaced',gcBucket: 'persistence-duplication-reset',bundleExposure: 'metadata',+ chainAnchor: false,},'auto-consolidation': {visibility: 'hidden',gcBucket: 'auto-consolidation',bundleExposure: 'none',+ chainAnchor: true,},} as const satisfies Record<CheckpointKind, CheckpointKindAttributes>;@@ -529,3 +555,15 @@ export function isSurfacedCheckpointKind(kind: CheckpointKind | null | undefinedif (kind == null) return true;return CHECKPOINT_KIND_REGISTRY[kind].visibility === 'surfaced';}++/**+ * Whether a checkpoint kind may anchor the consolidation chain.+ *+ * `null` / `undefined` — an untyped user `Save Version` checkpoint, or one+ * whose body line was missing or malformed — anchors. Those are retained+ * permanently, so a chain routed through one can never be severed by GC.+ */+export function isChainAnchorCheckpointKind(kind: CheckpointKind | null | undefined): boolean {+ if (kind == null) return true;+ return CHECKPOINT_KIND_REGISTRY[kind].chainAnchor;+}diff --git a/packages/core/src/markdown/callout-transformer.ts b/packages/core/src/markdown/callout-transformer.tsindex 83d47404a..a363dfd54 100644--- a/packages/core/src/markdown/callout-transformer.ts+++ b/packages/core/src/markdown/callout-transformer.ts@@ -1,3 +1,4 @@+import type { Blockquote, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/code-fence.ts b/packages/core/src/markdown/code-fence.tsindex 9807a7e82..4499dbc92 100644--- a/packages/core/src/markdown/code-fence.ts+++ b/packages/core/src/markdown/code-fence.ts@@ -1,3 +1,4 @@+export function selectFenceChar(info: string): '`' | '~' {return info.includes('`') ? '~' : '`';}diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.tsindex 7415c474a..34704165b 100644--- a/packages/core/src/markdown/comment-promoter.ts+++ b/packages/core/src/markdown/comment-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, PhrasingContent, Root, RootContent, Text } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/dedent-block-jsx-close.ts b/packages/core/src/markdown/dedent-block-jsx-close.tsindex ece5c02a1..b6299a948 100644--- a/packages/core/src/markdown/dedent-block-jsx-close.ts+++ b/packages/core/src/markdown/dedent-block-jsx-close.ts@@ -1,3 +1,4 @@+import { findFencedRegions, isInsideFence } from './fence-regions.ts';const INDENTED_BLOCK_JSX_CLOSE_RE = /^([ ]{1,3})(<\/[A-Z][A-Za-z0-9_]*\s*>)([ \t]*)$/gm;diff --git a/packages/core/src/markdown/details-accordion-promoter.ts b/packages/core/src/markdown/details-accordion-promoter.tsindex 54774764a..acd398aa6 100644--- a/packages/core/src/markdown/details-accordion-promoter.ts+++ b/packages/core/src/markdown/details-accordion-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/div-align-promoter.ts b/packages/core/src/markdown/div-align-promoter.tsindex 43ecdc709..ba9b56384 100644--- a/packages/core/src/markdown/div-align-promoter.ts+++ b/packages/core/src/markdown/div-align-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Paragraph, Parent, Root, Text } from 'mdast';import type { MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/fence-regions.ts b/packages/core/src/markdown/fence-regions.tsindex c7518d614..fb5ac8e8a 100644--- a/packages/core/src/markdown/fence-regions.ts+++ b/packages/core/src/markdown/fence-regions.ts@@ -1,3 +1,4 @@+const FENCE_RE = /^(`{3,}|~{3,})/gm;export function findFencedRegions(src: string): Array<[number, number]> {diff --git a/packages/core/src/markdown/fixtures/index.ts b/packages/core/src/markdown/fixtures/index.tsindex 00f5771ee..6931623c7 100644--- a/packages/core/src/markdown/fixtures/index.ts+++ b/packages/core/src/markdown/fixtures/index.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -8,6 +9,7 @@ function fixturePath(...segments: string[]): string {return resolve(FIXTURES_DIR, ...segments);}+interface GfmExample {section: string;markdown: string;@@ -17,6 +19,7 @@ export function loadGfmExamples(): GfmExample[] {return JSON.parse(readFileSync(fixturePath('gfm', 'examples.json'), 'utf8')) as GfmExample[];}+interface MdxCrashEntry {id: string;input: string;@@ -68,6 +71,7 @@ export function loadLargeEmbedFixtures(): LargeEmbedFixture[] {) as LargeEmbedFixture[];}+export function loadPrd6955Before(): string {return readFileSync(fixturePath('regression', 'prd-6955-before.md'), 'utf8');}@@ -76,6 +80,7 @@ export function loadPrd6955CorruptedTriplicated(): string {return readFileSync(fixturePath('regression', 'prd-6955-corrupted-triplicated.md'), 'utf8');}+export interface NgPinnedCase {id: string;name: string;@@ -92,6 +97,7 @@ export function loadNgPinnedCases(): NgPinnedCase[] {) as NgPinnedCase[];}+export function loadLargeRealistic(): string {return readFileSync(fixturePath('perf', 'large-realistic.md'), 'utf8');}diff --git a/packages/core/src/markdown/fixtures/perf/generate.ts b/packages/core/src/markdown/fixtures/perf/generate.tsindex 8b1eb8519..daa3ef82b 100644--- a/packages/core/src/markdown/fixtures/perf/generate.ts+++ b/packages/core/src/markdown/fixtures/perf/generate.ts@@ -1,3 +1,4 @@+import { writeFileSync } from 'node:fs';import { dirname, resolve } from 'node:path';import { fileURLToPath } from 'node:url';@@ -10,6 +11,7 @@ const BASELINE_ONLY_COUNTS = [500, 2500] as const;const SEED = 0xf1de1117;+function mulberry32(seed: number): () => number {let a = seed >>> 0;return () => {@@ -36,6 +38,7 @@ function pickWeighted<T>(rand: () => number, items: readonly [T, number][]): T {return items[items.length - 1][0];}+const WORDS = ['lorem','ipsum',@@ -153,6 +156,7 @@ function mdxBlock(rand: () => number): string {return `<${name}>\n\n${sentence(rand)}\n\n</${name}>`;}+type BlockKind = 'paragraph' | 'heading' | 'list' | 'code' | 'table' | 'mdx';const MIX: readonly [BlockKind, number][] = [@@ -191,6 +195,7 @@ function generateDocument(blockCount: number, seed: number): string {return `${blocks.join('\n\n')}\n`;}+function main(): void {for (const count of [...BLOCK_COUNTS, ...BASELINE_ONLY_COUNTS]) {const doc = generateDocument(count, SEED);diff --git a/packages/core/src/markdown/guard-flanking-matrix.ts b/packages/core/src/markdown/guard-flanking-matrix.tsindex 420dc0fe5..32c055c5b 100644--- a/packages/core/src/markdown/guard-flanking-matrix.ts+++ b/packages/core/src/markdown/guard-flanking-matrix.ts@@ -7,6 +7,7 @@ import {import { BACKSLASH_GUARD_SUBSTITUTIONS, encodeBackslashEscapes } from './backslash-escape-guard.ts';import { ENTITY_REF_GUARD_SUBSTITUTIONS, encodeEntityRefs } from './entity-ref-guard.ts';+export const ATTENTION_DELIMITERS = ['*', '_', '**', '~~', '=='] as const;export type FlankClass = 'whitespace' | 'punctuation' | 'other';diff --git a/packages/core/src/markdown/handler-shadow-audit.ts b/packages/core/src/markdown/handler-shadow-audit.tsindex 2653473da..283913255 100644--- a/packages/core/src/markdown/handler-shadow-audit.ts+++ b/packages/core/src/markdown/handler-shadow-audit.ts@@ -1,3 +1,4 @@+export interface HandlerShadowWitness {input: string;expect: 'byte' | 'byte-and-reparse-type';diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.tsindex da0a81d23..5d1000cc4 100644--- a/packages/core/src/markdown/highlight-promoter.ts+++ b/packages/core/src/markdown/highlight-promoter.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, PhrasingContent, Root, Text } from 'mdast';import type { MdxJsxTextElement } from 'mdast-util-mdx';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/html-to-mdast.ts b/packages/core/src/markdown/html-to-mdast.tsindex b1f252c31..8dc3a81b5 100644--- a/packages/core/src/markdown/html-to-mdast.ts+++ b/packages/core/src/markdown/html-to-mdast.ts@@ -1,3 +1,4 @@+import type { Root as HastRoot } from 'hast';import type { List, Root as MdastRoot } from 'mdast';import rehypeParse from 'rehype-parse';@@ -85,7 +86,8 @@ export function htmlToMdast(html: string, options?: HtmlToMdastOptions): MdastRothrow new HtmlPayloadTooLargeError(html.length, maxBytes);}- const processor = unified().use(rehypeParse, { fragment: true });+ const processor = unified()+ .use(rehypeParse, { fragment: true });for (const plugin of cleanupPlugins) {processor.use(plugin);diff --git a/packages/core/src/markdown/image-promoter.ts b/packages/core/src/markdown/image-promoter.tsindex 706fa9afb..994eb6917 100644--- a/packages/core/src/markdown/image-promoter.ts+++ b/packages/core/src/markdown/image-promoter.ts@@ -1,3 +1,4 @@+import type { Image, Paragraph, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.tsindex 8b36807fd..fc30bda02 100644--- a/packages/core/src/markdown/index.ts+++ b/packages/core/src/markdown/index.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromPmMark,@@ -196,6 +197,7 @@ export class MarkdownManager {}}+const registry = createRegistry();function destructureAttrs(@@ -244,6 +246,7 @@ function destructureAttrs(return result;}+function hasDirtyDescendant(node: PmNode): boolean {let found = false;node.descendants((child) => {@@ -263,6 +266,7 @@ function effectiveDirty(node: PmNode, freshnessChecker?: StructuralFreshnessChecreturn freshnessChecker ? freshnessChecker.isDiverged(node.toJSON()) : false;}+function isEmptyMdastParagraph(node: MdastNodes): boolean {if (node.type !== 'paragraph') return false;const children = node.children ?? [];@@ -331,6 +335,7 @@ function extractTextFromMdastNodes(nodes: MdastNodes[]): string {return out;}+import {AUDIO_EXTENSIONS,FILE_ATTACHMENT_EXTENSIONS,@@ -577,6 +582,7 @@ function buildMdastToPmHandlers(}));}+if (m.emphasis) {handlers.emphasis = toPmMark(m.emphasis, (node: Emphasis) => ({sourceDelimiter: node.data?.sourceDelimiter ?? '*',@@ -657,6 +663,7 @@ function buildMdastToPmHandlers(}));}+if (m.link) {const sourceLiteralMark = m.sourceLiteral;handlers.link = (node: Link, _parent: MdastParent, state: MdastToPmState) => {@@ -935,6 +942,7 @@ function buildMdastToPmHandlers(};}+const blockUnknownHandler = (node: {type: string;position?: { start: { offset: number }; end: { offset: number } };@@ -1060,6 +1068,7 @@ function buildMdastToPmHandlers(return handlers as RemarkProseMirrorOptions['handlers'];}+function buildPmToMdastHandlers(schema: Schema,freshness: FreshnessCheckerHolder,diff --git a/packages/core/src/markdown/lint/applies-to.ts b/packages/core/src/markdown/lint/applies-to.tsindex fa0be9e86..b79e9aef7 100644--- a/packages/core/src/markdown/lint/applies-to.ts+++ b/packages/core/src/markdown/lint/applies-to.ts@@ -1,3 +1,4 @@+import picomatch from 'picomatch';import { SUPPORTED_DOC_EXTENSIONS } from '../../constants/doc-extensions.ts';diff --git a/packages/core/src/markdown/lint/config-files.ts b/packages/core/src/markdown/lint/config-files.tsindex 312c9c74b..94b34dee1 100644--- a/packages/core/src/markdown/lint/config-files.ts+++ b/packages/core/src/markdown/lint/config-files.ts@@ -1,3 +1,4 @@+const MARKDOWNLINT_JSON_CONFIG_FILES: ReadonlySet<string> = new Set(['.markdownlint.json','.markdownlint.jsonc',diff --git a/packages/core/src/markdown/lint/config-schemas.ts b/packages/core/src/markdown/lint/config-schemas.tsindex 3162881fc..d41c42367 100644--- a/packages/core/src/markdown/lint/config-schemas.ts+++ b/packages/core/src/markdown/lint/config-schemas.ts@@ -38,6 +38,7 @@ const fullPluginShape = Object.fromEntries(LINT_PLUGINS.map((plugin) => [plugin.id, plugin.sliceSchema]),) as z.ZodRawShape;+export const LinterConfigSchema = z.object({enabled: z.boolean(),plugins: z.object(fullPluginShape),diff --git a/packages/core/src/markdown/lint/default-config.ts b/packages/core/src/markdown/lint/default-config.tsindex d48eea5e4..a51f2ffb0 100644--- a/packages/core/src/markdown/lint/default-config.ts+++ b/packages/core/src/markdown/lint/default-config.ts@@ -6,6 +6,7 @@ export const DEFAULT_MARKDOWNLINT_CONFIG: Record<string, MarkdownlintRuleSettingMD013: false,};+export function resolveMarkdownlintConfig(rules: Record<string, MarkdownlintRuleSetting> | undefined,): Configuration {diff --git a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts b/packages/core/src/markdown/lint/frontmatter-schema-edit.tsindex ef478e268..9c9542661 100644--- a/packages/core/src/markdown/lint/frontmatter-schema-edit.ts+++ b/packages/core/src/markdown/lint/frontmatter-schema-edit.ts@@ -1,3 +1,4 @@+import { CANONICAL_SCHEMA_DIALECT_URIS, DEFAULT_SCHEMA_DIALECT } from './frontmatter-validate.ts';export interface FrontmatterFieldConstraint {diff --git a/packages/core/src/markdown/lint/frontmatter-validate.ts b/packages/core/src/markdown/lint/frontmatter-validate.tsindex 3871ccada..997f71794 100644--- a/packages/core/src/markdown/lint/frontmatter-validate.ts+++ b/packages/core/src/markdown/lint/frontmatter-validate.ts@@ -1,3 +1,4 @@+import Ajv, { type ValidateFunction } from 'ajv';import Ajv2019 from 'ajv/dist/2019.js';import Ajv2020 from 'ajv/dist/2020.js';diff --git a/packages/core/src/markdown/lint/index.ts b/packages/core/src/markdown/lint/index.tsindex ce0db23a3..e371f6a6c 100644--- a/packages/core/src/markdown/lint/index.ts+++ b/packages/core/src/markdown/lint/index.ts@@ -1,3 +1,4 @@+import { LINT_PLUGINS, type LinterConfig } from './plugins.ts';import type { LintDiagnostic } from './types.ts';diff --git a/packages/core/src/markdown/lint/plugins.ts b/packages/core/src/markdown/lint/plugins.tsindex 5e832aa19..be5871ed9 100644--- a/packages/core/src/markdown/lint/plugins.ts+++ b/packages/core/src/markdown/lint/plugins.ts@@ -1,3 +1,4 @@+import { z } from 'zod';import { DEFAULT_MARKDOWNLINT_CONFIG, resolveMarkdownlintConfig } from './default-config.ts';import {@@ -13,6 +14,7 @@ import {type MarkdownlintSlice,} from './types.ts';+const MarkdownlintRuleSettingSchema = z.union([z.boolean(),z.enum(MARKDOWNLINT_RULE_SEVERITIES),diff --git a/packages/core/src/markdown/lint/types.ts b/packages/core/src/markdown/lint/types.tsindex da6c477e9..772183427 100644--- a/packages/core/src/markdown/lint/types.ts+++ b/packages/core/src/markdown/lint/types.ts@@ -1,3 +1,4 @@+export const LINT_PLUGIN_IDS = ['markdownlint', 'frontmatter'] as const;export type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];@@ -69,6 +70,7 @@ export interface FrontmatterSlice {schemas: ResolvedFrontmatterSchemaEntry[];}+interface RuleOptionSpecBase {key: string;description: string;diff --git a/packages/core/src/markdown/math-promoter.ts b/packages/core/src/markdown/math-promoter.tsindex a5b511f25..bd79424c7 100644--- a/packages/core/src/markdown/math-promoter.ts+++ b/packages/core/src/markdown/math-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { Math as MdastMath } from 'mdast-util-math';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-hast-handlers.ts b/packages/core/src/markdown/mdast-to-hast-handlers.tsindex 679c72ef7..f84967798 100644--- a/packages/core/src/markdown/mdast-to-hast-handlers.ts+++ b/packages/core/src/markdown/mdast-to-hast-handlers.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Properties } from 'hast';import type { FootnoteDefinition, FootnoteReference } from 'mdast';import type { MdxJsxFlowElement, MdxJsxTextElement } from 'mdast-util-mdx';diff --git a/packages/core/src/markdown/mdast-to-html.ts b/packages/core/src/markdown/mdast-to-html.tsindex 8ce2b2492..df788a80d 100644--- a/packages/core/src/markdown/mdast-to-html.ts+++ b/packages/core/src/markdown/mdast-to-html.ts@@ -1,3 +1,4 @@+import type { Element, Root as HastRoot, Text as HastText } from 'hast';import type { Root as MdastRoot, Text as MdastText } from 'mdast';import type { Handler } from 'mdast-util-to-hast';diff --git a/packages/core/src/markdown/merged-walker.ts b/packages/core/src/markdown/merged-walker.tsindex bfd7e3109..fa3cfcd86 100644--- a/packages/core/src/markdown/merged-walker.ts+++ b/packages/core/src/markdown/merged-walker.ts@@ -1,3 +1,4 @@+import type { Nodes, Parent, Root } from 'mdast';import { SKIP, visit } from 'unist-util-visit';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/mermaid-promoter.ts b/packages/core/src/markdown/mermaid-promoter.tsindex 1a897fca8..17ed2b829 100644--- a/packages/core/src/markdown/mermaid-promoter.ts+++ b/packages/core/src/markdown/mermaid-promoter.ts@@ -1,3 +1,4 @@+import type { Code, Root } from 'mdast';import type { MdxJsxAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import { visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/parse-with-fallback.ts b/packages/core/src/markdown/parse-with-fallback.tsindex 9864b3b60..7e4a9a48b 100644--- a/packages/core/src/markdown/parse-with-fallback.ts+++ b/packages/core/src/markdown/parse-with-fallback.ts@@ -168,6 +168,7 @@ export function parseRecursive(}}+interface VFilePlace {offset?: number;start?: { offset?: number };@@ -186,6 +187,7 @@ function extractErrorOffset(err: unknown): number | undefined {return undefined;}+interface Region {start: number;end: number;@@ -209,6 +211,7 @@ function nearestBlankLineAfter(src: string, offset: number): number | null {return null;}+export interface TagEvent {kind: 'open' | 'close' | 'self-close';name: string;@@ -355,6 +358,7 @@ function findFallbackRegion(src: string, errorOffset: number): Region {return { start: blockStart, end: blockEnd };}+interface SourceBlock {src: string;start: number;@@ -452,6 +456,7 @@ function tryPerBlockFallback(};}+function wholeDocRawText(source: string): JSONContent {return {type: 'doc',diff --git a/packages/core/src/markdown/parser-drop-closure.ts b/packages/core/src/markdown/parser-drop-closure.tsindex e6ab4fd57..43d420187 100644--- a/packages/core/src/markdown/parser-drop-closure.ts+++ b/packages/core/src/markdown/parser-drop-closure.ts@@ -1,3 +1,4 @@+export type DroppedTokenAdjudication =| {kind: 'format-dof-axis';diff --git a/packages/core/src/markdown/pipeline.ts b/packages/core/src/markdown/pipeline.tsindex 21bc33473..d46238f00 100644--- a/packages/core/src/markdown/pipeline.ts+++ b/packages/core/src/markdown/pipeline.ts@@ -1,3 +1,4 @@+import {type FromProseMirrorOptions,fromProseMirror,diff --git a/packages/core/src/markdown/position-aware-join.ts b/packages/core/src/markdown/position-aware-join.tsindex 5a5e4c42a..f8f5e8530 100644--- a/packages/core/src/markdown/position-aware-join.ts+++ b/packages/core/src/markdown/position-aware-join.ts@@ -1,3 +1,4 @@+import type { Join } from 'mdast-util-to-markdown';import type { Position } from 'unist';diff --git a/packages/core/src/markdown/position-slice.ts b/packages/core/src/markdown/position-slice.tsindex 0f399d34c..e5b4c9eba 100644--- a/packages/core/src/markdown/position-slice.ts+++ b/packages/core/src/markdown/position-slice.ts@@ -1,3 +1,4 @@+import type { Nodes, Root } from 'mdast';import { visit } from 'unist-util-visit';import type { VFile } from 'vfile';@@ -476,7 +477,8 @@ export function applyPositionSliceToNode(const first = source[startOff];if (first !== '[' && first !== '<' && !node.title) {node.data.sourceStyle = 'gfm-autolink';- } else if (first === '[') {+ }+ else if (first === '[') {const slice = source.slice(startOff, endOff);const closeBracketIdx = slice.lastIndexOf('](');if (closeBracketIdx !== -1) {diff --git a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.tsindex db10fa54b..ca225ce9b 100644--- a/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts+++ b/packages/core/src/markdown/rehype-plugins/skip-notion-whitespace.ts@@ -1,3 +1,4 @@+import type { Comment, Element, Root, Text } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.tsindex 34068d103..3a2524a9a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-cocoa-meta.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.tsindex 93151d43b..2279a0189 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gdocs-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.tsindex 188f02d83..a0f467c42 100644--- a/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-github-hovercard.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.tsindex 4ba2c3418..4e8542a21 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gmail-classes.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.tsindex 1a74b1272..a3c96b24a 100644--- a/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-gsheets-wrapper.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.tsindex de35e7b79..e95cf43d6 100644--- a/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-mso-styles.ts@@ -1,3 +1,4 @@+import type { Comment, Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.tsindex b4be1b2ea..ffdb4d5b5 100644--- a/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-slack-classes.ts@@ -1,3 +1,4 @@+import type { Element, ElementContent, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.tsindex 3c8d88b7c..e2a96d1a7 100644--- a/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts+++ b/packages/core/src/markdown/rehype-plugins/strip-vscode-spans.ts@@ -1,3 +1,4 @@+import type { Element, Root } from 'hast';import type { Plugin } from 'unified';diff --git a/packages/core/src/markdown/resolve-image-url.ts b/packages/core/src/markdown/resolve-image-url.tsindex cf2c9da8e..0389575ac 100644--- a/packages/core/src/markdown/resolve-image-url.ts+++ b/packages/core/src/markdown/resolve-image-url.ts@@ -1,3 +1,4 @@+import { isRelativeUrl } from './safe-url.ts';function isDevDiagnosticContext(): boolean {diff --git a/packages/core/src/markdown/safe-url.ts b/packages/core/src/markdown/safe-url.tsindex 4d3250d3a..8be632ba4 100644--- a/packages/core/src/markdown/safe-url.ts+++ b/packages/core/src/markdown/safe-url.ts@@ -1,3 +1,4 @@+export const SAFE_URL_SCHEMES = ['https', 'http', 'mailto', 'tel', 'ftp', 'sms'] as const;const SCHEME_ALT = SAFE_URL_SCHEMES.map((s) => `${s}:`).join('|');diff --git a/packages/core/src/markdown/serialize-fidelity.test-helper.ts b/packages/core/src/markdown/serialize-fidelity.test-helper.tsindex 0dd54070e..96304e7a5 100644--- a/packages/core/src/markdown/serialize-fidelity.test-helper.ts+++ b/packages/core/src/markdown/serialize-fidelity.test-helper.ts@@ -1,3 +1,4 @@+import type { JSONContent } from '@tiptap/core';import type { Nodes } from 'mdast';import { expect } from 'vitest';diff --git a/packages/core/src/markdown/serialize-helpers.ts b/packages/core/src/markdown/serialize-helpers.tsindex 46cc6a074..542204403 100644--- a/packages/core/src/markdown/serialize-helpers.ts+++ b/packages/core/src/markdown/serialize-helpers.ts@@ -1,3 +1,4 @@+import type { Node as PmNode } from '@tiptap/pm/model';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { PropDef, SerializeContext } from '../registry/types.ts';diff --git a/packages/core/src/markdown/single-dollar-math-promoter.ts b/packages/core/src/markdown/single-dollar-math-promoter.tsindex b012a5aff..8c08b7a04 100644--- a/packages/core/src/markdown/single-dollar-math-promoter.ts+++ b/packages/core/src/markdown/single-dollar-math-promoter.ts@@ -1,3 +1,4 @@+import type { PhrasingContent, Root, Text } from 'mdast';import type { InlineMath } from 'mdast-util-math';import { SKIP, visit } from 'unist-util-visit';diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.tsindex 7f6dfcfc3..fd22d2c7b 100644--- a/packages/core/src/markdown/to-markdown-handlers.ts+++ b/packages/core/src/markdown/to-markdown-handlers.ts@@ -1,3 +1,4 @@+import type { Nodes, Parents } from 'mdast';import type { MdxJsxAttribute, MdxJsxExpressionAttribute, MdxJsxFlowElement } from 'mdast-util-mdx';import type { Handle, Info, State } from 'mdast-util-to-markdown';diff --git a/packages/core/src/markdown/unknown-mdast-guard.ts b/packages/core/src/markdown/unknown-mdast-guard.tsindex cd245c38c..c5bfd2386 100644--- a/packages/core/src/markdown/unknown-mdast-guard.ts+++ b/packages/core/src/markdown/unknown-mdast-guard.ts@@ -1,3 +1,4 @@+import type { Root as MdastRoot } from 'mdast';import type { VFile } from 'vfile';diff --git a/packages/core/src/markdown/whitespace-char-ref.ts b/packages/core/src/markdown/whitespace-char-ref.tsindex d578476a7..ac9f5239b 100644--- a/packages/core/src/markdown/whitespace-char-ref.ts+++ b/packages/core/src/markdown/whitespace-char-ref.ts@@ -1,3 +1,4 @@+const INLINE_WHITESPACE_BY_CODE: ReadonlyMap<number, string> = new Map([[0x20, ' '],[0x09, '\t'],diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.tsindex 6dad26200..afd9936fe 100644--- a/packages/core/src/markdown/wiki-link-micromark.ts+++ b/packages/core/src/markdown/wiki-link-micromark.ts@@ -17,6 +17,7 @@ declare module 'micromark-util-types' {}}+const CODE_BANG = 33; // !const CODE_LBRACKET = 91; // [const CODE_RBRACKET = 93; // ]@@ -260,6 +261,7 @@ export function wikiLinkSyntax(): Extension {};}+function enterWikiLink(this: CompileContext, token: Token) {this.enter({@@ -385,6 +387,7 @@ export const wikiLinkToMarkdown: {unsafe: [{ character: '[', inConstruct: ['phrasing'] }],};+const MICROMARK_EXT = wikiLinkSyntax();export function remarkWikiLink(this: Processor) {diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.tsindex d78abf77a..f7cfcec67 100644--- a/packages/core/src/shadow-repo-layout.ts+++ b/packages/core/src/shadow-repo-layout.ts@@ -480,6 +480,7 @@ export {CHECKPOINT_KIND_REGISTRY,CHECKPOINT_KINDS,formatCheckpointBodyLine,+ isChainAnchorCheckpointKind,isSurfacedCheckpointKind,parseCheckpoint,} from './checkpoint-kinds.ts';diff --git a/packages/server/src/checkpoint-chain.test.ts b/packages/server/src/checkpoint-chain.test.tsnew file mode 100644index 000000000..2f5910015--- /dev/null+++ b/packages/server/src/checkpoint-chain.test.ts@@ -0,0 +1,62 @@+import { mkdirSync, writeFileSync } from 'node:fs';+import { mkdtemp, rm } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import { resolve } from 'node:path';+import simpleGit from 'simple-git';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';+import { resolveCheckpointChainAnchors } from './checkpoint-chain.ts';+import {+ initShadowRepo,+ type ShadowHandle,+ saveInMemoryCheckpoint,+ shadowGit,+} from './shadow-repo';++let tmpDir: string;+let projectRoot: string;+let shadow: ShadowHandle;++beforeEach(async () => {+ tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-chain-'));+ projectRoot = resolve(tmpDir, 'project');+ mkdirSync(resolve(projectRoot, 'content/docs'), { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ shadow = await initShadowRepo(projectRoot);+});++afterEach(async () => {+ await rm(tmpDir, { recursive: true, force: true });+});++describe('resolveCheckpointChainAnchors — empty versus unknown', () => {+ // The safety contract rests on these two staying distinguishable. Collapsing+ // them is what let the writer commit a chain-severing checkpoint off any+ // transient git failure.++ test('an empty checkpoint namespace resolves to no anchors without throwing', async () => {+ // `for-each-ref` over an absent namespace exits 0 with no output, so this+ // really is "the first checkpoint" rather than a failed lookup.+ await expect(resolveCheckpointChainAnchors(shadowGit(shadow), 'main')).resolves.toEqual([]);+ });++ test('a failed ref query throws rather than reporting no anchors', async () => {+ // A rescue checkpoint exists, so the namespace is genuinely non-empty and+ // an empty result would be a lie rather than a first-checkpoint case.+ await saveInMemoryCheckpoint(shadow, 'content/docs', {+ kind: 'bridge-merge-loss',+ docName: 'intro.md',+ contents: '# rescued\n',+ label: 'merge loss',+ metadata: { lostSubstrings: ['x'] },+ });+ // A malformed `packed-refs` makes `for-each-ref` fail outright, which is the+ // real shape of the failures this guards (locked gitdir, concurrent prune,+ // spawn error) without mocking the git layer out of the test.+ writeFileSync(resolve(shadow.gitDir, 'packed-refs'), 'garbage not a ref line\n', 'utf-8');++ await expect(resolveCheckpointChainAnchors(shadowGit(shadow), 'main')).rejects.toThrow();+ });+});diff --git a/packages/server/src/checkpoint-chain.ts b/packages/server/src/checkpoint-chain.tsnew file mode 100644index 000000000..c3fa8320d--- /dev/null+++ b/packages/server/src/checkpoint-chain.ts@@ -0,0 +1,115 @@+/**+ * Resolving the checkpoint commits that anchor the consolidation chain.+ *+ * Shared by the consolidation writer (`shadow-repo.ts`, which adopts them as+ * parents) and the per-path activity reader (`content/shadow-log.ts`, which+ * walks their ancestry) so the two cannot disagree about where the chain is.+ */+import {+ isChainAnchorCheckpointKind,+ parseCheckpoint,+} from '@inkeep/open-knowledge-core/shadow-repo-layout';+import type { SimpleGit } from 'simple-git';+import { getLogger } from './logger.ts';++const log = getLogger('checkpoint-chain');++const SHA_LENGTH = 40;++/**+ * The checkpoints on `branch` that a new checkpoint must adopt so that reaping+ * an older checkpoint ref never strands the commit behind it.+ *+ * Two properties are load-bearing, and each fixes a distinct way the chain+ * used to break:+ *+ * - **Kind-filtered.** Only kinds GC cannot empty may anchor+ * (`isChainAnchorCheckpointKind`). The silent rescue kinds are parentless+ * root commits, so a chain routed through one reaches nothing; they are also+ * the kinds whose metadata carries verbatim document content, which a parent+ * edge would keep reachable past the budget that expires it.+ * - **Every tip, not the newest.** One severed chain leaves two dangling+ * anchors, and a single-slot parent can only ever re-attach one of them.+ * Checkpoint dates are one-second granular, so recency cannot separate a+ * tied pair either — this returns the whole independent set rather than+ * fabricating an order over it.+ *+ * The independence reduction runs over the ANCHOR set alone: reachability that+ * only holds through a ref GC may reap is not reachability we can rely on.+ *+ * **Throws rather than returning `[]` when a query fails.** An empty result and+ * a failed lookup are not the same thing: `for-each-ref` over an absent+ * namespace exits 0 with no output, so `[]` means "genuinely the first+ * checkpoint" and nothing else. Swallowing a thrown query would hand the writer+ * an empty anchor set and commit exactly the severed checkpoint this module+ * exists to prevent, from any transient git failure. Callers choose their own+ * policy: the writer lets it propagate so the fold fails and retries, while a+ * read path degrades to an empty history.+ */+export async function resolveCheckpointChainAnchors(+ sg: SimpleGit,+ branch: string,+): Promise<string[]> {+ let refOutput: string;+ try {+ refOutput = await sg.raw(+ 'for-each-ref',+ '--format=%(objectname)',+ `refs/checkpoints/${branch}/`,+ );+ } catch (err) {+ log.warn({ branch, err }, '[checkpoint-chain] for-each-ref failed; anchors are unknown');+ throw err;+ }++ const shas = refOutput+ .trim()+ .split('\n')+ .map((s) => s.trim())+ .filter((s) => s.length === SHA_LENGTH);+ if (shas.length === 0) return [];++ let logRaw: string;+ try {+ logRaw = await sg.raw('log', '--no-walk', '--format=%H%x00%B%x1e', ...shas);+ } catch (err) {+ log.warn(+ { branch, shaCount: shas.length, err },+ '[checkpoint-chain] checkpoint body read failed; anchors are unknown',+ );+ throw err;+ }++ const anchors: string[] = [];+ for (const record of logRaw.split('\x1e')) {+ const trimmed = record.trimStart();+ if (!trimmed) continue;+ const [sha = '', body = ''] = trimmed.split('\x00');+ if (sha.length !== SHA_LENGTH) continue;+ if (isChainAnchorCheckpointKind(parseCheckpoint(body)?.kind ?? null)) anchors.push(sha);+ }+ if (anchors.length <= 1) return anchors;++ try {+ // `--independent` prints the minimal subset — those not reachable from any+ // other — on stdout. The exit-code-only `--is-ancestor` cannot be used+ // here: simple-git rejects on stderr rather than branching on exit status.+ const independent = await sg.raw('merge-base', '--independent', ...anchors);+ const tips = independent+ .trim()+ .split('\n')+ .map((s) => s.trim())+ .filter((s) => s.length === SHA_LENGTH);+ return tips.length > 0 ? tips : anchors;+ } catch (err) {+ // Adopting a redundant parent is harmless; dropping a needed one destroys+ // history, so an unusable reduction falls back to the full anchor set. That+ // fallback is strictly safer than the reduction it replaces, which is why+ // this one failure does not propagate.+ log.warn(+ { branch, anchorCount: anchors.length, err },+ '[checkpoint-chain] tip reduction failed; adopting the full anchor set',+ );+ return anchors;+ }+}diff --git a/packages/server/src/content/shadow-log.test.ts b/packages/server/src/content/shadow-log.test.tsindex f21149556..d3cc17b44 100644--- a/packages/server/src/content/shadow-log.test.ts+++ b/packages/server/src/content/shadow-log.test.ts@@ -1,12 +1,3 @@-import { describe as _bunDescribe, afterEach, beforeEach, expect, test } from 'vitest';--// Skip-on-CI gate (oven-sh/bun#11892): simple-git fixture pattern in this-// test setup spawns git children that Bun fails to reap on ubuntu-latest-// GHA runners; post-test cgroup never drains, hanging test (test) at the-// 15-min timeout. Tests run normally locally; follow-up PR will migrate-// fixtures to execFileSync.-const describe = process.env.CI ? _bunDescribe.skip : _bunDescribe;-import { mkdirSync, writeFileSync } from 'node:fs';import { mkdtemp, rm } from 'node:fs/promises';import { tmpdir } from 'node:os';@@ -14,10 +5,12 @@ import { resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';import { formatOkActor, type OkActorEntry } from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';+import { afterEach, beforeEach, describe, expect, test } from 'vitest';import {commitUpstreamImport,commitWip,initShadowRepo,+ saveInMemoryCheckpoint,saveVersion,type WriterIdentity,} from '../shadow-repo.ts';@@ -321,6 +314,58 @@ describe('readShadowLog — checkpoint-ancestry fallback (PRD-6972 FR7 / D15)',expect(after.commits.every((c) => c.writerClassification === 'agent')).toBe(true);});+ test('parity holds when a loss checkpoint lands after the consolidation', async () => {+ const project = await bootstrapProject();+ const shadow = await initShadowRepo(project);+ const contentDir = resolve(project, 'content');+ mkdirSync(contentDir, { recursive: true });+ const branch = (await simpleGit(project).revparse(['--abbrev-ref', 'HEAD'])).trim();+ const writer: WriterIdentity = { id: 'agent-z', name: 'Agent Z', email: '[email protected]' };++ // Explicit increasing dates order the WIP commits and keep them ahead of+ // the checkpoints below. Git dates are one-second granular, so a short+ // real-time sleep would not order them at all.+ for (let i = 1; i <= 3; i++) {+ writeFileSync(resolve(contentDir, 'auth.md'), `# v${i}\n`);+ await commitWip(+ shadow,+ writer,+ contentDir,+ wipBody(`edit ${i}`, 'agent-z', 'Agent Z'),+ branch,+ { date: `@${1_799_999_000 + i * 100} +0000` },+ );+ }++ const before = await readShadowLog(project, 'content/auth.md', 5);+ expect(before.commits.length).toBe(3);++ await saveVersion(shadow, contentDir, [writer], branch, undefined, {+ checkpointKind: { foldedRefs: 1, trigger: 'dead-chain' },+ date: '@1800000000 +0000',+ });++ // Any bridge trip mints a rescue checkpoint, and it is a parentless root+ // commit. Once it is the newest checkpoint ref, a fallback that walks only+ // the newest one walks a dead end. Explicit dates order the two checkpoints+ // without a >1s sleep (git commit dates are one-second granular).+ await saveInMemoryCheckpoint(shadow, 'content', {+ kind: 'bridge-merge-loss',+ docName: 'auth.md',+ contents: '# rescued\n',+ label: 'merge loss',+ branch,+ metadata: { lostSubstrings: ['x'] },+ date: '@1800000100 +0000',+ });++ const after = await readShadowLog(project, 'content/auth.md', 5);+ expect(after.commits.map((c) => c.hash).sort()).toEqual(+ before.commits.map((c) => c.hash).sort(),+ );+ expect(after.commits.every((c) => c.writerId === 'agent-z')).toBe(true);+ });+test('no checkpoint + no WIP refs → still empty (no false fallback)', async () => {const project = await bootstrapProject();await initShadowRepo(project);diff --git a/packages/server/src/content/shadow-log.ts b/packages/server/src/content/shadow-log.tsindex a33e369ba..181eee139 100644--- a/packages/server/src/content/shadow-log.ts+++ b/packages/server/src/content/shadow-log.ts@@ -18,6 +18,8 @@ import {type WriterClassification,} from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit, { type SimpleGit } from 'simple-git';+import { resolveCheckpointChainAnchors } from '../checkpoint-chain.ts';+import { getLogger } from '../logger.ts';export interface ShadowCommit {hash: string;@@ -130,7 +132,9 @@ async function logOnRef(* Checkpoint-ancestry fallback. When the per-writer WIP* refs are shallow — e.g. immediately after an auto-consolidation folded the* dead chains and deleted their refs — the WIP commits are now reachable ONLY- * through the latest checkpoint's ancestry. Walk it (bounded `-n`) for `relPath`,+ * through the chain anchors' ancestry. Walk every anchor rather than the newest+ * checkpoint ref: the newest is routinely a parentless rescue artifact, and+ * walking that alone silently empties the read. Bounded `-n`, for `relPath`,* skipping the checkpoint/park/import commits themselves and already-seen hashes,* and attribute each surviving WIP commit via its `ok-actor:` body line (the* source of truth — the ref name is gone). Keeps the enriched read populated@@ -143,34 +147,40 @@ async function checkpointAncestryFallback(need: number,seen: Set<string>,): Promise<ShadowCommit[]> {- let latestCheckpoint = '';+ // Anchor resolution throws when a git query fails, because the writer must+ // never commit through an unknown anchor set. A read has no such stake, so it+ // degrades to an empty history like every other failure in this reader.+ let anchors: string[];try {- latestCheckpoint = (- await sg.raw(- 'for-each-ref',- '--sort=-creatordate',- '--count=1',- '--format=%(objectname)',- `refs/checkpoints/${branch}/`,- )- ).trim();- } catch {+ anchors = await resolveCheckpointChainAnchors(sg, branch);+ } catch (err) {+ // The resolver already warns about the git failure itself; this names the+ // consequence at the call site, so a degraded read is distinguishable from+ // an aborted write in the log.+ getLogger('shadow-log').warn(+ { branch, relPath, err },+ '[shadow-log] chain anchors unresolved; per-path history degraded to empty',+ );return [];}- if (!latestCheckpoint) return [];+ if (anchors.length === 0) return [];let out = '';try {// Bounded walk with slack for skipped checkpoint/seen rows.out = await sg.raw('log',- latestCheckpoint,+ ...anchors,`-${Math.max(need * 3, 20)}`,'--format=%H%x00%aI%x00%an%x00%s%x00%B%x1e','--',relPath,);- } catch {+ } catch (err) {+ getLogger('shadow-log').warn(+ { branch, relPath, anchorCount: anchors.length, err },+ '[shadow-log] ancestry walk failed; per-path history degraded to empty',+ );return [];}diff --git a/packages/server/src/shadow-repo.test.ts b/packages/server/src/shadow-repo.test.tsindex 5ab701742..74a0bd38a 100644--- a/packages/server/src/shadow-repo.test.ts+++ b/packages/server/src/shadow-repo.test.ts@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';import { resolve } from 'node:path';import { setTimeout as wait } from 'node:timers/promises';import {+ CHECKPOINT_KIND_REGISTRY,CHECKPOINT_KINDS,type CheckpointKind,formatCheckpointBodyLine,@@ -1660,6 +1661,206 @@ describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)});});+describe('checkpoint chain anchoring', () => {+ let projectRoot: string;+ let shadow: ShadowHandle;++ const WRITER: WriterIdentity = {+ id: 'agent-a',+ name: 'Agent A',+ email: '[email protected]',+ };++ beforeEach(async () => {+ projectRoot = resolve(tmpDir, 'chain-project');+ mkdirSync(resolve(projectRoot, 'content/docs'), { recursive: true });+ const git = simpleGit(projectRoot);+ await git.init();+ await git.raw('config', 'user.name', 'Test');+ await git.raw('config', 'user.email', '[email protected]');+ shadow = await initShadowRepo(projectRoot);+ });++ /** Distinct, increasing commit dates: git stores them at one-second granularity. */+ const at = (rank: number): string => `@${1_700_000_000 + rank * 100} +0000`;++ /** One writer edit, so the next consolidation has a WIP chain to fold. */+ async function edit(tag: string, rank: number): Promise<void> {+ writeFileSync(resolve(projectRoot, 'content/docs/intro.md'), `# ${tag}\n`, 'utf-8');+ await commitWip(shadow, WRITER, 'content/docs', `wip ${tag}`, 'main', { date: at(rank) });+ }++ /** A real service-authored consolidation through the production spine. */+ async function consolidate(tag: string, rank: number): Promise<string> {+ const { checkpointRef } = await saveVersion(shadow, 'content/docs', [WRITER], 'main', tag, {+ checkpointKind: { foldedRefs: 1, trigger: 'dead-chain' },+ date: at(rank),+ });+ return checkpointRef.split('/').pop() as string;+ }++ async function lossCheckpoint(rank: number): Promise<string> {+ return saveInMemoryCheckpoint(shadow, 'content/docs', {+ kind: 'bridge-merge-loss',+ docName: 'intro.md',+ contents: '# rescued\n',+ label: 'merge loss',+ metadata: { lostSubstrings: ['x'] },+ date: at(rank),+ });+ }++ const reachableShas = async (): Promise<string[]> =>+ (await shadowGit(shadow).raw('rev-list', '--all')).trim().split('\n').filter(Boolean);++ const parentsOf = async (sha: string): Promise<string[]> =>+ (await shadowGit(shadow).raw('rev-list', '--parents', '-n', '1', sha))+ .trim()+ .split(/\s+/)+ .slice(1);++ test('a kind anchors the chain exactly when its retention bucket is count-only', async () => {+ // `chainAnchor` (the registry, consumed by the writer and the CLI reader)+ // and `applyTtl` (the GC table) are the same fact stated in two modules:+ // a bucket GC can empty cannot carry the chain. TypeScript cannot express+ // the link across them, so pin it here — if a new kind declares one without+ // the other, reaping its ref starts destroying history silently.+ const { GC_BUCKET_POLICY } = await import('./shadow-repo.ts');+ for (const kind of CHECKPOINT_KINDS) {+ const { chainAnchor, gcBucket } = CHECKPOINT_KIND_REGISTRY[kind];+ expect(`${kind}:chainAnchor=${chainAnchor}`).toBe(+ `${kind}:chainAnchor=${!GC_BUCKET_POLICY[gcBucket].applyTtl}`,+ );+ }+ });++ test('a reaped consolidation stays reachable when a loss checkpoint landed between folds', async () => {+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');++ await edit('one', 1);+ const c1 = await consolidate('auto 1', 2);+ // A routine rescue artifact, newer than c1. It is a parentless root commit,+ // so a chain routed through it reaches nothing.+ await lossCheckpoint(3);+ await edit('two', 4);+ const c2 = await consolidate('auto 2', 5);+ await edit('three', 6);+ await consolidate('auto 3', 7);++ // c1 is now over the keep-2 budget and its ref is reaped. That is only+ // non-destructive if a surviving checkpoint's ancestry still reaches it —+ // the guarantee `maxAutoConsolidation` is documented to rest on.+ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxAutoConsolidation: 2,+ ttlMs: 0,+ });+ expect(gc.deletedAutoConsolidation).toBe(1);++ expect(await parentsOf(c2)).toContain(c1);+ expect(await reachableShas()).toContain(c1);+ });++ test('a consolidation adopts every dangling durable tip, not just one', async () => {+ // One severing event leaves TWO durable tips, so a single-slot chain parent+ // can never re-attach them both. Checkpoint dates are one-second granular,+ // so the surviving tip cannot be picked by recency either.+ await edit('one', 1);+ const c1 = await consolidate('auto 1', 2);+ await lossCheckpoint(3);+ await edit('two', 4);+ const c2 = await consolidate('auto 2', 5);+ await edit('three', 6);+ const c3 = await consolidate('auto 3', 7);++ const reachableFromC3 = (await shadowGit(shadow).raw('rev-list', c3))+ .trim()+ .split('\n')+ .filter(Boolean);+ expect(reachableFromC3).toContain(c2);+ expect(reachableFromC3).toContain(c1);+ });++ test('a consolidation re-joins a chain that is already forked into two durable tips', async () => {+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');+ const sg = shadowGit(shadow);++ await edit('one', 1);+ const c1 = await consolidate('auto 1', 2);++ // A repo the old writer already forked carries two durable tips at once,+ // and no single-slot parent can re-join them. Seed that state directly+ // rather than racing the old writer to produce it: a durable checkpoint+ // that neither reaches c1 nor is reachable from it.+ const tree = (await sg.raw('rev-parse', `${c1}^{tree}`)).trim();+ const severed = (+ await sg+ .env({+ GIT_DIR: shadow.gitDir,+ GIT_AUTHOR_NAME: 'openknowledge',+ GIT_AUTHOR_EMAIL: '[email protected]',+ GIT_COMMITTER_NAME: 'openknowledge',+ GIT_COMMITTER_EMAIL: '[email protected]',+ GIT_AUTHOR_DATE: at(3),+ GIT_COMMITTER_DATE: at(3),+ })+ .raw(+ 'commit-tree',+ tree,+ '-m',+ `checkpoint: severed\n\n${formatCheckpointBodyLine({+ kind: 'auto-consolidation',+ docName: null,+ size: null,+ metadata: { foldedRefs: 1, trigger: 'dead-chain' },+ })}`,+ )+ ).trim();+ await sg.raw('update-ref', `refs/checkpoints/main/${severed}`, severed);++ await edit('two', 4);+ const c2 = await consolidate('auto 2', 5);++ // Adopting only the newest durable anchor would strand c1 here, which is+ // exactly what the count-only budget then destroys.+ const parents = await parentsOf(c2);+ expect(parents).toContain(severed);+ expect(parents).toContain(c1);++ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxAutoConsolidation: 2,+ ttlMs: 0,+ });+ expect(gc.deletedAutoConsolidation).toBe(1);+ expect(await reachableShas()).toContain(c1);+ });++ test('a loss checkpoint is never adopted, so reaping its ref still bounds its content', async () => {+ // Loss metadata embeds verbatim document content, so its retention budget is+ // a data-lifecycle guarantee. Adopting one as a chain parent would keep it+ // reachable forever and silently defeat that expiry.+ const { gcCheckpointRefs } = await import('./shadow-repo.ts');++ await edit('one', 1);+ await consolidate('auto 1', 2);+ const loss = await lossCheckpoint(3);+ await edit('two', 4);+ const c2 = await consolidate('auto 2', 5);++ expect(await parentsOf(c2)).not.toContain(loss);++ const gc = await gcCheckpointRefs(shadow, 'main', {+ ...DEFAULT_CHECKPOINT_RETENTION,+ maxBridgeMergeLoss: 0,+ maxAutoConsolidation: 2,+ ttlMs: 0,+ });+ expect(gc.deletedBridgeMergeLoss).toBe(1);+ expect(await reachableShas()).not.toContain(loss);+ });+});+describe('sweepLegacyShadowRefs (US-018, D35, NFR-6)', () => {let projectRoot: string;let shadow: ShadowHandle;diff --git a/packages/server/src/shadow-repo.ts b/packages/server/src/shadow-repo.tsindex d230e22b7..387a69002 100644--- a/packages/server/src/shadow-repo.ts+++ b/packages/server/src/shadow-repo.ts@@ -45,6 +45,7 @@ import {type WriterClassification,} from '@inkeep/open-knowledge-core/shadow-repo-layout';import simpleGit from 'simple-git';+import { resolveCheckpointChainAnchors } from './checkpoint-chain.ts';import { tracedMkdirSync, tracedRenameSync, tracedWriteFileSync } from './fs-traced.ts';import { listTreeLongEntries } from './git-paths.ts';import { getLogger } from './logger.ts';@@ -1378,7 +1379,7 @@ interface GcBucketPolicy {* new kind can never end up scanned-but-never-reaped, accumulating refs forever* with no cap and no TTL.*/-const GC_BUCKET_POLICY = {+export const GC_BUCKET_POLICY = {'bridge-merge-loss': {limit: (p) => p.maxBridgeMergeLoss,counter: 'deletedBridgeMergeLoss',@@ -1972,28 +1973,25 @@ async function saveVersionInner(// Deduplicate (upstream may alias a writer ref in edge cases)const uniqueParents = [...new Set(shadowParentShas)];- // Checkpoint chaining: EVERY checkpoint — even one with WIP activity — adopts the- // latest prior checkpoint as an additional parent, so history forms one- // connected chain. The timeline walk then reaches all prior entries through- // the newest checkpoint's ancestry, and kind-aware GC can reap older- // auto-consolidation refs (their commits stay reachable via newer- // checkpoints). The prior checkpoint goes LAST so WIP tips remain- // first-parents.- try {- const priorCheckpoint = (- await sg.raw(- 'for-each-ref',- '--sort=-creatordate',- '--count=1',- '--format=%(objectname)',- `refs/checkpoints/${branch}/`,- )- ).trim();- if (priorCheckpoint && !uniqueParents.includes(priorCheckpoint)) {- uniqueParents.push(priorCheckpoint);- }- } catch {- // no prior checkpoints — this is the first one, parentless is fine+ // Checkpoint chaining: EVERY checkpoint — even one with WIP activity —+ // adopts every dangling chain anchor as an additional parent, so history+ // forms one connected DAG. That is what makes kind-aware GC non-destructive:+ // reaping an older checkpoint ref leaves its commit reachable through a+ // newer checkpoint's ancestry, which is the guarantee `maxAutoConsolidation`+ // rests on. Anchors go LAST so WIP tips remain first-parents.+ const chainAnchors = await resolveCheckpointChainAnchors(sg, branch);+ for (const anchor of chainAnchors) {+ if (!uniqueParents.includes(anchor)) uniqueParents.push(anchor);+ }+ if (chainAnchors.length > 1) {+ // More than one dangling anchor means the chain had already forked and is+ // being re-joined here. Routine once, persistent means something upstream+ // keeps splitting it. The count rides a structured log, never a metric+ // label.+ log.info(+ { branch, anchors: chainAnchors.length },+ '[shadow] checkpoint chain re-anchored across multiple dangling tips',+ );}const checkpointActorEntry: OkActorEntry = {