mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-16 02:40:39 +09:00
[codex] Add issue document locking (#6009)
## Thinking Path > - Paperclip orchestrates AI-agent companies through company-scoped issues, comments, and issue documents. > - Issue documents are the durable place where plans, handoffs, and other work artifacts are revised over time. > - Some documents need to be preserved as operator-approved snapshots while agents continue working on the same issue. > - Without document locking, a later board or agent write can overwrite the document key that reviewers expected to remain stable. > - This pull request adds board-managed issue document locks and makes agent writes to locked keys create a derived document instead of mutating the locked document. > - The benefit is safer document handoffs: approved or frozen issue documents stay immutable until the board explicitly unlocks them. ## What Changed - Added `locked_at`, `locked_by_agent_id`, and `locked_by_user_id` document fields plus migration `0085_tranquil_the_executioner.sql`. - Added document lock/unlock service behavior, route endpoints, activity events, and locked-document write protections. - Made agent document writes to locked keys create a new derived key such as `plan-2` rather than overwriting the locked document. - Surfaced lock state through shared issue document types, UI API methods, document header lock controls, and activity formatting. - Added server and UI tests for lock/unlock behavior, locked document immutability, and UI action visibility. - Updated `doc/SPEC-implementation.md` with the V1 document lock contract and endpoints. ## Verification - `git rebase public-gh/master` completed cleanly after committing the branch changes. - `git diff --check` passed before commit. - `pnpm run preflight:workspace-links && pnpm exec vitest run server/src/__tests__/documents-service.test.ts server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts ui/src/components/IssueDocumentsSection.test.tsx ui/src/components/IssueContinuationHandoff.test.tsx ui/src/lib/document-revisions.test.ts` passed: 5 files, 32 tests. ## Risks - Medium risk because this changes the document persistence contract and adds a migration. - The migration uses `ADD COLUMN IF NOT EXISTS` and guarded foreign-key creation so it remains safe for users who may have already applied an earlier copy of the migration. - Locked documents intentionally reject board edits/deletes/restores until unlocked; any existing workflows that expected direct overwrite need to unlock first. - Agent writes to locked keys now create derived documents, which may create extra issue documents when agents retry locked writes. ## Model Used - OpenAI Codex coding agent based on GPT-5, with tool use and local code execution in the Paperclip worktree. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
901c088e14
commit
03ad5c5bea
18 changed files with 684 additions and 27 deletions
|
|
@ -17,6 +17,20 @@ function isUniqueViolation(error: unknown): boolean {
|
|||
return !!error && typeof error === "object" && "code" in error && (error as { code?: string }).code === "23505";
|
||||
}
|
||||
|
||||
function nextAvailableDocumentKey(sourceKey: string, existingKeys: string[]) {
|
||||
const usedKeys = new Set(existingKeys);
|
||||
for (let index = 2; index < 1000; index += 1) {
|
||||
const suffix = `-${index}`;
|
||||
const baseMaxLength = 64 - suffix.length;
|
||||
const base = sourceKey.slice(0, baseMaxLength).replace(/[-_]+$/g, "") || "document";
|
||||
const candidate = `${base}${suffix}`;
|
||||
if (!usedKeys.has(candidate) && issueDocumentKeySchema.safeParse(candidate).success) {
|
||||
return candidate;
|
||||
}
|
||||
}
|
||||
throw conflict("Unable to choose a new document key for locked document", { key: sourceKey });
|
||||
}
|
||||
|
||||
export function extractLegacyPlanBody(description: string | null | undefined) {
|
||||
if (!description) return null;
|
||||
const match = /<plan>\s*([\s\S]*?)\s*<\/plan>/i.exec(description);
|
||||
|
|
@ -40,6 +54,9 @@ function mapIssueDocumentRow(
|
|||
createdByUserId: string | null;
|
||||
updatedByAgentId: string | null;
|
||||
updatedByUserId: string | null;
|
||||
lockedAt: Date | null;
|
||||
lockedByAgentId: string | null;
|
||||
lockedByUserId: string | null;
|
||||
createdAt: Date;
|
||||
updatedAt: Date;
|
||||
},
|
||||
|
|
@ -59,6 +76,9 @@ function mapIssueDocumentRow(
|
|||
createdByUserId: row.createdByUserId,
|
||||
updatedByAgentId: row.updatedByAgentId,
|
||||
updatedByUserId: row.updatedByUserId,
|
||||
lockedAt: row.lockedAt,
|
||||
lockedByAgentId: row.lockedByAgentId,
|
||||
lockedByUserId: row.lockedByUserId,
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
};
|
||||
|
|
@ -78,6 +98,9 @@ const issueDocumentSelect = {
|
|||
createdByUserId: documents.createdByUserId,
|
||||
updatedByAgentId: documents.updatedByAgentId,
|
||||
updatedByUserId: documents.updatedByUserId,
|
||||
lockedAt: documents.lockedAt,
|
||||
lockedByAgentId: documents.lockedByAgentId,
|
||||
lockedByUserId: documents.lockedByUserId,
|
||||
createdAt: documents.createdAt,
|
||||
updatedAt: documents.updatedAt,
|
||||
};
|
||||
|
|
@ -179,6 +202,7 @@ export function documentService(db: Db) {
|
|||
createdByAgentId?: string | null;
|
||||
createdByUserId?: string | null;
|
||||
createdByRunId?: string | null;
|
||||
lockedDocumentStrategy?: "conflict" | "create_new_document";
|
||||
}) => {
|
||||
const key = normalizeDocumentKey(input.key);
|
||||
const issue = await db
|
||||
|
|
@ -188,8 +212,10 @@ export function documentService(db: Db) {
|
|||
.then((rows) => rows[0] ?? null);
|
||||
if (!issue) throw notFound("Issue not found");
|
||||
|
||||
try {
|
||||
return await db.transaction(async (tx) => {
|
||||
const maxAttempts = input.lockedDocumentStrategy === "create_new_document" ? 3 : 1;
|
||||
for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
|
||||
try {
|
||||
return await db.transaction(async (tx) => {
|
||||
const now = new Date();
|
||||
const existing = await tx
|
||||
.select({
|
||||
|
|
@ -206,6 +232,9 @@ export function documentService(db: Db) {
|
|||
createdByUserId: documents.createdByUserId,
|
||||
updatedByAgentId: documents.updatedByAgentId,
|
||||
updatedByUserId: documents.updatedByUserId,
|
||||
lockedAt: documents.lockedAt,
|
||||
lockedByAgentId: documents.lockedByAgentId,
|
||||
lockedByUserId: documents.lockedByUserId,
|
||||
createdAt: documents.createdAt,
|
||||
updatedAt: documents.updatedAt,
|
||||
})
|
||||
|
|
@ -215,6 +244,102 @@ export function documentService(db: Db) {
|
|||
.then((rows) => rows[0] ?? null);
|
||||
|
||||
if (existing) {
|
||||
if (existing.lockedAt) {
|
||||
if (input.lockedDocumentStrategy === "create_new_document") {
|
||||
const issueDocumentKeys = await tx
|
||||
.select({ key: issueDocuments.key })
|
||||
.from(issueDocuments)
|
||||
.where(eq(issueDocuments.issueId, issue.id));
|
||||
const fallbackKey = nextAvailableDocumentKey(key, issueDocumentKeys.map((row) => row.key));
|
||||
|
||||
const [document] = await tx
|
||||
.insert(documents)
|
||||
.values({
|
||||
companyId: issue.companyId,
|
||||
title: input.title ?? null,
|
||||
format: input.format,
|
||||
latestBody: input.body,
|
||||
latestRevisionId: null,
|
||||
latestRevisionNumber: 1,
|
||||
createdByAgentId: input.createdByAgentId ?? null,
|
||||
createdByUserId: input.createdByUserId ?? null,
|
||||
updatedByAgentId: input.createdByAgentId ?? null,
|
||||
updatedByUserId: input.createdByUserId ?? null,
|
||||
lockedAt: null,
|
||||
lockedByAgentId: null,
|
||||
lockedByUserId: null,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
})
|
||||
.returning();
|
||||
|
||||
const [revision] = await tx
|
||||
.insert(documentRevisions)
|
||||
.values({
|
||||
companyId: issue.companyId,
|
||||
documentId: document.id,
|
||||
revisionNumber: 1,
|
||||
title: input.title ?? null,
|
||||
format: input.format,
|
||||
body: input.body,
|
||||
changeSummary: input.changeSummary ?? null,
|
||||
createdByAgentId: input.createdByAgentId ?? null,
|
||||
createdByUserId: input.createdByUserId ?? null,
|
||||
createdByRunId: input.createdByRunId ?? null,
|
||||
createdAt: now,
|
||||
})
|
||||
.returning();
|
||||
|
||||
await tx
|
||||
.update(documents)
|
||||
.set({ latestRevisionId: revision.id })
|
||||
.where(eq(documents.id, document.id));
|
||||
|
||||
await tx.insert(issueDocuments).values({
|
||||
companyId: issue.companyId,
|
||||
issueId: issue.id,
|
||||
documentId: document.id,
|
||||
key: fallbackKey,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
});
|
||||
|
||||
return {
|
||||
created: true as const,
|
||||
redirectedFromLockedDocument: {
|
||||
id: existing.id,
|
||||
key: existing.key,
|
||||
},
|
||||
document: {
|
||||
id: document.id,
|
||||
companyId: issue.companyId,
|
||||
issueId: issue.id,
|
||||
key: fallbackKey,
|
||||
title: document.title,
|
||||
format: document.format,
|
||||
body: document.latestBody,
|
||||
latestRevisionId: revision.id,
|
||||
latestRevisionNumber: 1,
|
||||
createdByAgentId: document.createdByAgentId,
|
||||
createdByUserId: document.createdByUserId,
|
||||
updatedByAgentId: document.updatedByAgentId,
|
||||
updatedByUserId: document.updatedByUserId,
|
||||
lockedAt: null,
|
||||
lockedByAgentId: null,
|
||||
lockedByUserId: null,
|
||||
createdAt: document.createdAt,
|
||||
updatedAt: document.updatedAt,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
throw conflict("Document is locked", {
|
||||
key: existing.key,
|
||||
documentId: existing.id,
|
||||
lockedAt: existing.lockedAt,
|
||||
});
|
||||
}
|
||||
|
||||
if (!input.baseRevisionId) {
|
||||
throw conflict("Document update requires baseRevisionId", {
|
||||
currentRevisionId: existing.latestRevisionId,
|
||||
|
|
@ -274,6 +399,9 @@ export function documentService(db: Db) {
|
|||
latestRevisionNumber: nextRevisionNumber,
|
||||
updatedByAgentId: input.createdByAgentId ?? null,
|
||||
updatedByUserId: input.createdByUserId ?? null,
|
||||
lockedAt: existing.lockedAt,
|
||||
lockedByAgentId: existing.lockedByAgentId,
|
||||
lockedByUserId: existing.lockedByUserId,
|
||||
updatedAt: now,
|
||||
},
|
||||
};
|
||||
|
|
@ -296,6 +424,9 @@ export function documentService(db: Db) {
|
|||
createdByUserId: input.createdByUserId ?? null,
|
||||
updatedByAgentId: input.createdByAgentId ?? null,
|
||||
updatedByUserId: input.createdByUserId ?? null,
|
||||
lockedAt: null,
|
||||
lockedByAgentId: null,
|
||||
lockedByUserId: null,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
})
|
||||
|
|
@ -348,17 +479,26 @@ export function documentService(db: Db) {
|
|||
createdByUserId: document.createdByUserId,
|
||||
updatedByAgentId: document.updatedByAgentId,
|
||||
updatedByUserId: document.updatedByUserId,
|
||||
lockedAt: document.lockedAt,
|
||||
lockedByAgentId: document.lockedByAgentId,
|
||||
lockedByUserId: document.lockedByUserId,
|
||||
createdAt: document.createdAt,
|
||||
updatedAt: document.updatedAt,
|
||||
},
|
||||
};
|
||||
});
|
||||
} catch (error) {
|
||||
if (isUniqueViolation(error)) {
|
||||
throw conflict("Document key already exists on this issue", { key });
|
||||
});
|
||||
} catch (error) {
|
||||
if (isUniqueViolation(error)) {
|
||||
if (input.lockedDocumentStrategy === "create_new_document" && attempt < maxAttempts - 1) {
|
||||
continue;
|
||||
}
|
||||
throw conflict("Document key already exists on this issue", { key });
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
throw error;
|
||||
}
|
||||
|
||||
throw conflict("Unable to choose a new document key for locked document", { key });
|
||||
},
|
||||
|
||||
restoreIssueDocumentRevision: async (input: {
|
||||
|
|
@ -378,6 +518,13 @@ export function documentService(db: Db) {
|
|||
.then((rows) => rows[0] ?? null);
|
||||
|
||||
if (!existing) throw notFound("Document not found");
|
||||
if (existing.lockedAt) {
|
||||
throw conflict("Document is locked", {
|
||||
key: existing.key,
|
||||
documentId: existing.id,
|
||||
lockedAt: existing.lockedAt,
|
||||
});
|
||||
}
|
||||
|
||||
const revision = await tx
|
||||
.select({
|
||||
|
|
@ -455,6 +602,105 @@ export function documentService(db: Db) {
|
|||
});
|
||||
},
|
||||
|
||||
lockIssueDocument: async (input: {
|
||||
issueId: string;
|
||||
key: string;
|
||||
lockedByAgentId?: string | null;
|
||||
lockedByUserId?: string | null;
|
||||
}) => {
|
||||
const key = normalizeDocumentKey(input.key);
|
||||
return db.transaction(async (tx) => {
|
||||
const existing = await tx
|
||||
.select(issueDocumentSelect)
|
||||
.from(issueDocuments)
|
||||
.innerJoin(documents, eq(issueDocuments.documentId, documents.id))
|
||||
.where(and(eq(issueDocuments.issueId, input.issueId), eq(issueDocuments.key, key)))
|
||||
.then((rows) => rows[0] ?? null);
|
||||
|
||||
if (!existing) throw notFound("Document not found");
|
||||
if (existing.lockedAt) {
|
||||
return {
|
||||
changed: false as const,
|
||||
document: mapIssueDocumentRow(existing, true),
|
||||
};
|
||||
}
|
||||
|
||||
const now = new Date();
|
||||
await tx
|
||||
.update(documents)
|
||||
.set({
|
||||
lockedAt: now,
|
||||
lockedByAgentId: input.lockedByAgentId ?? null,
|
||||
lockedByUserId: input.lockedByUserId ?? null,
|
||||
updatedAt: now,
|
||||
})
|
||||
.where(eq(documents.id, existing.id));
|
||||
|
||||
await tx
|
||||
.update(issueDocuments)
|
||||
.set({ updatedAt: now })
|
||||
.where(eq(issueDocuments.documentId, existing.id));
|
||||
|
||||
return {
|
||||
changed: true as const,
|
||||
document: {
|
||||
...mapIssueDocumentRow(existing, true),
|
||||
lockedAt: now,
|
||||
lockedByAgentId: input.lockedByAgentId ?? null,
|
||||
lockedByUserId: input.lockedByUserId ?? null,
|
||||
updatedAt: now,
|
||||
},
|
||||
};
|
||||
});
|
||||
},
|
||||
|
||||
unlockIssueDocument: async (issueId: string, rawKey: string) => {
|
||||
const key = normalizeDocumentKey(rawKey);
|
||||
return db.transaction(async (tx) => {
|
||||
const existing = await tx
|
||||
.select(issueDocumentSelect)
|
||||
.from(issueDocuments)
|
||||
.innerJoin(documents, eq(issueDocuments.documentId, documents.id))
|
||||
.where(and(eq(issueDocuments.issueId, issueId), eq(issueDocuments.key, key)))
|
||||
.then((rows) => rows[0] ?? null);
|
||||
|
||||
if (!existing) throw notFound("Document not found");
|
||||
if (!existing.lockedAt) {
|
||||
return {
|
||||
changed: false as const,
|
||||
document: mapIssueDocumentRow(existing, true),
|
||||
};
|
||||
}
|
||||
|
||||
const now = new Date();
|
||||
await tx
|
||||
.update(documents)
|
||||
.set({
|
||||
lockedAt: null,
|
||||
lockedByAgentId: null,
|
||||
lockedByUserId: null,
|
||||
updatedAt: now,
|
||||
})
|
||||
.where(eq(documents.id, existing.id));
|
||||
|
||||
await tx
|
||||
.update(issueDocuments)
|
||||
.set({ updatedAt: now })
|
||||
.where(eq(issueDocuments.documentId, existing.id));
|
||||
|
||||
return {
|
||||
changed: true as const,
|
||||
document: {
|
||||
...mapIssueDocumentRow(existing, true),
|
||||
lockedAt: null,
|
||||
lockedByAgentId: null,
|
||||
lockedByUserId: null,
|
||||
updatedAt: now,
|
||||
},
|
||||
};
|
||||
});
|
||||
},
|
||||
|
||||
deleteIssueDocument: async (issueId: string, rawKey: string) => {
|
||||
const key = normalizeDocumentKey(rawKey);
|
||||
return db.transaction(async (tx) => {
|
||||
|
|
@ -466,6 +712,13 @@ export function documentService(db: Db) {
|
|||
.then((rows) => rows[0] ?? null);
|
||||
|
||||
if (!existing) return null;
|
||||
if (existing.lockedAt) {
|
||||
throw conflict("Document is locked", {
|
||||
key: existing.key,
|
||||
documentId: existing.id,
|
||||
lockedAt: existing.lockedAt,
|
||||
});
|
||||
}
|
||||
|
||||
await tx.delete(issueDocuments).where(eq(issueDocuments.documentId, existing.id));
|
||||
await tx.delete(documents).where(eq(documents.id, existing.id));
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue