Found while verifying #4968 (PR for the OS_STORAGE_LOCAL_ROOT env-channel fix). Not caused by that change and not fixed there — filing per Prime Directive #10.
The claim
packages/cli/src/commands/dev.ts (the --fresh block) states:
Creates a unique scratch dir that owns ALL persistent state for this run: the SQLite DB (via OS_HOME → <home>/data/...), the storage-service uploads root, and any other state plugins keyed off OS_HOME. Auto-deleted on exit.
What is actually true after #4968
#4968 closes the storage half of this: with the env channel fixed, a --fresh run's uploads really do land in the tempdir and the project cwd stays clean. Verified on the PR branch — uploaded bytes at /tmp/objectstack-dev-*/uploads/user/..., nothing under examples/app-showcase/.objectstack.
What remains is the qualifier the sentence does not carry: the tempdir owns all framework-owned, OS_HOME-keyed state. State reached by an app-declared relative path is resolved against the process cwd and is untouched by --fresh.
Live specimen — the showcase's own external datasource, examples/app-showcase/src/system/datasources/showcase-external.datasource.ts:
config: { filename: '.objectstack/data/showcase_external.db' },Its own comment says so plainly ("Relative path → resolved against the project cwd by better-sqlite3"), so this is deliberate authoring, not a bug in the example. But the consequence is that every pnpm --filter @objectstack/example-showcase exec objectstack dev --fresh run leaves examples/app-showcase/.objectstack/data/showcase_external.db (+ -wal, -shm) behind in the working tree after exit — observed on both the pre-fix and post-fix boots.
Why it is observation-class rather than a defect
No user loses data and no documented deployment channel is broken; the residue is one example app's fixture database in a dev working tree. The defect, such as it is, is in the claim: "ALL persistent state" is the kind of unqualified promise that a reader relies on when reasoning about isolation, and #4968 exists precisely because a --fresh isolation promise was believed and was false. Marking finding, no pm:queue — the PM's triage round should grade it.
Possible dispositions (not a recommendation, just the shape)
- Narrow the comment (and any user-facing
--fresh docs) to name what is actually covered: state keyed off OS_HOME plus the env channels the CLI publishes.
- Additionally resolve relative datasource
filename against OS_HOME when it is set — a real behaviour change with a real contract question (does an app-declared relative path mean "relative to cwd" or "relative to this run's home"?), so it is not a drive-by.
Option 2 is a contract decision and should not be taken as implied by this filing.
Filed unassigned.
Found while verifying #4968 (PR for the
OS_STORAGE_LOCAL_ROOTenv-channel fix). Not caused by that change and not fixed there — filing per Prime Directive #10.The claim
packages/cli/src/commands/dev.ts(the--freshblock) states:What is actually true after #4968
#4968 closes the storage half of this: with the env channel fixed, a
--freshrun's uploads really do land in the tempdir and the project cwd stays clean. Verified on the PR branch — uploaded bytes at/tmp/objectstack-dev-*/uploads/user/..., nothing underexamples/app-showcase/.objectstack.What remains is the qualifier the sentence does not carry: the tempdir owns all framework-owned, OS_HOME-keyed state. State reached by an app-declared relative path is resolved against the process cwd and is untouched by
--fresh.Live specimen — the showcase's own external datasource,
examples/app-showcase/src/system/datasources/showcase-external.datasource.ts:Its own comment says so plainly ("Relative path → resolved against the project cwd by better-sqlite3"), so this is deliberate authoring, not a bug in the example. But the consequence is that every
pnpm --filter @objectstack/example-showcase exec objectstack dev --freshrun leavesexamples/app-showcase/.objectstack/data/showcase_external.db(+-wal,-shm) behind in the working tree after exit — observed on both the pre-fix and post-fix boots.Why it is observation-class rather than a defect
No user loses data and no documented deployment channel is broken; the residue is one example app's fixture database in a dev working tree. The defect, such as it is, is in the claim: "ALL persistent state" is the kind of unqualified promise that a reader relies on when reasoning about isolation, and #4968 exists precisely because a
--freshisolation promise was believed and was false. Markingfinding, nopm:queue— the PM's triage round should grade it.Possible dispositions (not a recommendation, just the shape)
--freshdocs) to name what is actually covered: state keyed offOS_HOMEplus the env channels the CLI publishes.filenameagainstOS_HOMEwhen it is set — a real behaviour change with a real contract question (does an app-declared relative path mean "relative to cwd" or "relative to this run's home"?), so it is not a drive-by.Option 2 is a contract decision and should not be taken as implied by this filing.
Filed unassigned.