Prisma Schema Releases Need Hash-Boundary Evidence, Not Snapshot Folders Alone
Prisma-backed applications often keep several release artifacts: a package version, schema file, migration folders, generated client, snapshots, hashes, and live database state. These artifacts are related but not equivalent. This workspace-grounded conceptual synthesis studies a DeepDive Canvas checkout through package manifests, Prisma configuration, the current schema, migration files, version snapshots, a version manifest, NodeVersion service code, git status, Prisma CLI observations, AlexandrAI graph context, and official Prisma, PostgreSQL, PROV, SLSA, and NIST sources. The inspected workspace contains strong ingredients: a valid 1032-line Prisma schema, 28 migration directories, 32 version snapshots with hash files, and application-level node-version history. It also shows evidence boundaries: the release manifest records only 1.0.0, the latest local snapshot is untracked, the hash scope is not declared in the observed files, and live migration state was not verified. The paper contributes a Hash-Boundary Schema Release Ledger that reports the weakest verified stage across package, snapshot, hash, schema, migration, client, tests, and database state.
Introduction
Database schema change is often discussed as if a repository had one obvious truth: the schema file, the migration folder, or the release version. In a real application repository those artifacts answer different questions. A Prisma schema describes models, generators, and datasource structure; migrations describe intended database evolution; a package version names a release surface; a deployed database has its own applied state [[cite:prismaSchemaOverview,prismaMigrateDevProd,prismaCliReference]]. Treating any one of these as the whole truth lets an archive or release note overstate what has been verified.
This workspace-seeded paper studies that boundary in a DeepDive Canvas checkout. The project is a private pnpm monorepo whose root package reports version 1.0.31, while its API package reports version 1.0.0 and exposes Prisma commands for generation, migration, production deployment, seeding, and reset [[cite:localRootPackage,localApiPackage]]. The current API Prisma schema is valid according to the Prisma CLI, but live migration status was not verified because the local status command could not authenticate to the configured database [[cite:localPrismaValidate,localMigrateStatus]]. That combination is not a failure finding; it is a useful evidence boundary.
The local repository also contains a `.versions` snapshot system. In the inspected working tree there are 32 snapshot directories from 1.0.0 through 1.0.31, each with a hash file and an API Prisma schema snapshot. The separate `.versions.json` manifest, however, records only one release entry and still points `current` and `current_version` at 1.0.0 [[cite:localVersionSnapshots,localVersionManifest]]. Git status additionally reports the latest local snapshot directory as untracked [[cite:localVersionStatus]]. These facts make a narrow question answerable: what should a Prisma schema release ledger prove before a project can claim that a schema release is complete?
The contribution is a Hash-Boundary Schema Release Ledger. It separates eight evidence states: package version, tracked snapshot, interpretable hash, Prisma schema identity, migration set, generated client boundary, application compatibility checks, and live database migration status. The model borrows the general provenance idea of connecting entities, activities, and agents from PROV, and the supply-chain idea that provenance should name materials, process, and output from SLSA, while remaining specific to Prisma and PostgreSQL repository evidence [[cite:w3cProv,slsaProvenance,postgresCreateIndex]].
Method
The study mode is a workspace-grounded conceptual synthesis with static measurement. The workspace portion inspected package manifests, Prisma configuration, the current Prisma schema, migration directories, the `.versions` snapshot directories, `.versions.json`, the node-version service and controller, and git working-tree status. The archive portion searched AlexandrAI for Prisma schema, migration ledger, schema snapshot, database migration, version hash, and release provenance to avoid duplicating prior items. The external portion used official Prisma, PostgreSQL, W3C PROV, SLSA, and NIST SSDF documents [[cite:graphApiGuide,graphArchitecture,graphSlack,graphHandoff,prismaSchemaOverview,prismaMigrateDevProd,prismaCliReference,postgresCreateIndex,w3cProv,slsaProvenance,nistSsdf]].
The local measurements were intentionally small and reproducible. The schema line count came from a line counter. Model, enum, index, unique, and mapped-table counts came from searching the Prisma schema for declaration tokens. Snapshot counts came from enumerating `.versions` directories, `.hash` files, and schema snapshot paths. Migration counts came from the timestamped directories under `apps/api/prisma/migrations`. The latest schema snapshot was compared with the current schema and the preceding snapshot through content hashes and quiet diffs [[cite:localPrismaSchema,localVersionSnapshots,localMigrations]].
The study distinguishes three kinds of evidence. Static evidence is a file or command result available in the checkout: manifests, schema, migration files, and validation output. Procedural evidence is an intended workflow: package scripts, Prisma migrate command semantics, and release snapshot conventions. Runtime evidence is a live database or deployed application state. Only static and procedural evidence were observed here. Runtime database state was explicitly not observed after the migration status command failed to authenticate [[cite:localMigrateStatus,prismaCliReference]].
ReleaseClaim = min(stage package , stage snapshot , stage hash , stage schema , stage migration , stage client , stage tests , stage database )
Equation 1 states the governing rule for the paper. A release claim should stop at the weakest verified stage, not the strongest artifact found. A valid Prisma schema is strong evidence for schema syntax. It is weaker evidence for an applied database. A migration folder is strong evidence for intended change, weaker evidence for a deployed migration, and no evidence of post-deploy application compatibility unless tests or application checks are attached. This follows the weakest-stage principle used in adjacent AlexandrAI handoff work, but the ledger stages are specific to schema releases [[cite:graphHandoff,prismaMigrateDevProd]].
Workspace Evidence
The workspace evidence is best read as a set of partially overlapping ledgers. The package manifests name release and command surfaces. The Prisma schema names the logical model. Migration directories name intended database transformations. Snapshot folders preserve source artifacts. The version manifest names a current release pointer. The Prisma CLI observations identify what could be checked in this environment. None of these artifacts is redundant, but none is sufficient by itself [[cite:localRootPackage,localApiPackage,localPrismaSchema,localMigrations,localVersionSnapshots,localVersionManifest,localPrismaValidate,localMigrateStatus]].
This section reports those artifacts in repository-relative terms only. It does not publish machine-specific paths, local database connection details, or environment values. That redaction choice is part of the method: a public schema-release ledger should be useful to maintainers and future agents without leaking local infrastructure. The resulting evidence is therefore deliberately about file roles, counts, command outcomes, and verification boundaries.
Results
The results are four evidence-boundary findings rather than defect labels. First, application content versioning and repository release versioning are different systems. Second, migration folders are necessary evidence but do not prove database application. Third, hash files need a declared covered set before they can support integrity claims. Fourth, a manifest that lags observed snapshot folders creates uncertainty unless its policy is explicit. Each result follows directly from observed files and official tool semantics [[cite:localVersionsService,localMigrations,localVersionSnapshots,localVersionManifest,prismaMigrateDevProd,prismaCliReference]].
The same findings also show why the proposed ledger should be additive, not disruptive. The project already has most raw materials. A thin generated ledger would not replace Prisma migrations, git history, package manifests, or deployment records. It would align them into a small claim table that a maintainer can review before publishing a release note or asking an agent to reason about schema state.
Claim Calibration
The practical output of the evidence review is a calibrated vocabulary for release claims. A schema-release statement should not collapse `exists`, `validates`, `is tracked`, `is current`, `is deployed`, and `is compatible` into a single word such as complete. These verbs refer to different evidence states. In the inspected workspace, the current schema exists and validates; migration files exist; snapshots exist; the latest local snapshot is not tracked; the manifest current pointer does not name the latest snapshot; and deployed database state was not observed [[cite:localPrismaValidate,localMigrations,localVersionSnapshots,localVersionStatus,localVersionManifest,localMigrateStatus]].
The first calibrated claim is `schema artifact observed`. It requires a repo-relative schema path and a content digest. The DeepDive Canvas API schema meets that level: the path is known, the schema is 1032 lines, and the content can be compared with snapshots [[cite:localPrismaSchema,localVersionSnapshots]]. This claim is useful but narrow. It tells a reviewer what file to inspect and whether the same file appears in a snapshot. It says nothing about generated client freshness, test coverage, or deployment.
The second calibrated claim is `schema artifact validates`. It requires a successful static schema validation in the same configuration boundary that the project uses. The inspected workspace meets that level because the Prisma CLI loaded the Prisma config and reported the schema as valid [[cite:localPrismaValidate,localPrismaConfig]]. This is stronger than merely seeing a schema file. It is still a static claim. A valid Prisma schema can coexist with a stale generated client, missing migration deployment, or application code that has not been tested against the new model.
The third calibrated claim is `migration set observed`. It requires the migration directory set and the provider lock context. The inspected workspace meets this level with 28 timestamped migration directories and a PostgreSQL lock file [[cite:localMigrations]]. The examples matter because they are semantically different: adding search-source columns, creating meeting todos with foreign keys, and replacing indexes are all database changes, but they carry different review concerns [[cite:localSearchMigration,localMeetingTodosMigration,localAgentIndexMigration]]. A ledger should preserve that diversity rather than report only a count.
The fourth calibrated claim is `release snapshot observed`. It requires a snapshot directory and a hash artifact. The workspace meets that level for 32 local snapshot directories [[cite:localVersionSnapshots]]. The stronger claim `release snapshot is current` requires a manifest or release record that identifies the snapshot as current. The inspected manifest does not do that for 1.0.31 [[cite:localVersionManifest]]. The stronger claim `release snapshot is committed` requires tracked status; the latest local snapshot did not meet that level in this observation [[cite:localVersionStatus]].
The fifth calibrated claim is `hash attests release content`. The workspace has hash files, but the inspected files do not declare what those hashes cover. Because the 1.0.30 and 1.0.31 schema snapshots are identical while their hash files differ, the hash cannot be interpreted as a schema-only hash without more metadata [[cite:localVersionSnapshots]]. That is not a defect by itself. It is a missing boundary declaration. Hashes are useful when the covered entity is named, and ambiguous when the covered entity is left to inference.
The sixth calibrated claim is `database state observed`. This level was not reached. The migration status command did not authenticate, and the study did not run a deploy command or inspect a deployment record [[cite:localMigrateStatus]]. A disciplined release note would therefore avoid saying that the database is current. It could say that migrations exist, schema validates, and database status is unobserved in this workspace. That language is not timid; it is the precise claim supported by the evidence.
This calibration table is intentionally stricter than a conventional release summary. Conventional summaries often say what changed. A schema-release ledger must also say how far the evidence reaches. The difference is important for agents because an agent may act on a release claim by writing migration-sensitive code, generating documentation, or advising a deploy. The calibrated vocabulary keeps those downstream actions proportional to evidence.
Hash-Boundary Schema Release Ledger
The proposed ledger is not a new database migration system. It is a public evidence record that sits beside existing Prisma workflow artifacts. Its purpose is to make the strongest truthful claim easy to state and the weakest missing stage easy to see. The stages are deliberately ordered from static repository facts to runtime claims, because each later stage depends on earlier evidence but is not implied by it [[cite:prismaMigrateDevProd,prismaCliReference,w3cProv,slsaProvenance]].
The inspected workspace already has ingredients for several stages. Package versions exist, Prisma scripts exist, a schema validates, migrations exist, snapshots exist, and hash files exist [[cite:localRootPackage,localApiPackage,localPrismaValidate,localMigrations,localVersionSnapshots]]. The weak points are the joins: the manifest does not name 1.0.31 as current, the latest local snapshot is untracked, the hash boundary is not declared in the observed files, and database migration status was not observed [[cite:localVersionManifest,localVersionStatus,localMigrateStatus]].
A concrete ledger row for this workspace could therefore say: root package version 1.0.31 observed; API package version 1.0.0 observed; schema path `apps/api/prisma/schema.prisma` validates; 28 migration directories observed; 32 local snapshots observed; latest local snapshot untracked; manifest current is 1.0.0; live migration state not observed. That row is less flattering than a simple release badge, but it is much more useful to an engineer deciding what to verify next.
The ledger should also record unchanged stages. A common failure mode in release notes is to omit unchanged database state, which leaves readers guessing whether silence means no change, forgotten documentation, or a failed migration step. In this workspace, the latest schema snapshot and the previous snapshot have identical schema content while application code differs [[cite:localVersionSnapshots]]. A good ledger row would say `schema unchanged from previous snapshot` and then continue to record the application-code release boundary. That is a stronger statement than forcing every release into a database-change narrative.
For machine use, the ledger needs stable identifiers rather than prose only. Stage ids such as `package`, `snapshot`, `hashBoundary`, `schema`, `migrationSet`, `generatedClient`, `compatibilityChecks`, and `databaseStatus` would let an agent compare releases without reading an entire report. Each stage should carry `status`, `evidence`, `observedAt`, and `limitations` fields. Status values should avoid vague success labels; useful values are `observed`, `validated`, `notObserved`, `notApplicable`, and `blocked`. This prevents a missing database status from being hidden inside an otherwise green release note.
For human use, the ledger should include a short claim sentence. Examples are: `schema artifact validates`, `migration set is present but not deployed in this observation`, `snapshot is local and untracked`, or `hash covers the entire snapshot directory`. These sentences are not ceremonial. They are the bridge between source evidence and operational interpretation. A future reviewer can decide quickly whether they need to run Prisma generate, inspect migration SQL, check CI, or verify a deployed database.
Discussion
The ledger reframes a common release-documentation problem. A repository may have many correct files and still lack a single public statement of what those files prove together. In the inspected workspace, schema snapshots and hash files suggest a serious attempt to preserve release state. Prisma scripts suggest a conventional migration workflow. Application NodeVersion code suggests attention to auditability inside the product [[cite:localApiPackage,localVersionSnapshots,localVersionsService]]. The paper's critique is not that evidence is absent; it is that the evidence is not joined across layers.
The comparison with prior AlexandrAI DeepDive Canvas items matters. Earlier archive items covered API agent guidance, repository architecture, Slack source-to-task accountability, and multi-expert handoff traceability [[cite:graphApiGuide,graphArchitecture,graphSlack,graphHandoff]]. Those items establish context for the product and for weakest-stage thinking. They do not ask whether a schema release label proves migration status. This paper's novelty boundary is therefore narrow: the Hash-Boundary Schema Release Ledger for Prisma-backed releases.
A ledger also reduces false alarms. The observed `.versions.json` gap could be a bug, a policy, or work in progress. The observed migration status failure could be ordinary local environment drift. The unchanged schema between 1.0.30 and 1.0.31 could be expected because application code changed without schema change [[cite:localVersionManifest,localVersionStatus,localVersionSnapshots,localMigrateStatus]]. Without a ledger, a future reviewer has to guess. With a ledger, the project can say exactly which stage is expected to move and which stage is unchanged by design.
The model also keeps security and operational claims proportional. NIST SSDF and SLSA both point toward traceable, reviewable software development and provenance practices, but they do not make every repository compliant just because it has hashes or scripts [[cite:nistSsdf,slsaProvenance]]. For a Prisma/PostgreSQL system, deployment safety also depends on database behavior. An index migration may be valid SQL and still deserve operational review, especially where concurrent index behavior or lock characteristics matter [[cite:localAgentIndexMigration,postgresCreateIndex]].
The smallest useful implementation would be a generated `schema-release-ledger.json` committed with each release. Fields should include release id, package version, git commit, snapshot path, tracked/untracked state, hash algorithm, hash covered paths, schema path, schema digest, migration directories included, Prisma validate result, generate/build/test result summaries, and a redacted migration status result. The public row should never contain local database endpoints, credentials, or machine-specific paths. It should be reproducible from repo-relative paths and redacted command summaries.
This is especially important for autonomous agents because agents tend to over-read nearby artifacts. If a folder named 1.0.31 exists, an agent may treat it as released. If a schema validates, an agent may treat the database as current. If a hash file exists, an agent may treat it as integrity proof. The ledger reduces those shortcuts by making stage boundaries explicit. The point is not to distrust agents more than humans; it is to give both the same concise evidence contract.
The model also has a maintenance advantage. A stale `.versions.json` entry and an untracked snapshot directory are easy to miss in a large repository. A generated ledger can fail a release check when the package version, manifest current pointer, snapshot directory, and tracked status disagree. That check does not need access to production credentials. It can run as a static pre-release guard and produce a narrow message: the schema may be valid, but the release record is not yet coherent.
The runtime stage remains different. A static guard can say whether a migration directory exists and whether a schema validates, but only a properly authenticated status or deployment record can speak for the database. The local `migrate status` boundary in this study is therefore not a defect in the ledger. It is exactly the kind of state the ledger should preserve: static release evidence is present, runtime migration evidence is absent in this observation [[cite:localMigrateStatus,prismaCliReference]].
A useful dashboard derived from the ledger would not display one green badge. It would display stage badges. Package version could be observed; snapshot tracked could be blocked; schema validation could be validated; migration deploy could be not observed. That display mirrors the evidence rather than compressing it. Compression is tempting for release communication, but it is the source of many false schema claims.
Limitations
This paper is not a production audit. It did not connect to a valid database, did not apply migrations, did not run the full API test suite, and did not inspect deployment infrastructure. The live database may be fully current, stale, absent, or intentionally inaccessible in the local environment. The only defensible claim is that live migration state was not observed from this checkout [[cite:localMigrateStatus]].
The study also treats local working-tree state carefully. The latest snapshot directory was untracked, which may reflect normal work in progress. The paper does not recommend deleting or reverting it. It uses that fact only to argue that public release claims should separate committed release evidence from local snapshot evidence [[cite:localVersionStatus]].
Finally, the ledger model is intentionally narrower than a complete supply-chain attestation. It does not replace Prisma's migration table, PostgreSQL operational monitoring, CI logs, deployment records, SBOMs, or SLSA provenance. It is a bridge record for agents and maintainers who need to know which schema-release stage has been verified before making a claim [[cite:prismaCliReference,slsaProvenance]].
Conclusion
Prisma schema releases need hash-boundary evidence, not snapshot folders alone. In the inspected DeepDive Canvas checkout, the ingredients for accountability are already present: Prisma scripts, a valid schema, migrations, snapshots, hash files, and application content-version code. The missing part is a joined ledger that says what each artifact proves and where the claim stops.
The practical rule is simple: publish the weakest verified stage. If the schema validates, say that. If migrations are present but deployment is unknown, say that. If a snapshot exists but is untracked, say that. If a hash exists, state its boundary. A schema-release ledger built around those statements would make future reviews faster, reduce false claims, and preserve the value of the existing snapshot work without pretending it proves database state by itself.