Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Timeline attribution to users (#2456)

shagun-singh-inkeep1ab5a18a380d
diff --git a/.changeset/lovely-friends-wash.md b/.changeset/lovely-friends-wash.md
new file mode 100644
index 000000000..18ad40307
--- /dev/null
+++ b/.changeset/lovely-friends-wash.md
@@ -0,0 +1,6 @@
+---
+"@inkeep/open-knowledge-server": patch
+---
+
+The timeline now reads the incoming commits and attributes each changed document to the author of the commit that last touched it, so pulled changes show the
+contributor's name rather than a generic disk write.
diff --git a/packages/core/src/shadow-repo-layout.test.ts b/packages/core/src/shadow-repo-layout.test.ts
index 5f0c9e49a..82e56464f 100644
--- a/packages/core/src/shadow-repo-layout.test.ts
+++ b/packages/core/src/shadow-repo-layout.test.ts
@@ -18,6 +18,7 @@ import {
GitDirAccessError,
getShadowRepoPath,
getWipRefPattern,
+ gitAuthorWriterId,
MalformedGitPointerError,
type OkActorEntry,
parseCheckpoint,
@@ -207,6 +208,22 @@ describe('parseWriterId (D34 taxonomy)', () => {
expect(p.isAgent).toBe(null);
});
+ test('"git-author-<hash>" → classified-git-author, isAgent null', () => {
+ const p = parseWriterId('git-author-1a2b3c4d');
+ expect(p.classification).toBe('classified-git-author');
+ expect(p.isAgent).toBe(null);
+ });
+
+ test('gitAuthorWriterId is stable per email and case/space-insensitive', () => {
+ const a = gitAuthorWriterId('[email protected]');
+ const b = gitAuthorWriterId(' [email protected] ');
+ expect(a).toBe(b);
+ expect(a.startsWith('git-author-')).toBe(true);
+ expect(parseWriterId(a).classification).toBe('classified-git-author');
+ // Distinct authors get distinct refs.
+ expect(gitAuthorWriterId('[email protected]')).not.toBe(a);
+ });
+
// Legacy ids → unknown (eligible for GC by the allowlist sweep)
test('legacy "human-<id>" → unknown (D34: human- prefix dropped)', () => {
const p = parseWriterId('human-tim');
diff --git a/packages/core/src/shadow-repo-layout.ts b/packages/core/src/shadow-repo-layout.ts
index 7d13233e4..095a8f65f 100644
--- a/packages/core/src/shadow-repo-layout.ts
+++ b/packages/core/src/shadow-repo-layout.ts
@@ -39,6 +39,7 @@
import { existsSync, readFileSync, statSync } from 'node:fs';
import { homedir } from 'node:os';
import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fnv1aDigest } from './bridge/hash-util.ts';
/**
* Writer-ID taxonomy (precedent #25). Classified system writers are non-attributable
@@ -49,19 +50,38 @@ import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
* Full writer-ID table:
* agent-<connectionId> → 'agent' (MCP session)
* principal-<UUID> → 'principal' (browser tab)
+ * git-author-<hash> → 'classified-git-author' (upstream commit author)
* file-system → 'classified-file-system' (disk reconcile)
- * git-upstream → 'classified-git-upstream' (HEAD-move import)
+ * git-upstream → 'classified-git-upstream' (HEAD-move import boundary)
* openknowledge-service → 'classified-openknowledge-service' (park / service)
* server, human-*, upstream → 'unknown' (legacy, swept on GC)
+ *
+ * `git-author-<hash>` gives each distinct upstream commit author their own WIP
+ * ref so the per-doc Timeline query (which diffs each ref's chain) attributes a
+ * pulled change to the right author. The `<hash>` is `fnv1aDigest(email)` — one
+ * ref per author, not per pull. Display name / real email travel on the commit's
+ * `ok-actor` line, not in the id.
*/
export type WriterClassification =
| 'agent'
| 'principal'
+ | 'classified-git-author'
| 'classified-file-system'
| 'classified-git-upstream'
| 'classified-openknowledge-service'
| 'unknown';
+/** Prefix for per-author upstream-import writer ids: `git-author-<fnv1a(email)>`. */
+export const GIT_AUTHOR_WRITER_PREFIX = 'git-author-';
+
+/**
+ * Stable writer id for an upstream commit author, keyed by email so the same
+ * person reuses one ref across pulls. Non-cryptographic digest — identity only.
+ */
+export function gitAuthorWriterId(email: string): string {
+ return `${GIT_AUTHOR_WRITER_PREFIX}${fnv1aDigest(email.trim().toLowerCase())}`;
+}
+
export interface ParsedWriter {
/** The full writer id as stored in the ref (e.g., "agent-<uuid>"). */
id: string;
@@ -83,13 +103,13 @@ export interface ParsedWriter {
* Single source of truth for the layout; any ref-parsing code in the repo
* should flow through `parseWriterId`.
*
- * Recognized ids — `agent-<uuid>`, `principal-<uuid>`,
+ * Recognized ids — `agent-<uuid>`, `principal-<uuid>`, `git-author-<hash>`,
* `file-system`, `git-upstream`, `openknowledge-service`.
* Legacy ids (`human-*`, `upstream`, `server`) do NOT match → 'unknown',
* so they are eligible for GC by the allowlist sweep.
*/
const WRITER_ID_RE =
- /^(agent-[^/]+|principal-[^/]+|file-system|git-upstream|openknowledge-service)$/;
+ /^(agent-[^/]+|principal-[^/]+|git-author-[^/]+|file-system|git-upstream|openknowledge-service)$/;
/**
* Classification of `<projectRoot>/.git`. Centralizes the single
@@ -1092,6 +1112,8 @@ export function parseWriterId(id: string): ParsedWriter {
}
if (id.startsWith('agent-')) return { id, classification: 'agent', isAgent: true };
if (id.startsWith('principal-')) return { id, classification: 'principal', isAgent: false };
+ if (id.startsWith(GIT_AUTHOR_WRITER_PREFIX))
+ return { id, classification: 'classified-git-author', isAgent: null };
if (id === 'file-system') return { id, classification: 'classified-file-system', isAgent: null };
if (id === 'git-upstream')
return { id, classification: 'classified-git-upstream', isAgent: null };
diff --git a/packages/server/src/contributor-tracker.ts b/packages/server/src/contributor-tracker.ts
index 718281416..8fd2aee94 100644
--- a/packages/server/src/contributor-tracker.ts
+++ b/packages/server/src/contributor-tracker.ts
@@ -138,6 +138,22 @@ export function recordContributor(
}
}
+/**
+ * Remove a set of docs from every pending writer entry, dropping any entry left
+ * with no docs. Used by the upstream-import path to strip a doc's provisional
+ * `file-system` attribution before re-recording it under the real commit author
+ * — without this, a doc reconciled by a sibling watcher batch would produce both
+ * a "File System" and an authored row for the same import.
+ */
+export function dropPendingDocs(docNames: Iterable<string>): void {
+ const names = docNames instanceof Set ? docNames : new Set(docNames);
+ if (names.size === 0) return;
+ for (const [writerId, entry] of pendingContributors) {
+ for (const name of names) entry.docs.delete(name);
+ if (entry.docs.size === 0) pendingContributors.delete(writerId);
+ }
+}
+
/**
* Atomically swap the live accumulator with a fresh empty map.
* Returns the snapshot of in-flight contributors at the moment of the swap.
diff --git a/packages/server/src/external-change.ts b/packages/server/src/external-change.ts
index 9f8ec236b..eca6a32ed 100644
--- a/packages/server/src/external-change.ts
+++ b/packages/server/src/external-change.ts
@@ -137,11 +137,24 @@ export function applyExternalChange(
const document = hocuspocus.documents.get(docName);
if (!document) return;
+ // Byte-identical reconcile guard. When Y.Text already holds exactly the disk
+ // bytes there is nothing to ATTRIBUTE, so a trailing/duplicate file-watcher
+ // event (e.g. one arriving after an upstream import already applied the
+ // content) must not manufacture a spurious "File System" Timeline row — the
+ // `recordContributor` call below is gated on this flag.
+ //
+ // The apply itself must still run, though: embed resolution depends on branch
+ // context (basenameIndex), so a cross-branch reset re-applies byte-identical
+ // markdown whose `resolveEmbed` output changed (`![[photo.png]]` resolves to a
+ // new asset path on the switched-to branch).
+ const currentSource = document.getText('source').toString();
+ const bytesUnchanged = currentSource === content;
+
// Capture prior FM region from Y.Text so the edit_surface counter only
// fires when disk content actually changed FM (body-only edits shouldn't
// count). The YAML region of `Y.Text('source')` IS the FM source of
// truth — read it before applyDiskContentToDoc applies the disk content.
- const priorFm = stripFrontmatter(document.getText('source').toString()).frontmatter;
+ const priorFm = stripFrontmatter(currentSource).frontmatter;
const { frontmatter: nextFm } = stripFrontmatter(content);
// Caller wraps for atomicity + paired-write FILE_WATCHER_ORIGIN identity
@@ -178,14 +191,23 @@ export function applyExternalChange(
// Attribute this disk-originated write to the file-system classified writer.
// FILE_WATCHER_ORIGIN has skipStoreHooks:true so persistence.ts:onStoreDocument
// will not auto-record this origin. The explicit call here ensures the next L2
- // drain produces a commit on refs/wip/<branch>/file-system.
- recordContributor(
- docName,
- FILE_SYSTEM_WRITER.id,
- FILE_SYSTEM_WRITER.name,
- FILE_SYSTEM_WRITER.id,
- formatReconcileSubject(docName),
- );
+ // drain produces a commit on refs/wip/<branch>/file-system. When a HEAD move
+ // brought the change in, the server-factory HEAD-move drain re-attributes
+ // these docs to the upstream commit author (see resolveUpstreamChanges).
+ //
+ // Skip when the source bytes were unchanged: a byte-identical reconcile has
+ // nothing to attribute (the apply above still re-resolved embeds), and
+ // recording here would manufacture a spurious "File System" row for a
+ // trailing/duplicate event or a cross-branch reset.
+ if (!bytesUnchanged) {
+ recordContributor(
+ docName,
+ FILE_SYSTEM_WRITER.id,
+ FILE_SYSTEM_WRITER.name,
+ FILE_SYSTEM_WRITER.id,
+ formatReconcileSubject(docName),
+ );
+ }
// Set the reconciled base so persistence does not re-serialize and re-write
// the same content on next flush.
diff --git a/packages/server/src/head-watcher.ts b/packages/server/src/head-watcher.ts
index 31a983c4d..e79a76075 100644
--- a/packages/server/src/head-watcher.ts
+++ b/packages/server/src/head-watcher.ts
@@ -282,7 +282,14 @@ export async function startHeadWatcher(
async function handleGitEvent(trigger: string): Promise<void> {
if (!inBatch) {
inBatch = true;
- oldHead = readHeadSha(gitDir);
+ // Do NOT re-read HEAD here. `oldHead` already holds the last-settled HEAD
+ // (seeded at watcher start, rolled over to `newHead` at each batch end).
+ // A fast `git merge`/`git pull` can advance the branch ref BEFORE the
+ // watcher delivers its first `.git` event, so re-reading now would capture
+ // the post-move SHA and report `headMoved: false` for a genuine move —
+ // silently defeating upstream-import detection + author attribution. Only
+ // seed when we have no baseline yet (first event in an empty repo).
+ if (oldHead === null) oldHead = readHeadSha(gitDir);
const beginPromise = (async () => {
try {
await onBatchBegin({ trigger });
diff --git a/packages/server/src/resolve-upstream-author.test.ts b/packages/server/src/resolve-upstream-author.test.ts
new file mode 100644
index 000000000..692a089a8
--- /dev/null
+++ b/packages/server/src/resolve-upstream-author.test.ts
@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import simpleGit, { type SimpleGit } from 'simple-git';
+import { resolveUpstreamChanges } from './server-factory.ts';
+
+/**
+ * Unit coverage for the Timeline upstream-author recovery helper. A git pull
+ * moves HEAD over an `oldHead..newHead` range; the helper maps each changed
+ * `.md`/`.mdx` doc to the newest non-merge commit author that touched it, so the
+ * reconcile can be attributed to a real author instead of the "File System"
+ * writer.
+ */
+describe('resolveUpstreamChanges', () => {
+ let dir: string;
+ let git: SimpleGit;
+
+ async function commitAs(name: string, email: string, file: string, body: string) {
+ writeFileSync(join(dir, file), body);
+ await git.add(file);
+ await git
+ .env({
+ GIT_AUTHOR_NAME: name,
+ GIT_AUTHOR_EMAIL: email,
+ GIT_COMMITTER_NAME: name,
+ GIT_COMMITTER_EMAIL: email,
+ })
+ .commit(`edit ${file}`);
+ return (await git.revparse('HEAD')).trim();
+ }
+
+ beforeEach(async () => {
+ dir = mkdtempSync(resolve(tmpdir(), 'ok-upstream-changes-'));
+ git = simpleGit(dir);
+ await git.init(['-b', 'main']);
+ await git.addConfig('user.name', 'Seed');
+ await git.addConfig('user.email', '[email protected]');
+ });
+
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ test('maps a single incoming commit to its author', async () => {
+ const oldHead = await commitAs('Seed', '[email protected]', 'bugs.md', 'v0');
+ const newHead = await commitAs('Ana Dev', '[email protected]', 'bugs.md', 'v1');
+
+ const changes = resolveUpstreamChanges(dir, dir, oldHead, newHead);
+ expect(changes.get('bugs')).toEqual({ name: 'Ana Dev', email: '[email protected]' });
+ });
+
+ test('maps a non-ASCII (Unicode) filename to its author', async () => {
+ // git quotes non-ASCII paths as "caf\303\251.md" under the default
+ // core.quotePath=true; resolveUpstreamChanges must disable that so the
+ // path maps to a real docName instead of falling back to file-system.
+ const oldHead = await commitAs('Seed', '[email protected]', 'café.md', 'v0');
+ const newHead = await commitAs('Ana Dev', '[email protected]', 'café.md', 'v1');
+
+ const changes = resolveUpstreamChanges(dir, dir, oldHead, newHead);
+ expect(changes.get('café')).toEqual({ name: 'Ana Dev', email: '[email protected]' });
+ });
+
+ test('maps each doc to the newest author that touched it', async () => {
+ const oldHead = await commitAs('Seed', '[email protected]', 'bugs.md', 'v0');
+ await commitAs('Ana Dev', '[email protected]', 'bugs.md', 'v1');
+ const newHead = await commitAs('Ben Dev', '[email protected]', 'notes.md', 'n1');
+
+ const changes = resolveUpstreamChanges(dir, dir, oldHead, newHead);
+ expect(changes.get('bugs')).toEqual({ name: 'Ana Dev', email: '[email protected]' });
+ expect(changes.get('notes')).toEqual({ name: 'Ben Dev', email: '[email protected]' });
+ });
+
+ test('skips the merge commit and attributes to the content author', async () => {
+ const base = await commitAs('Seed', '[email protected]', 'bugs.md', 'v0');
+ const startBranch = (await git.revparse(['--abbrev-ref', 'HEAD'])).trim();
+ await git.checkoutLocalBranch('feature');
+ await commitAs('Ana Dev', '[email protected]', 'feature.md', 'f1');
+ await git.checkout(startBranch);
+ await git
+ .env({
+ GIT_AUTHOR_NAME: 'Merger',
+ GIT_AUTHOR_EMAIL: '[email protected]',
+ GIT_COMMITTER_NAME: 'Merger',
+ GIT_COMMITTER_EMAIL: '[email protected]',
+ })
+ .merge(['--no-ff', 'feature']);
+ const newHead = (await git.revparse('HEAD')).trim();
+
+ const changes = resolveUpstreamChanges(dir, dir, base, newHead);
+ expect(changes.get('feature')).toEqual({ name: 'Ana Dev', email: '[email protected]' });
+ });
+
+ test('ignores non-markdown files', async () => {
+ const oldHead = await commitAs('Seed', '[email protected]', 'bugs.md', 'v0');
+ const newHead = await commitAs('Ana Dev', '[email protected]', 'data.json', '{}');
+
+ const changes = resolveUpstreamChanges(dir, dir, oldHead, newHead);
+ expect(changes.has('data')).toBe(false);
+ expect(changes.size).toBe(0);
+ });
+
+ test('returns an empty map when oldHead is absent', async () => {
+ const newHead = await commitAs('Ana Dev', '[email protected]', 'bugs.md', 'v1');
+ expect(resolveUpstreamChanges(dir, dir, null, newHead).size).toBe(0);
+ });
+});
diff --git a/packages/server/src/server-factory.ts b/packages/server/src/server-factory.ts
index bf5c835fe..da9984b23 100644
--- a/packages/server/src/server-factory.ts
+++ b/packages/server/src/server-factory.ts
@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { type SpawnSyncReturns, spawnSync } from 'node:child_process';
import { randomUUID } from 'node:crypto';
import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
import { basename, dirname, join, relative, resolve } from 'node:path';
@@ -25,7 +25,12 @@ import {
resolveConfigPath,
writeConfigPatch,
} from '@inkeep/open-knowledge-core/server';
-import { resolveGitDir, resolveShadowDir } from '@inkeep/open-knowledge-core/shadow-repo-layout';
+import {
+ formatReconcileSubject,
+ gitAuthorWriterId,
+ resolveGitDir,
+ resolveShadowDir,
+} from '@inkeep/open-knowledge-core/shadow-repo-layout';
import simpleGit from 'simple-git';
import { AgentFocusBroadcaster } from './agent-focus.ts';
import { AgentPresenceBroadcaster } from './agent-presence.ts';
@@ -55,6 +60,7 @@ import { isDocInConflict } from './conflict-errors.ts';
import { createConflictLifecycleSeedExtension } from './conflict-lifecycle-seed.ts';
import { resolveProjectTemplates } from './content/templates-resolver.ts';
import { type ContentFilter, createContentFilter } from './content-filter.ts';
+import { dropPendingDocs, recordContributor } from './contributor-tracker.ts';
import { getDocExtension, stripDocExtension } from './doc-extensions.ts';
import { runDocLineageGuard } from './doc-lineage-guard.ts';
import {
@@ -78,6 +84,7 @@ import {
assertNeverDiskEvent,
contentHash,
type DiskEvent,
+ pathToDocName,
reconcileFileIndexAfterFilterRebuild,
startWatcher,
type WatcherHandle,
@@ -122,6 +129,7 @@ import {
getActiveBranch,
getReconciledBase,
isBatchInProgress,
+ isWithinContentDir,
type PersistenceOptions,
safeContentPath,
setBatchInProgress,
@@ -389,6 +397,110 @@ export function buildSyncCredentialArgs(localOpCliArgs?: string[]): string[] {
return ['-c', `credential.helper=!${cliPrefix} auth git-credential`];
}
+export interface UpstreamAuthor {
+ name: string;
+ email: string;
+}
+
+/**
+ * Recover, per changed markdown doc, the author to attribute a HEAD-move import
+ * to. Runs `git log <oldHead>..<newHead>` in the project repo and maps each
+ * changed `.md`/`.mdx` doc to the author of the newest in-range commit that
+ * touched it — the author whose bytes are now on disk. `git log` lists commits
+ * newest-first, so the first occurrence of a doc in the output is its newest
+ * commit; the first-occurrence-wins guard below therefore selects that author.
+ *
+ * Deterministic and complete: git authoritatively lists what the import
+ * changed, so attribution does not depend on which watcher batch happened to
+ * observe the file event. Merge commits are skipped (`--no-merges`) because
+ * their author is whoever ran the pull, not the content author. Returns an
+ * empty map on any ambiguity (missing `oldHead`, git failure) so the caller
+ * falls back to the `file-system` writer.
+ */
+export function resolveUpstreamChanges(
+ projectDir: string,
+ contentDir: string,
+ oldHead: string | null,
+ newHead: string,
+): Map<string, UpstreamAuthor> {
+ const changes = new Map<string, UpstreamAuthor>();
+ if (!oldHead) return changes;
+ // `C\0name\0email` header per commit, then one changed path per line. NUL
+ // delimiters keep names/emails with spaces unambiguous.
+ let result: SpawnSyncReturns<string>;
+ try {
+ result = spawnSync(
+ 'git',
+ [
+ // `core.quotePath=false` emits non-ASCII pathnames as raw UTF-8 instead
+ // of git's default octal-escaped `"caf\303\251.md"` quoting — otherwise
+ // Unicode-named docs never match a real docName and silently fall back
+ // to file-system attribution.
+ '-c',
+ 'core.quotePath=false',
+ 'log',
+ `${oldHead}..${newHead}`,
+ '--no-merges',
+ '--name-only',
+ '--format=C%x00%an%x00%ae',
+ ],
+ { cwd: projectDir, encoding: 'utf-8', timeout: 5000 },
+ );
+ } catch (err) {
+ // spawnSync normally surfaces ENOENT/timeout via result.error rather than
+ // throwing, but guard the throw path too. On failure the caller sees an
+ // empty map and leaves the imported docs under `file-system` — log so that
+ // silent attribution degradation is diagnosable.
+ getLogger('upstream-attribution').warn(
+ { err, oldHead, newHead },
+ 'git log spawn threw; upstream docs keep file-system attribution',
+ );
+ return changes;
+ }
+ // Distinguish a real failure (git missing, non-zero exit, or the 5s timeout —
+ // status is non-zero/null or result.error is set) from the legitimate empty
+ // result (git succeeded, no markdown changed). Only the former is logged.
+ if (result.error || result.status !== 0 || typeof result.stdout !== 'string') {
+ getLogger('upstream-attribution').warn(
+ {
+ err: result.error,
+ status: result.status,
+ signal: result.signal,
+ // git's actionable message (`fatal: bad object …`) is on stderr; bound
+ // it so the warning is self-diagnosable without reproducing the command.
+ stderr: typeof result.stderr === 'string' ? result.stderr.slice(0, 500) : undefined,
+ oldHead,
+ newHead,
+ },
+ 'git log failed; upstream docs keep file-system attribution',
+ );
+ return changes;
+ }
+
+ let current: UpstreamAuthor | null = null;
+ for (const rawLine of result.stdout.split('\n')) {
+ const line = rawLine.trim();
+ if (line === '') continue;
+ if (line.startsWith('C\0')) {
+ const [, name, email] = line.split('\0');
+ current = name && email ? { name, email } : null;
+ continue;
+ }
+ if (!current) continue;
+ if (!line.endsWith('.md') && !line.endsWith('.mdx')) continue;
+ const abs = resolve(projectDir, line);
+ if (!isWithinContentDir(abs, contentDir)) continue;
+ const docName = pathToDocName(abs, contentDir);
+ // First occurrence wins. `git log` is newest-first, so the doc's first
+ // appearance is its newest in-range commit — keep it, discard older commits'
+ // claims. Reversing this regresses to oldest-author attribution.
+ if (changes.has(docName)) continue;
+ if (!existsSync(abs)) continue;
+ changes.set(docName, current);
+ }
+ return changes;
+}
+
export function createServer(options: ServerOptions): ServerInstance {
const {
contentDir,
@@ -3231,8 +3343,48 @@ export function createServer(options: ServerOptions): ServerInstance {
if (info.batchKind === 'within-branch') {
setBatchInProgress(false);
- // Pull, merge, rebase on same branch — reconcile buffered events
+ // Pull, merge, rebase on same branch — reconcile buffered events.
+ // The buffered reconciles tag their docs as `file-system`.
await drainEventBuffer();
+
+ // When HEAD actually moved, these bytes came from upstream commits.
+ // Ask git which docs the import changed and who authored them
+ // (deterministic — independent of which watcher batch observed each
+ // file event), strip the provisional `file-system` attribution, and
+ // re-record each under the real commit author. Then flush now: the
+ // reconcile records under FILE_WATCHER_ORIGIN (skipStoreHooks) so no
+ // L2 debounce is scheduled, and the commits must land before the
+ // commitUpstreamImport boundary below.
+ if (info.headMoved && info.newHead) {
+ const changes = resolveUpstreamChanges(
+ projectDir,
+ resolve(contentDir),
+ info.oldHead,
+ info.newHead,
+ );
+ if (changes.size > 0) {
+ dropPendingDocs(changes.keys());
+ // Record each changed doc under a per-author writer id
+ // (`git-author-<hash(email)>`), NOT the shared git-upstream id.
+ // The Timeline queries each writer ref's chain independently and
+ // diffs it; multiple authors on one ref produce identical trees,
+ // so the per-path diff collapses them onto the oldest commit and
+ // mis-attributes docs. A distinct ref per author makes each
+ // commit diff against its own base, so every doc surfaces under
+ // its real author. The per-writer persistence fan-out turns this
+ // single flush into one commit per author ref.
+ for (const [docName, author] of changes) {
+ recordContributor(
+ docName,
+ gitAuthorWriterId(author.email),
+ author.name,
+ author.email,
+ formatReconcileSubject(docName),
+ );
+ }
+ await persistence.flushContributors();
+ }
+ }
await persistence.flushDeferredStores('within-branch');
// External git ops (`git merge --abort`, `git checkout --ours
// && git add && git commit` mid-conflict, etc.) leave the
diff --git a/packages/server/src/shadow-branch-gc.ts b/packages/server/src/shadow-branch-gc.ts
index 1aa009cde..84a6a0f99 100644
--- a/packages/server/src/shadow-branch-gc.ts
+++ b/packages/server/src/shadow-branch-gc.ts
@@ -310,6 +310,7 @@ export async function gcShadowBranches(
if (
c.classification === 'classified-file-system' ||
c.classification === 'classified-git-upstream' ||
+ c.classification === 'classified-git-author' ||
c.classification === 'classified-openknowledge-service'
) {
continue;
diff --git a/packages/server/src/upstream-attribution.integration.test.ts b/packages/server/src/upstream-attribution.integration.test.ts
new file mode 100644
index 000000000..cb09502fd
--- /dev/null
+++ b/packages/server/src/upstream-attribution.integration.test.ts
@@ -0,0 +1,145 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { resolve } from 'node:path';
+import simpleGit, { type SimpleGit } from 'simple-git';
+import { createServer, type ServerInstance } from './server-factory.ts';
+import { initShadowRepo, type ShadowHandle, shadowGit } from './shadow-repo.ts';
+import { getDocumentHistory } from './timeline-query.ts';
+
+/**
+ * End-to-end: a git merge (stand-in for `git pull`) that moves HEAD while a doc
+ * is open should attribute the reconcile to the incoming commit's author, not
+ * "File System". Drives the real createServer + head-watcher + file-watcher path.
+ */
+let dir: string;
+let git: SimpleGit;
+let shadow: ShadowHandle;
+let server: ServerInstance | null = null;
+
+async function commitAs(name: string, email: string, file: string, body: string) {
+ writeFileSync(resolve(dir, file), body);
+ await git.add(file);
+ await git
+ .env({
+ GIT_AUTHOR_NAME: name,
+ GIT_AUTHOR_EMAIL: email,
+ GIT_COMMITTER_NAME: name,
+ GIT_COMMITTER_EMAIL: email,
+ })
+ .commit(`edit ${file}`);
+}
+
+beforeEach(async () => {
+ dir = mkdtempSync(resolve(tmpdir(), 'ok-upstream-attr-int-'));
+ git = simpleGit(dir);
+ await git.init(['-b', 'main']);
+ await git.addConfig('user.name', 'Seed');
+ await git.addConfig('user.email', '[email protected]');
+ await commitAs('Seed', '[email protected]', 'bugs.md', '# Bugs\n\ninitial\n');
+ await git.checkoutLocalBranch('incoming');
+ await commitAs(
+ 'Ana Dev',
+ 'bugs.md',
+ '# Bugs\n\ninitial\n\nAna added this line\n',
+ );
+ await git.checkout('main');
+ shadow = await initShadowRepo(dir);
+});
+
+afterEach(async () => {
+ await server?.destroy().catch(() => {});
+ server = null;
+ rmSync(dir, { recursive: true, force: true });
+});
+
+test('merge while doc is open attributes the reconcile to the incoming author', async () => {
+ server = createServer({
+ contentDir: dir,
+ projectDir: dir,
+ contentRoot: '.',
+ quiet: true,
+ debounce: 200,
+ shadowRepo: shadow,
+ });
+ await server.ready;
+
+ // Load the doc so it is a live Y.Doc when the merge lands.
+ const conn = await server.hocuspocus.openDirectConnection('bugs');
+
+ // Merge the incoming branch — moves HEAD + rewrites bugs.md on disk.
+ await git.merge(['--no-ff', '-m', 'merge incoming', 'incoming']);
+
+ // Poll the shadow log for a reconcile commit whose git author is the incoming
+ // commit's author (display name). The writer-bucket email is synthetic
+ // (git-upstream@…) by design — the real email rides along as the ok-actor
+ // color seed, asserted separately below.
+ const sg = shadowGit(shadow);
+ let reconcileLine = '';
+ for (let i = 0; i < 40; i++) {
+ const log = (await sg.raw('log', '--all', '--format=%an | %s')).trim();
+ reconcileLine = log.split('\n').find((l) => l.startsWith('Ana Dev | reconcile:')) ?? '';
+ if (reconcileLine) break;
+ await new Promise((r) => setTimeout(r, 250));
+ }
+
+ // The recovered git identity (real email) is carried on the ok-actor body line
+ // as the color seed, not as the git-author email.
+ const body = reconcileLine
+ ? await sg.raw('log', '--all', '-1', '--format=%b', '--grep=reconcile: bugs')
+ : '';
+
+ await conn.disconnect?.();
+
+ expect(reconcileLine).toMatch(/^Ana Dev \| reconcile: bugs$/);
+ expect(body).toContain('[email protected]');
+}, 20_000);
+
+test('a multi-author pull attributes each doc to its own author', async () => {
+ // Add a second incoming commit by a different author touching a different doc,
+ // so the merge range spans two authors (Ana → bugs, Ben → notes).
+ await git.checkout('incoming');
+ await commitAs('Ben Dev', '[email protected]', 'notes.md', '# Notes\n\nBen wrote this\n');
+ await git.checkout('main');
+
+ server = createServer({
+ contentDir: dir,
+ projectDir: dir,
+ contentRoot: '.',
+ quiet: true,
+ debounce: 200,
+ shadowRepo: shadow,
+ });
+ await server.ready;
+
+ await git.merge(['--no-ff', '-m', 'merge incoming', 'incoming']);
+
+ const sg = shadowGit(shadow);
+ let log = '';
+ for (let i = 0; i < 40; i++) {
+ log = (await sg.raw('log', '--all', '--format=%an | %s')).trim();
+ if (/Ana Dev \| reconcile:/.test(log) && /Ben Dev \| reconcile:/.test(log)) break;
+ await new Promise((r) => setTimeout(r, 250));
+ }
+
+ const lines = log.split('\n');
+ // Each author gets their own reconcile commit — no collapse onto one name.
+ expect(lines).toContain('Ana Dev | reconcile: bugs');
+ expect(lines).toContain('Ben Dev | reconcile: notes');
+
+ // The real fix: the per-doc Timeline query must attribute each doc to its own
+ // author. Per-author writer refs make each commit diff against its own base,
+ // so `bugs` surfaces Ana and `notes` surfaces Ben — not the collapse where a
+ // shared ref's identical trees pinned both docs onto the oldest commit.
+ const authorsFor = async (docName: string) => {
+ const hist = await getDocumentHistory(shadow, { docName, limit: 20 }, '.');
+ return hist.entries.flatMap((e) => e.contributors.map((c) => c.name));
+ };
+ const bugsAuthors = await authorsFor('bugs');
+ const notesAuthors = await authorsFor('notes');
+ expect(bugsAuthors).toContain('Ana Dev');
+ expect(bugsAuthors).not.toContain('Ben Dev');
+ expect(notesAuthors).toContain('Ben Dev');
+ expect(notesAuthors).not.toContain('Ana Dev');
+}, 20_000);