mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-14 17:40:37 +02:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agent runs need durable records so Paperclip can explain results and final status changes. > - The current heartbeat tables support direct adapters, but they do not model native runner evidence. > - The runner transport and server coordinator must share a strict finalization contract before they write production data. > - This pull request adds that contract and its additive database boundary. > - It does not select the Paperclip Runner or change any existing adapter execution path. > - The benefit is a reviewable persistence layer that preserves all current behavior and supports later guarded integration. ## Linked Issues or Issue Description Refs #11962 Refs #12129 ## What Changed - Add native run result, finalization, completion, assessment, status decision, and status effect tables. - Add inert native metadata to heartbeat runs and events. Keep `legacy` as the default runtime mode. - Bind each evidence relationship to one company, issue, run, contract, result, assessment, and decision with composite constraints. - Add a strict `paperclip.native_finalization.v1` shared type and validator. - Preserve database functions, triggers, and the unique indexes required by foreign keys in JavaScript backups. - Add migration, backup, mixed-owner denial, validator, and direct-adapter compatibility tests. - Document the new records and their ownership rules. ## Verification - Run `pnpm -r typecheck`. - Run `pnpm build`. - Run `pnpm db:generate`. The schema output and migration safety checks remain current. - Run `PAPERCLIP_PSQL_PATH=/Applications/Postgres.app/Contents/Versions/latest/bin/psql pnpm exec vitest run packages/shared/src/validators/native-finalization.test.ts packages/db/src/client.test.ts packages/db/src/backup-lib.test.ts server/src/__tests__/heartbeat-workspace-busy.test.ts server/src/__tests__/heartbeat-comment-wake-batching.test.ts`. All 52 tests pass. - The full local `pnpm test:run` run completed 4,688 tests. It found 30 existing macOS test-environment failures. A serial rerun with the canonical `/private/tmp` path reduced those failures to six existing listener-diagnostics and skill-browser cases. None of those suites use files in this change. - The full Linux GitHub Actions matrix passes. This includes all general-server, serialized-server, workspace, browser, build, typecheck, canary, and aggregate verification jobs. - Greptile passes at 5/5. Contributor trust, Superagent, Socket, and Snyk pass with no finding from this change. - Storybook visual regression skips by path because this pull request has no UI or Storybook change. - Confirm that the diff contains 25 files. Confirm that it contains no workflow or `pnpm-lock.yaml` changes. ## Risks - The migration adds tables, columns, indexes, a function, a trigger, and ownership constraints. It does not remove or rename existing data. - Composite foreign keys reject mixed-company, mixed-issue, and mixed-run evidence even when each ID exists. - The status-version trigger runs only when an issue status changes. Backup tests confirm that restore retains this trigger and its dependencies. - Native source identifiers are unique when present. Legacy event rows remain unchanged. - This change does not add a unique run sequence constraint. The later native writer must allocate its sequence atomically before that invariant can be safe. - Existing adapters keep their current execution and finalization paths. New heartbeat runs default to `legacy` mode. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex with GPT-5. The exact deployment ID and context-window size are not exposed. The model used agentic reasoning, repository tools, code execution, and test execution. ## 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 searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
87 lines
2.8 KiB
TypeScript
87 lines
2.8 KiB
TypeScript
import {
|
|
foreignKey,
|
|
pgTable,
|
|
uuid,
|
|
text,
|
|
timestamp,
|
|
bigint,
|
|
jsonb,
|
|
unique,
|
|
uniqueIndex,
|
|
} from "drizzle-orm/pg-core";
|
|
import { companies } from "./companies.js";
|
|
import { issues } from "./issues.js";
|
|
import { workAssessments } from "./work_assessments.js";
|
|
|
|
export const statusDecisions = pgTable(
|
|
"status_decisions",
|
|
{
|
|
id: uuid("id").primaryKey().defaultRandom(),
|
|
companyId: uuid("company_id").notNull().references(() => companies.id),
|
|
issueId: uuid("issue_id").notNull(),
|
|
runId: uuid("run_id").notNull(),
|
|
assessmentId: uuid("assessment_id").notNull(),
|
|
decisionVersion: bigint("decision_version", { mode: "number" }).notNull(),
|
|
policyVersion: text("policy_version").notNull(),
|
|
fromStatus: text("from_status").notNull(),
|
|
toStatus: text("to_status").notNull(),
|
|
reasonCode: text("reason_code").notNull(),
|
|
decisionJson: jsonb("decision_json").$type<Record<string, unknown>>().notNull(),
|
|
decisionDigest: text("decision_digest").notNull(),
|
|
applicationState: text("application_state").notNull().default("proposed"),
|
|
supersedesDecisionId: uuid("supersedes_decision_id"),
|
|
appliedAt: timestamp("applied_at", { withTimezone: true }),
|
|
createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
|
|
},
|
|
(table) => ({
|
|
companyIssueIdUq: unique("status_decisions_company_issue_id_uq").on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.id,
|
|
),
|
|
companyIssueRunAssessmentIdUq: unique(
|
|
"status_decisions_company_issue_run_assessment_id_uq",
|
|
).on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.runId,
|
|
table.assessmentId,
|
|
table.id,
|
|
),
|
|
issueCompanyFk: foreignKey({
|
|
columns: [table.companyId, table.issueId],
|
|
foreignColumns: [issues.companyId, issues.id],
|
|
name: "status_decisions_issue_company_fk",
|
|
}),
|
|
assessmentOwnerFk: foreignKey({
|
|
columns: [table.companyId, table.issueId, table.runId, table.assessmentId],
|
|
foreignColumns: [
|
|
workAssessments.companyId,
|
|
workAssessments.issueId,
|
|
workAssessments.runId,
|
|
workAssessments.id,
|
|
],
|
|
name: "status_decisions_assessment_owner_fk",
|
|
}),
|
|
supersedesOwnerFk: foreignKey({
|
|
columns: [table.companyId, table.issueId, table.supersedesDecisionId],
|
|
foreignColumns: [table.companyId, table.issueId, table.id],
|
|
name: "status_decisions_supersedes_owner_fk",
|
|
}),
|
|
issueVersionUq: uniqueIndex("status_decisions_company_issue_version_uq").on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.decisionVersion,
|
|
),
|
|
assessmentUq: uniqueIndex("status_decisions_company_assessment_uq").on(
|
|
table.companyId,
|
|
table.assessmentId,
|
|
),
|
|
issueDigestUq: uniqueIndex("status_decisions_company_issue_digest_uq").on(
|
|
table.companyId,
|
|
table.issueId,
|
|
table.decisionDigest,
|
|
),
|
|
}),
|
|
);
|