From 07ae2f1497f62589057069b498afb5d11650ba5e Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sat, 18 Jul 2026 16:42:19 +0300 Subject: [PATCH 1/4] docs: record T3 review and first-slice boundary --- docs/architecture/technology-stack.md | 4 +- ...ient-vertical-slice-implementation-plan.md | 30 +- ...and-external-agents-implementation-plan.md | 4 +- .../open-source-adaptation-map.md | 13 +- lab/external/sources.lock.md | 2 +- lab/notes/README.md | 2 + .../first-slice-source-trace-2026-07-18.md | 408 ++++++++++++++++++ .../t3-code-targeted-review-2026-07-18.md | 136 ++++++ 8 files changed, 576 insertions(+), 23 deletions(-) create mode 100644 lab/notes/first-slice-source-trace-2026-07-18.md create mode 100644 lab/notes/t3-code-targeted-review-2026-07-18.md diff --git a/docs/architecture/technology-stack.md b/docs/architecture/technology-stack.md index 2d08106..93e0573 100644 --- a/docs/architecture/technology-stack.md +++ b/docs/architecture/technology-stack.md @@ -90,10 +90,10 @@ v0.5.5 passed hosted CI at `d4b10c27` and advanced owned `main` to owned `main` as `d9d8992a`, based on tested upstream `9be46c3c`. Subsequent reviewed UI and project-init status follow-ups advanced maintained `main` to `2ecfbe19`. Standalone ownership and upstream-maintenance follow-ups then -advanced maintained `main` to `d78388a4`; exact provenance is recorded in +advanced maintained `main` to `57e6b2cd`; exact provenance is recorded in `lab/external/sources.lock.md`. The owned OpenCode-derived repository—the current source foundation for the Scient -agent—is in the workspace sibling `../scient-agent/` on `dev` at `14003a01`, +agent—is in the workspace sibling `../scient-agent/` on `dev` at `bc125cbc`, after a reviewed sync through source version 1.18.3 at official upstream `69a80663` and the standalone upstream-maintenance rollout. Historical Gate 1 and Gate 1.5 commits, tags, and ignored runtime evidence remain diff --git a/docs/planning/first-scient-vertical-slice-implementation-plan.md b/docs/planning/first-scient-vertical-slice-implementation-plan.md index a8cd73a..5595a46 100644 --- a/docs/planning/first-scient-vertical-slice-implementation-plan.md +++ b/docs/planning/first-scient-vertical-slice-implementation-plan.md @@ -47,21 +47,21 @@ the next implementation step. ## Current Execution Status Phase 1 is complete. The placement trace selected the permanent package seam, -and desktop PR #4 implemented `@scientfactory/project-init` with zero-write -inspection, explicit plan/apply behavior, conservative recovery, and 43 focused -tests. The package remains present on the maintained desktop `main` at -`2ecfbe19`, after the verified Scient rename on the reviewed official Synara -v0.5.5 foundation and subsequent reviewed UI and project-init status -follow-ups. The owned OpenCode-derived agent-source baseline is -`5ffaf9a2` on `dev`, after the verified `scient-agent` source-boundary rename -and reviewed sync to official upstream `69a80663`. - -Phase 2, the remaining first-slice boundary trace, is the next work. The owned -OpenCode-derived checkout is the Scient agent's selected source foundation, but -the native agent is not yet implemented or packaged. No scientific-state store, -project-initiation UI or server RPC, Scient agent gateway, -proposal/decision ledger, or complete scientific workflow is claimed as -implemented. +and the reviewed desktop implementation added `@scientfactory/project-init` +with zero-write inspection, explicit plan/apply behavior, conservative +recovery, and focused tests. The package, trusted-server RPC, project-open/setup dialog, and +interrupted-initialization recovery UI are present on maintained desktop `main` +at `57e6b2cde09f64db367b894506f56db605fb91b4`. They initialize only the portable +foundation and do not make the host project projection canonical. + +Phase 2 source tracing is complete in +`../../lab/notes/first-slice-source-trace-2026-07-18.md` and awaits the required +Yaacov review checkpoint. The proposed decision is a permanent Scient project +domain/persistence package with thin host shims and a narrow executor port. +The selected OpenCode-derived source is `bc125cbc60c36e4b7013f8d7cf755f745af509b3` +on `dev`, but the native agent is not yet implemented or packaged. No +scientific-state store, Scient agent gateway, proposal/decision ledger, or +complete scientific workflow is claimed as implemented. ## Product Slice diff --git a/docs/planning/scient-and-external-agents-implementation-plan.md b/docs/planning/scient-and-external-agents-implementation-plan.md index e9baff6..a09cf3e 100644 --- a/docs/planning/scient-and-external-agents-implementation-plan.md +++ b/docs/planning/scient-and-external-agents-implementation-plan.md @@ -125,7 +125,7 @@ Source lineage does not merge product identities: ## Current Implementation Truth At maintained desktop-source revision -`d78388a42bcc09dabc926c0885ec34a8de6427b0`, inspected on 2026-07-18, the +`57e6b2cde09f64db367b894506f56db605fb91b4`, inspected on 2026-07-18, the inherited host contains a shared provider adapter contract and adapters for: - Codex; @@ -158,7 +158,7 @@ paths first, then certify compatibility honestly per agent. The owned OpenCode-derived checkout in the workspace sibling `../scient-agent/` (relative to the Scient repository root), maintained on -`dev` at `5ffaf9a2dfa5b958e8f4856b94b50d26b00c6b76`, is the accepted +`dev` at `bc125cbc60c36e4b7013f8d7cf755f745af509b3`, is the accepted source foundation for the Scient agent. Its repository and maintenance-verifier identity are Scient-owned while its current runtime remains upstream-aligned OpenCode source. Scient-agent packaging, private state diff --git a/docs/research/source-evaluations/open-source-adaptation-map.md b/docs/research/source-evaluations/open-source-adaptation-map.md index 88ce9aa..3272f82 100644 --- a/docs/research/source-evaluations/open-source-adaptation-map.md +++ b/docs/research/source-evaluations/open-source-adaptation-map.md @@ -57,6 +57,10 @@ Current inputs: [Lacuna: A Research Map for Machine Learning](https://arxiv.org/html/2606.26246v1) and live site as a research-map reference for literature search, synthesis, and agent-readable paper-grounded intermediate objects. +- Targeted T3 Code inspection through revision + `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0` on 2026-07-18, with + accepted, deferred, and rejected dispositions recorded in + [`t3-code-targeted-review-2026-07-18.md`](../../../lab/notes/t3-code-targeted-review-2026-07-18.md). Remaining evidence gaps before architecture promotion: @@ -330,13 +334,16 @@ is relevant only to a separately reviewed process or external-agent path. | Source | Adaptation target | Why it matters | Do not adopt | Depth status | |---|---|---|---|---| -| T3 Code | Desktop/backend process lifecycle, provider-instance patterns, remote/SSH/Tailscale ideas if needed, multi-surface product structure. | Gives practical patterns for a desktop agent app that coordinates backends and providers. | Do not inherit coding-product assumptions. | Needs targeted review of provider-instance and process lifecycle code. | +| T3 Code | Bounded reliability fixes now; provider-instance separation as design evidence for execution targets above `ProviderKind`; lifecycle and diagnostics patterns only when a concrete trigger appears. | Supplies proven implementation details and comparison evidence without becoming Scient's product architecture. | Do not inherit coding-product assumptions, broad runtime alignment, mobile/cloud surfaces, or speculative remote infrastructure. | Targeted review completed through `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0` on 2026-07-18. Three reliability fixes were accepted, snapshot startup was characterized, browser socket isolation was proven and fixed, and all larger ideas were explicitly deferred or rejected. | | Synara | Orchestration, UI/provider adapters, Effect server ideas, event-sourced orchestration, desktop/web split, worktree/Git flows. | Useful for building a reliable agent workspace that can explain what happened. | Do not copy its UI shape blindly; Scient needs a research cockpit. | Accepted initial application foundation through ADR-0001; scientific-product fit still needs pressure testing. | | Vercel AI SDK | Model/provider abstraction, typed stream parts, tool-call state, approval status, UI message events, mock providers, and model I/O tests. | Useful for model plumbing and chat/event surfaces around Scient-owned actions. | Do not use it as the abstraction over local executors like OpenCode or Codex. Executor actions need a Scient-owned contract. | Candidate model I/O layer; needs a narrow harness prototype. | | Vercel AI Elements | Tool cards, source citations, confirmations, terminal output, file trees, artifacts, plans, queue state. | Useful UI pieces for agent work inspection. | Do not let it make Scient a generic chat surface. | Side UI pattern source. | -Recommendation: adapt shell/process/provider ideas from T3 Code and Synara, but -keep the scientific navigation and object model Scient-owned. +Recommendation: keep Synara as the owned application foundation and use T3 Code +only as a trigger-driven donor. The completed T3 review does not create an +ongoing upstream-monitoring obligation. Provider-instance patterns may inform +the already-planned execution-target contract, while scientific navigation, +canonical state, provenance, review, and recovery remain Scient-owned. ### Desktop Base And Science-App Candidates diff --git a/lab/external/sources.lock.md b/lab/external/sources.lock.md index ce1f800..35d9711 100644 --- a/lab/external/sources.lock.md +++ b/lab/external/sources.lock.md @@ -29,7 +29,7 @@ siblings. A deferred source with no retained checkout says so explicitly. | Scient agent source (OpenCode-derived) | `../scient-agent/`; canonical workspace sibling on `dev` at `bc125cbc60c36e4b7013f8d7cf755f745af509b3` | `https://github.com/anomalyco/opencode.git`, `dev` | `https://github.com/ScientFactory/scient-agent`, public standalone repository | `69a80663a2ed7d671d2b4d5dd6f2d605714675a5` | Current owned `dev` `bc125cbc60c36e4b7013f8d7cf755f745af509b3`; exact rename and maintenance evidence below | Owned source foundation for the planned Scient agent; `adapter-maintained`; native Scient runtime identity is not yet implemented. | | Goose | No local checkout is retained. | `https://github.com/aaif-goose/goose.git`, `main` | None; owned repository deferred | Not tested in Gate 1.5 | Last inspected commit `3c1fdd692cc8aaa5f09b9175410c09a09d4dfe49` | Deferred broader-agent research input. Repository, build, ACP adapter, runtime, credentials, and adoption wait until after the first Scient gateway. | | Scient desktop (Synara-derived) | `../scient-desktop/`; canonical workspace sibling on `main` at `57e6b2cde09f64db367b894506f56db605fb91b4` | `https://github.com/Emanuele-web04/synara.git`, `main` | `https://github.com/ScientFactory/scient-desktop`, public standalone repository | `9be46c3ce6a7521b64436b7334bc6fce16e3cac4` | Current owned `main` `57e6b2cde09f64db367b894506f56db605fb91b4`; exact rename and maintenance evidence below | Accepted initial application foundation; `divergent-cherry-pick`; must not own scientific project truth. | -| T3 Code | No local checkout is retained. | `https://github.com/pingdotgg/t3code.git`, `main` | None | Not tested in Gate 1.5 | Last inspected commit `b9cc8d6ef17ca9f45bec621bef71ad3f706b9276` | Desktop/runtime/provider/process reference only. | +| T3 Code | No canonical local checkout is retained. | `https://github.com/pingdotgg/t3code.git`, `main` | None | Not tested in Gate 1.5 | Targeted review completed through `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0`; see [`t3-code-targeted-review-2026-07-18.md`](../notes/t3-code-targeted-review-2026-07-18.md) | Trigger-driven desktop/runtime/provider/process reference only; not a continuously monitored upstream. | ## Maintained Upstream Review State diff --git a/lab/notes/README.md b/lab/notes/README.md index 537f566..8dbfed5 100644 --- a/lab/notes/README.md +++ b/lab/notes/README.md @@ -20,6 +20,8 @@ integration observations, and temporary lab decisions. - `synara-gate-1-baseline-2026-07-11.md` - historical inherited-scaffold baseline, official-CLI correction run, and Gate 1 pass result. - `synara-first-inspection-2026-07-07.md` - first source inspection of Synara as desktop base, OpenCode first-agent path, Goose integration path, and Scient ownership boundary. - `goose-source-depth-inspection-2026-07-11.md` - research input for Goose's later role, ACP surfaces, runtime-state boundary, permission risks, and first adapter recommendation. +- `first-slice-source-trace-2026-07-18.md` - exact desktop/agent path trace and proposed permanent boundary for the first scientific source-to-note slice, awaiting the required user review checkpoint. +- `t3-code-targeted-review-2026-07-18.md` - bounded T3 Code review through `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0`, including accepted reliability work and explicit deferred/rejected dispositions. Keep notes clear about whether they are: diff --git a/lab/notes/first-slice-source-trace-2026-07-18.md b/lab/notes/first-slice-source-trace-2026-07-18.md new file mode 100644 index 0000000..fe77ca1 --- /dev/null +++ b/lab/notes/first-slice-source-trace-2026-07-18.md @@ -0,0 +1,408 @@ +# First Scientific Slice Source Trace + +Status: Complete; awaiting Yaacov review +Owner: Yaacov +Created: 2026-07-18 +Last updated: 2026-07-18 +Purpose: Selects the permanent Scient-owned state, recovery, UI, and execution boundary for the first scientific vertical slice. +Doc type: Implementation evidence + +## Verdict + +**Go for the permanent walking skeleton after the review checkpoint.** The +maintained Synara-derived desktop can host the slice without making its project, +thread, provider, or checkpoint projections canonical scientific state. + +Use a hybrid placement: + +1. a permanent `packages/scient-project` package in `scient-desktop` owns the + first-slice domain rules, project-local persistence, proposal decisions, + recovery, and filesystem-scope policy; +2. thin contracts, trusted-server RPC, and project-level UI shims call that + package; and +3. a narrow executor port accepts immutable task/context receipts and returns a + proposal. A deterministic fake implements that port first. Scient later + implements it as a distinct execution target; external OpenCode remains an + independent adapter. + +Canonical accepted state belongs in the project folder, with `.scient/project.json` +as portable identity and `.scient/project.sqlite` as the first-slice record and +revision ledger. Synara's `~/.scient/userdata/state.sqlite`, provider sessions, +chat transcripts, and Git checkpoint refs remain host state or execution +evidence only. + +The existing Git-backed checkpoint mechanism is not suitable for the required +non-Git guarantee. For the first slice, proposal acceptance should be one SQLite +transaction that creates a recovery point referring to the prior accepted +revisions, appends the decision, and advances the accepted record pointers. +Revert creates new accepted revisions; it does not rewrite history. No Git +repository, worktree, executor session, or transcript is required to reopen or +recover the accepted source-to-note relationship. + +One required native-agent gap is now proven: the selected `scient-agent` source +still defaults its global data/config/state roots and database name to +`opencode`. Native Scient packaging must supply a dedicated first-party runtime +profile before it can be connected. That change must not alter the existing +external OpenCode adapter or its user-owned data paths. + +## Controlled Fixture + +Use a deterministic synthetic capsule for the first implementation PR. This is +the safer first fixture because no public capsule with compatible excerpt, +dataset, figure, and redistribution rights has yet been validated as one +self-contained unit. Replacing the fixture later with an openly licensed study +does not change the selected architecture. + +The capsule is `greenhouse-seedling-capsule` and lives outside every parent Git +repository during runtime tests. Its committed test fixture will contain: + +- `README.md`: project title, question, and short plan; +- `sources/trial-summary.txt`: a locally authored source summary with one + designated exact excerpt; +- `data/seedling-heights.csv`: a small deterministic dataset; +- `analysis/summary.txt`: precomputed group means and the command used to + reproduce them; +- `outputs/height-by-treatment.svg`: one representative figure; +- `writing/results-fragment.md`: a short results fragment; +- `expected/stages.json`: deterministic initialized, source-added, + task-created, proposed, accepted, reopened, and recovered states; and +- no network, cloud service, parser, sensitive data, or external API. + +The first exercised thread is deliberately narrower than the capsule: manually +select one exact excerpt, create the task “Summarize this excerpt as a +two-sentence evidence note using only the selected text,” produce one +deterministic proposed note, inspect its source link, accept or reject it, +reopen the project, and prove recovery. The data, analysis, figure, and writing +files are context for future slices and are not ingested in this one. + +## Selected Sources And Health + +| Source | Selected revision | Working state | Relevant upstream result | Minimal health evidence | +|---|---|---|---|---| +| Scient desktop (`scient-desktop`) | owned `main` `57e6b2cde09f64db367b894506f56db605fb91b4` | Canonical checkout clean when selected | Official Synara reviewed through `69304bc1d59d86da8afbac367118c75db8c9dbfe`; verifier current with no unreviewed commits | Existing installed-app smoke reached project initialization. On reliability branch `8a8398e8`, full tests, typecheck, build, release smoke, and 171 browser tests passed; the branch does not alter this trace's product seams. | +| Scient agent (`scient-agent`) | owned `dev` `bc125cbc60c36e4b7013f8d7cf755f745af509b3` | Clean and equal to `origin/dev` | Official OpenCode reviewed through `fab213312927ea64cf968832c527206e8c944f9e`; verifier current with no unreviewed commits | Maintained upstream verifier and public-identity check passed. A live Scient action was not run because native Scient identity, private state, packaging, and gateway are correctly still absent. | + +No upstream code was merged during this trace. The agent revision advanced only +through already-merged repository automation changes after the prior source-lock +snapshot; the runtime files inspected below remain selected source, not proof of +a native Scient product. + +## Path A: Project Creation, Opening, And Reopening + +### Current path + +| Stage | Exact entry point | State and behavior | +|---|---|---| +| Folder selection and setup choice | `apps/web/src/components/Sidebar.tsx`: `addProjectFromPath`, `requestProjectInitializationDecision`; `apps/web/src/components/ScientProjectInitializationDialog.tsx` | Opening first calls the Scient initialization preview. The user may initialize, recover, roll back, open without setup, or cancel. Opening without setup makes no Scient initialization write. | +| Shared initialization flow | `apps/web/src/lib/scientProjectInitialization.ts`: `prepareScientProjectForOpening` | Re-previews after failures, consumes one-time preview capabilities, reports completion, and keeps initialization separate from project registration. | +| Trusted filesystem application | `apps/server/src/scientProjectInitialization.ts`: `ScientProjectInitializationService`; `packages/scient-project-init` | The server calls the existing dependency-light kernel. Preview capabilities expire and are single-use. Kernel preconditions, path containment, transaction recovery, and preserve/propose/conflict behavior remain authoritative. | +| Host project registration | `apps/web/src/lib/projectCreation.ts`: `createOrRecoverProjectFromPath`; `apps/server/src/orchestration/decider.ts`: `project.create`; `apps/server/src/orchestration/projectMetadataProjection.ts`: `applyProjectMetadataProjection` | A Synara project ID, title, workspace root, default model, and timestamps are persisted as events and `projection_projects`. Duplicate roots are recovered or rejected. This registration can survive restart but is a host index, not Scient project identity. | +| Restart read model | `apps/server/src/orchestration/Layers/ProjectionPipeline.ts`; `apps/server/src/orchestration/Layers/ProjectionSnapshotQuery.ts`; `apps/web/src/store.ts` | SQLite projections rebuild the shell snapshot and sidebar. Failure to synchronize is surfaced as a retryable add-project error. | + +Desktop production state derives from `SCIENT_HOME` (normally `~/.scient`). +`apps/server/src/config.ts:deriveServerPaths` places host events, projections, +settings, and provider session projections in +`~/.scient/userdata/state.sqlite`. Electron/Chromium UI state uses the separate +platform user-data profile resolved by +`apps/desktop/src/desktopUserDataProfile.ts` (on macOS, +`~/Library/Application Support/scient`). + +### Scient attachment point + +After the host resolves a workspace root, the trusted server should inspect +`.scient/project.json` and open `.scient/project.sqlite` through the new package. +The project-level UI is keyed by the portable Scient project ID, while the +Synara project ID remains a replaceable host reference. Moving the whole folder +preserves Scient identity and history; reopening from a new path may create or +recover a different host project row without changing canonical records. + +Failure to open the canonical store must not silently fall back to chat state. +It should show an explicit unavailable/migration/recovery state and leave the +project files untouched until the user chooses a safe action. + +## Path B: Manual Operations And Minimal UI + +The current product has the necessary shell but no canonical scientific +operations. The smallest placement is a new project-level route and component, +not another chat-thread projection: + +- add `_chat.project.$projectId.tsx` as the thin route shim; +- add a focused `ScientProjectView` with source, task/context, proposal, and + history sections; +- enter it from the existing project row/context menu in `Sidebar.tsx`; +- reuse existing dialog, button, form, toast, loading, and error primitives; +- reuse `WorkspaceFilePreview` only for optional local-file inspection; and +- use a small structured before/proposed-note review card. Do not force the + note through Git/file diff machinery merely to reuse `DiffPanel`. + +Both UI actions and executor output call the same package commands through the +trusted server: + +- add or revise a source excerpt; +- create a task and immutable context receipt; +- begin/finish/fail a run receipt; +- record a proposal linked to exact source and context revisions; +- edit the proposal without accepting it; +- accept or reject with a decision record; and +- create or apply a recovery action. + +The existing `EditorWorkspaceView`, chat composer, Kanban board, and +thread-proposed-plan surfaces may remain available, but none owns source, +evidence, task, proposal, or decision truth for this slice. + +## Path C: Scient Execution And External OpenCode Separation + +### Reusable inherited path + +| Concern | Exact current seam | Reuse decision | +|---|---|---| +| Provider contract | `apps/server/src/provider/Services/ProviderAdapter.ts`: `ProviderAdapterShape` | Reuse provider session, send, interrupt, request response, thread read, and canonical event concepts behind a new executor port. Do not expose `ProviderKind` as Scient's durable execution-target identity. | +| Session orchestration | `apps/server/src/orchestration/Layers/ProviderCommandReactor.ts`: session start/restart, cwd resolution, prompt assembly, interrupt, approval dispatch | Reuse as external-agent infrastructure. Native Scient may later adapt to the same normalized lifecycle, but scientific context must be assembled by the Scient gateway from an immutable context receipt. | +| External OpenCode | `apps/server/src/provider/Layers/OpenCodeAdapter.ts`: `startSession`, `sendTurn`, `interruptTurn`, `respondToRequest`; `apps/server/src/provider/opencodeRuntime.ts`: `OPENCODE_CLI_SPEC` | Preserve unchanged as the user's independently installed/connected OpenCode. It keeps its own binary/URL/password, `opencode` data directory, credentials, sessions, and updates. | +| Runtime evidence | `packages/contracts/src/providerRuntime.ts`: `ProviderRuntimeEvent` family; `apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.ts` | Reuse normalized session, turn, item, content, approval, tool, file, warning, error, and completion events as execution evidence. They do not become canonical scientific records. | +| Native source | owned `scient-agent`: `packages/core/src/global.ts`; `packages/core/src/database/database.ts` | Selected inherited core, but not yet a native product runtime. It currently hardcodes the application path segment `opencode` and default database names `opencode*.db`; this is the exact state-isolation gap to close. | + +### Execution contract + +Add a Scient-owned `ScientificTaskExecutor` port whose input contains only: + +- stable execution-target ID; +- Scient project ID and run ID; +- project-root capability reference, not an arbitrary model-generated path; +- immutable task revision; +- immutable context receipt with selected source revision IDs and hashes; +- allowed operation/capability set; and +- cancellation signal. + +Its output is a proposed record plus normalized run evidence. It cannot accept +scientific state and cannot write canonical tables directly. The server records +the run and proposal through package commands after validating IDs, hashes, +scope, and current revisions. + +### Filesystem scope + +`apps/server/src/workspace/Layers/WorkspacePaths.ts` and +`WorkspaceFileSystem.ts` already provide useful lexical and real-path +containment for app file RPC. They should be reused by server shims, including +symlink checks, but they do not confine provider-native tools or a shell. + +The selected agent source improves mutation safety in +`packages/core/src/location-mutation.ts`, which rejects relative escapes and +requires `external_directory` permission for explicit external mutation paths. +However, `packages/core/src/tool/bash.ts` explicitly states that command-argument +path scanning is advisory and that the shell runs with host-user filesystem, +process, and network authority. A cwd plus approval mode is therefore not an +enforceable project sandbox. + +For the first slice: + +1. canonical operations accept only package IDs and root-relative paths; +2. the fake executor has no filesystem capability; +3. native Scient later runs with a dedicated capability profile that disables + unrestricted shell/direct-write tools for this workflow and exposes only + scoped Scient gateway tools; +4. every gateway path is resolved against the registered real project root and + rechecked after following existing ancestors/symlinks; and +5. proposal acceptance, not model output, is the only route to canonical state. + +If a later workflow genuinely requires arbitrary shell execution, add an OS +sandbox or isolated staged workspace as a separate safety slice. Do not claim +that the current OpenCode permission prompt alone enforces filesystem scope. + +## Path D: Persistence And State Ownership + +| State | Current owner | Location | Survives restart? | Canonical for Scient? | +|---|---|---|---|---| +| Application identity and settings | Synara-derived Scient host | Electron profile under platform app data; server settings at `~/.scient/userdata/settings.json` | Yes | No | +| Workspace path | Synara-derived host | `projection_projects.workspace_root` in `~/.scient/userdata/state.sqlite` and UI shell state | Yes | Host reference only | +| Synara project/session projection | Synara-derived host | orchestration events and projection tables in `~/.scient/userdata/state.sqlite` | Yes | No | +| Scient session and transcript | Missing; OpenCode-derived source selected | Must use a dedicated first-party agent data/config/state root and database, separate from external OpenCode | Must for runtime continuity | No | +| External OpenCode session and transcript | External OpenCode plus host adapter | External OpenCode's XDG/Application Support `opencode` data; resume/session projection in host SQLite | Provider-dependent; normally yes | No | +| Runtime events and tool logs | Agent plus host ingestion | Provider-native store; normalized host events/projections; optional `~/.scient/userdata/logs/provider/events.log` | Yes where persisted | Evidence only | +| Scient project identity | Existing project-init kernel | `.scient/project.json` | Yes and moves with folder | Yes | +| Source excerpt and evidence note | New Scient project package | Versioned rows in `.scient/project.sqlite` | Yes | Yes | +| Task and context receipt | New Scient project package | Versioned task and immutable context-receipt rows in `.scient/project.sqlite` | Yes | Yes | +| Run receipt, proposal, and decision | New Scient project package | Append-only run, proposal revision, and decision rows in `.scient/project.sqlite` | Yes | Yes | +| Recovery state | New Scient project package | Recovery-point and accepted-revision ledger rows in `.scient/project.sqlite`; content-addressed blobs only when later file materialization requires them | Yes | Yes | + +Project-local SQLite must use foreign keys, WAL or an equally safe journaling +mode, explicit schema versioning, deterministic migrations, busy timeouts, and +backup/recovery tests. Secrets and provider credentials never enter this file. +Large source files are out of scope; the first exact excerpt is stored as text +with a digest and local source locator. + +## Path E: Proposal, Review, Non-Git Recovery, And Reopening + +Current checkpointing is intentionally Git-specific: + +- `apps/server/src/checkpointing/Services/CheckpointStore.ts` defines hidden + Git-ref capture, restore, reverse diff, and checkpoint diff; +- `apps/server/src/checkpointing/Layers/CheckpointStore.ts` implements those + operations with an isolated Git index and refs; and +- `apps/server/src/orchestration/Layers/CheckpointReactor.ts` emits + “Checkpoints are unavailable because this project is not a git repository” + for the non-Git boundary. + +Provider live diffs and host proposed plans are useful presentation/evidence +inputs, but they remain thread/provider projections and cannot reconstruct an +accepted scientific note after their session is deleted. + +The first-slice proposal flow is instead: + +1. create immutable source, task, and context revisions; +2. open a run receipt before executor invocation; +3. record executor evidence and a proposal linked to exact revision IDs; +4. allow proposal text edits as new proposal revisions; +5. on accept, begin one database transaction; +6. append a recovery point containing the prior accepted revision pointers; +7. append the decision and accepted note revision; +8. atomically advance the accepted pointers and commit; and +9. on reject or failure, append the outcome without changing accepted pointers. + +Reopening reads the portable project identity and canonical ledger without +starting an agent. Recovery creates a new decision/revision that points back to +the recovery point; audit history remains intact. Interrupted transactions roll +back through SQLite. Corruption/open failures are explicit and read-only until +backup or repair is chosen. + +This is credible for the fixture because acceptance changes only canonical +records. Later materialized project-file changes require content-addressed +preimages or another reviewed file transaction; they must not be silently +declared covered by the first ledger. + +## Permanent Seam Comparison + +Scores use 1 (poor) to 5 (strong). + +| Option | Shared manual/agent operations | Session-independent truth | Non-Git recovery | Low inherited-core change | Upstream cost | Maintainer clarity | Reversible | +|---|---:|---:|---:|---:|---:|---:|---:| +| One namespaced package with integration left implicit | 4 | 5 | 5 | 5 | 5 | 4 | 5 | +| Isolated modules scattered across contracts/server/UI | 3 | 2 | 3 | 3 | 2 | 2 | 2 | +| **Hybrid package plus thin integration shims and executor port** | **5** | **5** | **5** | **4** | **4** | **5** | **5** | + +The hybrid is selected because the package makes ownership and portability +real, while named shims make the UI/server/executor crossings explicit and +testable. Scattered modules would let host projections become accidental truth. +A package with no explicit integration policy would still leave executor and UI +call paths ambiguous. + +## Reuse Unchanged + +- `@scientfactory/project-init` for folder inspection, initialization, + migration, and interrupted-init recovery; +- folder picker, duplicate project recovery, host project registration, and + sidebar shell; +- trusted local server and typed websocket RPC transport; +- `WorkspacePaths`/`WorkspaceFileSystem` containment for app-owned paths; +- normalized provider runtime events as execution evidence; +- provider interrupt and approval UI concepts behind the executor adapter; +- common UI primitives, toasts, loading/error surfaces, and optional file + preview; and +- existing external provider registry/settings/adapters, especially OpenCode. + +## Do Not Couple Scient Truth To + +- `ProviderKind`, model selection, or one provider's resume cursor; +- Synara project ID, thread ID, message ID, proposed-plan rows, or checkpoint + refs; +- app `state.sqlite`, browser local storage, Electron profile, or provider event + log; +- external OpenCode binary, URL, password, auth file, XDG root, session DB, or + update channel; +- Git repository presence, worktrees, branches, or hidden refs; +- unrestricted shell commands or model-generated paths; or +- T3 Code, Goose, cloud, mobile, collaboration, or remote execution. + +## Required Changes And Proven Gaps + +### Scient desktop + +- add `packages/scient-project` with domain commands, SQLite repository, + migrations, revision/recovery ledger, and path-scope policy; +- add narrow DTO/RPC contracts and server services that resolve portable + identity from the workspace root and call the package; +- add one project-level route/view and sidebar entry; and +- add the executor port, deterministic fake, and later one Scient adapter. + +No change to Synara's orchestration event schema, `projection_projects`, generic +provider event schema, or Git checkpoint store is required for the fixture. + +### Scient agent + +Before native connection, replace the inherited hardcoded global identity/path +defaults with a build/runtime profile that gives Scient dedicated data, config, +state, cache, temp, log, auth, database, plugin, and update locations. Use a +brand-neutral durable first-party ID where records persist. Keep upstream +OpenCode defaults available to external OpenCode builds; never redirect or +migrate the user's external OpenCode state implicitly. + +Then expose a bounded Scient workflow capability that consumes the gateway +receipt and returns a proposal. The first capability profile must not provide +unrestricted shell or direct canonical writes. + +## Exact First Coding Backlog + +After Yaacov accepts this trace, implement in this order and keep each repository +change independently reviewable: + +1. **Fixture and package contract:** commit the synthetic capsule fixture and + create `@scientfactory/scient-project` with branded IDs, schemas, command + results, revision invariants, and a deterministic in-memory repository. +2. **Canonical store:** add `.scient/project.sqlite` open/create validation, + migrations, source/task/context/run/proposal/decision tables, transactional + acceptance, recovery points, reopen/move tests, busy/corrupt/interrupted + cases, and dependency audit. +3. **Trusted server boundary:** add project-root identity resolution, real-path + scope checks, package service wiring, typed RPC methods, and tests proving + host project/session deletion cannot delete canonical records. +4. **Manual project UI:** add the project-level route/view, manual excerpt and + task/context forms, proposal edit/accept/reject/history UI, explicit store + errors, and close/reopen flow. +5. **Fake executor proof:** implement `ScientificTaskExecutor` with a + deterministic fake that receives only the context receipt and returns the + expected two-sentence proposal; prove cancellation/failure leave accepted + state unchanged. +6. **End-to-end non-Git test:** run initialized -> source -> task -> proposal -> + accept -> close -> move folder -> reopen -> recover, while proving the + folder remains outside Git and no provider transcript is needed. +7. **Execution-target foundation:** add stable agent-connection/execution-target + identity above `ProviderKind`, preserve all external settings and adapters, + and test migration with Scient absent/present. +8. **Native Scient isolation:** in `scient-agent`, add the dedicated first-party + runtime profile and prove simultaneous Scient/external-OpenCode credentials, + processes, paths, sessions, and updates do not overlap. +9. **Native adapter:** connect Scient to the executor port with scoped gateway + tools, normalized evidence, cancellation, and failures; replay a sanitized + live run before the final controlled-fixture smoke. + +Do not combine steps 7-9 with the first domain/store PR. The fake proves the +scientific boundary before provider plumbing can obscure it. + +## Go/No-Go Conditions + +Go after review because: + +- manual and agent paths share one command boundary; +- accepted state is independent of host and provider sessions; +- non-Git recovery is transactional and testable for the fixture; +- project scope is enforced at the canonical/gateway boundary rather than + trusted to prompt wording; +- external OpenCode remains unchanged; and +- the first coding backlog is bounded. + +Stop and revisit this decision if implementation proves any of these: + +- project-local SQLite cannot be opened/moved/recovered safely across supported + desktop platforms; +- accepted state requires host projection IDs or an executor transcript; +- scoped gateway tools cannot prevent direct native-agent writes for the + controlled workflow; +- native Scient cannot isolate every durable path from external OpenCode without + a broad upstream-hostile rewrite; or +- the project-level UI requires a broad workbench redesign. + +## Review Checkpoint + +No product-code implementation follows from this note until Yaacov reviews the +selected hybrid boundary, `.scient/project.sqlite` ledger, non-Git recovery, +filesystem-scope rule, external OpenCode separation, and backlog above. diff --git a/lab/notes/t3-code-targeted-review-2026-07-18.md b/lab/notes/t3-code-targeted-review-2026-07-18.md new file mode 100644 index 0000000..3793ef6 --- /dev/null +++ b/lab/notes/t3-code-targeted-review-2026-07-18.md @@ -0,0 +1,136 @@ +# T3 Code Targeted Review + +Status: Complete +Owner: Yaacov +Created: 2026-07-18 +Last updated: 2026-07-18 +Purpose: Records the bounded T3 Code inspection, accepted reliability intake, and explicit stop boundary for future T3-derived work. +Doc type: Research evidence + +## Verdict + +T3 Code remains a useful subsystem donor, not Scient's application foundation, +product roadmap, or continuously monitored upstream. The targeted review is +complete through T3 Code revision +`bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0`. + +The review found three small reliability changes worth adapting immediately, +one subscription-startup risk that Scient's current Effect runtime already +handles correctly, and one real multi-socket browser isolation defect in the +Scient desktop. Larger T3 architecture remains either part of an existing +Scient plan, deferred until a concrete trigger appears, or rejected for the +current product scope. + +## Source Snapshot + +| Item | Evidence | +|---|---| +| Official source | `https://github.com/pingdotgg/t3code.git` | +| Branch inspected | `main` | +| Review boundary | `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0` | +| Review date | 2026-07-18 | +| License observed | MIT | +| Scient desktop base reviewed | `57e6b2cde09f64db367b894506f56db605fb91b4` | +| Review method | Exact donor commits, corresponding Scient seams, existing tests, and deterministic characterization tests were inspected locally. | + +The temporary T3 checkout used for this review is not a canonical Scient source +checkout. `lab/external/sources.lock.md` remains the durable provenance record. + +## Accepted Reliability Intake + +| T3 evidence | Scient seam | Disposition | Scient evidence | +|---|---|---|---| +| `ed81c156daf3d8ce7d3599236df7a26c11ef145f` | `apps/server/src/imageMime.ts` | Adapted. The payload parser now scans linearly instead of applying a regex to multi-megabyte base64 content. | Desktop commit `9c36410e`; focused tests cover malformed input, padding, whitespace, case handling, and a 14 MB payload from a deep stack. | +| `58302b2010913d6e236570bbe8c9abe38de7fa18` | `apps/server/src/git/Layers/GitCore.ts` | Adapted. Selected paths use Git's global `--literal-pathspecs` option. | Desktop commit `ee705427`; integration coverage includes brackets, glob characters, question marks, pathspec magic, a leading dash, spaces, and Unicode. | +| `1047dac0c5296b1c548e607f061f95227a706b49` | `apps/server/src/terminal/Layers/Manager.ts` | Adapted. AppImage markers and mount-prefixed path entries are removed at the terminal child-environment boundary. | Desktop commit `353f8d67`; tests prove marker/path cleanup, unrelated-variable preservation, non-AppImage identity behavior, and no host-environment mutation. | + +These changes preserve Scient's existing contracts and introduce no new runtime +dependency, provider model, or T3-owned abstraction. + +## Characterization Results + +### Snapshot And Live-Event Startup + +T3 commit `c14a5ca492b4da11da81e482e307222946536300` fixed events dropped while an +initial thread snapshot loaded. Scient uses `Stream.merge` for the analogous +shell and thread subscriptions. + +A deterministic barrier test now proves that Scient's current Effect runtime: + +1. subscribes to the live stream while the snapshot is blocked; +2. captures an event emitted during snapshot loading; +3. emits the snapshot first; +4. emits the during-snapshot event exactly once; and +5. continues with later live events in order. + +The characterization passed without a runtime behavior change. Desktop commit +`f12d5b56` names the shared subscription seam and adds the regression test. + +### Browser Native-Pipe Socket Isolation + +The Scient browser-use bridge attached CDP listeners per session but broadcast +every notification to every connected native-pipe socket. A two-socket protocol +test proved that a tab event for session A leaked to session B. The same test +also showed that disconnecting a socket left its CDP listener active. + +Desktop commits `fe4668fa` and `8a8398e8` bind each attached session to its +owning socket, send notifications only through that socket, reject cross-client +attach, detach, and CDP requests, dispose the session listener on disconnect, +and preserve the other socket. The test exercises real framed native-pipe +requests and two distinct tabs rather than only testing an internal helper. The +complete bounded intake is published for review in +[Scient desktop PR #14](https://github.com/ScientFactory/scient-desktop/pull/14). + +## Use During Existing Scient Work + +T3's provider-instance separation is useful evidence for Phase 2 of +`docs/planning/scient-and-external-agents-implementation-plan.md`. It does not +justify a separate T3-alignment project. + +When the first scientific vertical slice reaches its execution contract: + +- keep `ProviderKind` as an external-provider implementation detail; +- add stable agent-connection identity above it; +- represent native Scient and external-agent connections as distinct execution + targets; +- use one narrow executor port and a deterministic fake executor; +- preserve existing external adapters and settings; and +- keep canonical scientific state independent of every provider session store. + +The first-slice boundary trace and its user review checkpoint remain the gate +before product-code implementation. + +## Triggered Shelf + +The following ideas are not scheduled. Reinspect T3 only when the named trigger +exists. + +| Candidate | Trigger required before work | First bounded proof | +|---|---|---| +| Connection supervisor | More than one real connection or recurring lifecycle leaks | Tested connection state machine | +| Desktop-main decomposition | Repeated feature collisions in the same desktop lifecycle seam | Extract only the seam under active change | +| Diagnostics bundle | A user-visible failure cannot be diagnosed from existing logs | Redaction-first diagnostic export | +| Reusable Codex protocol package | A second genuine protocol consumer | Extract only proven shared protocol types | +| VCS/forge abstraction | The scientific slice requires a demonstrated collaboration operation | Model that operation only | +| Execution environments or SSH | An accepted remote-execution scenario | One target-specific adapter | +| Capability authorization | An executor gains a new privileged action | Explicit capability and denial tests | + +## Rejected For Current Scope + +- broad T3 architecture alignment; +- replacing the Synara-derived desktop foundation; +- importing T3's coding-product assumptions; +- mobile companion work; +- cloud or relay synchronization; +- Tailscale integration; +- WSL expansion; and +- speculative SSH or remote-environment infrastructure. + +## Operating Rule After This Review + +Do not monitor T3 Code as though it were an owned upstream. Future T3 inspection +must begin with a concrete Scient problem, name the exact source revision and +files inspected, produce a bounded adaptation or explicit rejection, and stop +when that problem is resolved. + +The primary product track returns to the first scientific vertical slice. From f0ef3cdd32a74638e7ac736c5f50d77134750e08 Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sat, 18 Jul 2026 17:20:38 +0300 Subject: [PATCH 2/4] docs: defer project persistence decision --- docs/README.md | 1 + docs/architecture/README.md | 3 + docs/architecture/local-first-sync.md | 7 +- docs/architecture/project-format.md | 5 +- ...ient-project-persistence-decision-brief.md | 619 ++++++++++++++++++ docs/architecture/technology-stack.md | 59 +- ...ient-vertical-slice-implementation-plan.md | 49 +- lab/notes/README.md | 2 +- .../first-slice-source-trace-2026-07-18.md | 280 ++++---- .../t3-code-targeted-review-2026-07-18.md | 9 +- 10 files changed, 857 insertions(+), 177 deletions(-) create mode 100644 docs/architecture/scient-project-persistence-decision-brief.md diff --git a/docs/README.md b/docs/README.md index 885fadc..5c2c86f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,6 +32,7 @@ Start here: - [Scient product identity](product/scient-product-identity.md) - accepted company, app, native-agent, external-agent, and naming vocabulary. - [Product philosophy](product/product-philosophy.md) - draft durable product principles; the accepted PRD governs conflicts. - [Technology stack](architecture/technology-stack.md) - current proposed stack direction. +- [Scient project persistence decision brief](architecture/scient-project-persistence-decision-brief.md) - draft context, alternatives, questions, and evidence gates for later storage review; no project store is selected. - [Product roadmap](planning/product-roadmap.md) - current sequence of coherent product outcomes. - [First vertical-slice implementation plan](planning/first-scient-vertical-slice-implementation-plan.md) - bounded plan for the active product slice. - [Scient and external agents implementation plan](planning/scient-and-external-agents-implementation-plan.md) - proposed plan for building the Scient agent as the owned OpenCode-derived first-party agent while preserving external agents independently. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 23f6205..e017c3c 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -12,6 +12,9 @@ Architecture docs explain how Scient should be structured and why. They must cle Current documents: - `technology-stack.md` - current stack direction. +- `scient-project-persistence-decision-brief.md` - draft reviewer brief for the + unresolved canonical project-state, reliability, portability, backup, sync, + and storage-technology decision; it is not implementation authorization. - `project-format.md` - future home for the Scient project format. - `local-first-sync.md` - future home for local-first and sync architecture. - `collaboration-model.md` - future home for collaboration architecture. diff --git a/docs/architecture/local-first-sync.md b/docs/architecture/local-first-sync.md index ba4ff3c..311ee04 100644 --- a/docs/architecture/local-first-sync.md +++ b/docs/architecture/local-first-sync.md @@ -7,12 +7,15 @@ Last updated: 2026-07-17 Purpose: Defines what should be documented about Scient local-first storage and cloud sync once the design is validated. Doc type: Future home -This page will document Scient's local-first and sync architecture when it exists. +This page will document Scient's local-first and sync architecture when it +exists. The upstream decision context is currently captured in the draft +[Scient Project Persistence Decision Brief](scient-project-persistence-decision-brief.md), +which does not select a canonical project store or sync engine. Document here: - offline behavior -- local SQLite boundaries +- local application-state and project-owned-state boundaries - cloud mirror semantics - sync engine selection - conflict handling diff --git a/docs/architecture/project-format.md b/docs/architecture/project-format.md index 2694092..5c7c800 100644 --- a/docs/architecture/project-format.md +++ b/docs/architecture/project-format.md @@ -7,7 +7,10 @@ Last updated: 2026-07-17 Purpose: Defines what should be documented about Scient project structure once the format is designed. Doc type: Future home -This page will document the Scient project format when it exists. +This page will document the Scient project format when it exists. The open +canonical-state requirements, candidate representations, and proof obligations +are currently framed in the draft +[Scient Project Persistence Decision Brief](scient-project-persistence-decision-brief.md). Document here: diff --git a/docs/architecture/scient-project-persistence-decision-brief.md b/docs/architecture/scient-project-persistence-decision-brief.md new file mode 100644 index 0000000..e14a6e4 --- /dev/null +++ b/docs/architecture/scient-project-persistence-decision-brief.md @@ -0,0 +1,619 @@ +# Scient Project Persistence Decision Brief + +Status: Draft +Owner: Yaacov +Created: 2026-07-18 +Last updated: 2026-07-18 +Purpose: Frames the open decision about where Scient-owned scientific records should live and what evidence is required before selecting or implementing a persistence design. +Doc type: Architecture direction + +## Document Rules + +- This is a review brief, not accepted architecture, an implementation plan, or + evidence that a project-local database exists. +- The accepted PRD owns the product outcomes. This brief translates those + outcomes into persistence questions and proof obligations. +- SQLite is one serious candidate. It is not selected by this document. +- The inherited application SQLite database is current implementation, but it + is not automatically the canonical Scient project store. +- No production persistence code, schema, sync layer, or migration should be + created from this brief before the decision process reaches explicit human + acceptance. + +## Executive Summary + +Scient needs a durable home for scientific records that must survive beyond a +chat, agent session, provider, or one installation of the desktop app. The +current product foundation can identify and reopen a Scient project folder, and +the inherited host can persist application projects, threads, messages, and +provider sessions. It does not yet own a canonical source-to-task-to-proposal- +to-decision history. + +Project-local SQLite is attractive because it can provide atomic transactions, +constraints, migrations, indexed history, and non-Git recovery in one embedded +file. It also creates serious questions about cloud-synchronized folders, +active-copy safety, binary Git behavior, multi-device collaboration, readable +exports, backup, schema evolution, corruption response, and the relationship +between project files, database rows, CRDT history, object storage, and a future +cloud mirror. + +The immediate decision is therefore not "use SQLite." The immediate work is to +agree on requirements, compare credible storage models, run a disposable +persistence evaluation against real failure modes, and only then produce an +architecture decision for Yaacov to accept or reject. + +## Why This Decision Exists + +The first scientific workflow eventually needs to preserve relationships such +as: + +```text +exact source revision + -> bounded task revision + -> immutable context receipt + -> run and proposal revision + -> researcher decision + -> accepted scientific record + -> recovery history +``` + +If those relationships live only in application state, deleting or moving the +application may detach a project from its accepted scientific history. If they +live only in an agent transcript, deleting or replacing the provider may do the +same. If they rely only on Git, non-Git researchers cannot receive the promised +recovery behavior. + +The storage choice matters before that workflow is implemented because it will +shape record identity, atomicity, revision semantics, recovery, UI queries, +agent tool contracts, export, backup, sync, migration, and support. Choosing too +early risks freezing an unproven topology; choosing after production records +exist creates a costly and risky migration. + +## Relationship To The T3 Code Work + +The bounded T3 Code review is a separate lane. It produced small reliability +improvements for image parsing, literal Git paths, AppImage child environments, +snapshot/live-event characterization, and browser native-pipe isolation. Those +changes do not require or select a Scient project database. + +T3 supplied implementation evidence and comparison points for desktop runtime +boundaries. It did not supply Scient's scientific record model. This persistence +question comes from Scient's own researcher-ownership, provenance, review, and +non-Git recovery requirements. T3 completion must not be blocked by this later +decision. + +## Explicit User Direction At This Checkpoint + +Yaacov provided the following direction on 2026-07-18: + +Approved requirements: + +- recovery must work without Git; +- project filesystem scope must be enforced at a trusted Scient boundary rather + than delegated to prompt wording or an unrestricted shell; and +- native Scient runtime state must remain completely independent from the + user's external OpenCode installation. + +Deferred: + +- deterministic fake-executor implementation and its controlled product test + will be discussed later. + +Open for later review: + +- the permanent code/package seam for ongoing scientific project operations; +- the canonical storage representation and location; +- whether project-local SQLite is suitable; +- the exact portability, backup, sync, and collaboration model; and +- the implementation sequence that depends on those choices. + +## Current Implemented State + +### Portable project initialization + +The permanent `@scientfactory/project-init` package can inspect, plan, +initialize, recover, and roll back project-folder setup. It creates or preserves +`PROJECT.md`, `AGENTS.md`, and `.scient/project.json`. That JSON file provides a +path-independent project identity. The package intentionally has no SQLite, +agent, React, Electron, or inherited Synara dependency. + +It does not currently store scientific sources, tasks, context receipts, +proposals, decisions, accepted revisions, or recovery history. + +### Host application state + +The Synara-derived desktop server places its application database at +`~/.scient/userdata/state.sqlite` in production. It stores and projects host +concerns such as project registration, workspace paths, threads, messages, +turns, approvals, provider sessions, and application activity. + +That database is valuable current implementation. It is tied to the local app +installation and must not be relabeled as canonical scientific project truth +without a separate decision. + +### Missing project-owned record boundary + +No implemented store currently proves that accepted scientific records: + +- survive deletion of host project, chat, provider, or agent state; +- move or restore with the research project; +- remain coherent after interruption during acceptance; +- recover without Git; +- export completely into a documented researcher-readable representation; or +- synchronize safely across devices or collaborators. + +## Required Outcomes Before Selecting A Technology + +These are candidate requirements for review. They must be accepted, revised, or +rejected independently of any database library. + +### Ownership and authority + +1. Scient-owned scientific records remain authoritative independently of chat, + provider, executor, or host UI projections. +2. Deleting or rebuilding app-level state cannot silently delete accepted + project truth. +3. Provider transcripts and tool logs may be evidence, but are not the only + reconstruction path for accepted records. +4. Secrets, provider credentials, authentication tokens, and unrelated user + settings never enter the project-owned scientific store. + +### Integrity and recovery + +5. Accept, reject, revise, and recover operations have explicit atomicity or an + equivalently proven repair protocol. +6. A crash or forced termination at every durable-write boundary cannot produce + a falsely accepted or partially advanced scientific record. +7. Recovery appends an auditable action; it does not erase prior decisions. +8. Corruption, incompatible schema, or failed migration becomes an explicit + safe state and never triggers silent destructive repair. +9. Backup and restore reproduce IDs, relationships, accepted pointers, and + decision history exactly. + +### Portability and researcher control + +10. Moving or renaming a complete local project preserves its identity and + record history. +11. The supported transfer unit is explicitly defined: folder copy, backup + bundle, export/import, Git clone, cloud mirror, or another mechanism. +12. Researchers can export all canonical records and relationships in a + documented, readable, non-proprietary representation. +13. Scient can explain which files or stores must be copied and whether the app + must be closed first. +14. Unsupported network or cloud-folder behavior is detected or documented + honestly rather than implied safe. + +### Performance and scale + +15. Project open, common reads, proposal review, acceptance, history browsing, + backup, migration, and integrity checks meet explicit budgets on realistic + projects rather than only toy fixtures. +16. Performance remains understandable as sources, revisions, tasks, runs, + proposals, decisions, figures, analyses, and manuscript links grow. +17. Startup does not require scanning or reparsing an unbounded project history + when an index or checkpoint can be validated safely. +18. Large assets remain ordinary files or object-storage content; structured + metadata does not accidentally duplicate entire PDFs, datasets, or outputs. + +### Concurrency, sync, and collaboration + +19. A second local Scient process cannot unknowingly become a conflicting + writer. +20. The design states whether concurrent readers are supported and how stale + views are refreshed. +21. The behavior of active databases or ledgers inside iCloud Drive, Dropbox, + OneDrive, network filesystems, backup tools, and file-level sync is tested or + explicitly unsupported. +22. Multi-device and multi-user writes are not claimed solved by a single local + file format. +23. A future cloud mirror has a defined authority and conflict relationship to + local project truth before bidirectional sync is selected. +24. Structured state, document/CRDT history, large-file revisions, and Git + artifacts can eventually participate in one inspectable project timeline + and restore story. + +### Maintainability and support + +25. Schema and format versions are explicit and migrations are deterministic, + tested, resumable or safely restartable, and backed up before destructive + steps. +26. The chosen library and native dependencies package reliably on supported + macOS, Windows, and Linux targets. +27. Integrity inspection, backup, export, recovery, and support diagnostics are + available without exposing sensitive content unnecessarily. +28. The design has a credible path for future schema evolution without freezing + the complete scientific object model in the first slice. + +## Candidate Storage Models + +This list is a shortlist for investigation, not a verdict. + +### Candidate A: project-local SQLite as canonical structured state + +Example shape: + +```text +project/ + .scient/ + project.json + project.sqlite +``` + +Potential strengths: + +- mature atomic transactions and crash recovery; +- foreign keys, uniqueness, checks, and indexed queries; +- explicit migrations and integrity checks; +- one embedded structured store with no server process; and +- strong local query performance at likely first-slice scale. + +Questions and risks: + +- active WAL and shared-memory side files complicate naive copying or file-level + cloud sync; +- a binary database is not human-readable or meaningfully Git-mergeable; +- branch, clone, backup, and folder-transfer semantics need an explicit policy; +- multi-device writes and cloud collaboration require more than SQLite itself; +- corruption, migration, locking, checkpoint, and backup UX become product + responsibilities; and +- a per-project SQLite-to-single-cloud-database topology is already identified + as a deep unproven sync assumption. + +Primary SQLite references for the review: + +- SQLite documents atomic commit and rollback behavior in + [Atomic Commit In SQLite](https://www.sqlite.org/atomiccommit.html). +- The [Write-Ahead Logging](https://www.sqlite.org/wal.html) documentation + explains the single-writer model, checkpointing, additional `-wal` and + `-shm` files, and the limitation that all WAL processes must be on the same + host. +- [WAL-mode File Format](https://www.sqlite.org/walformat.html) describes the + persistent database, WAL, and shared-memory files that copy, backup, and + recovery procedures must account for. +- [SQLite Backup API](https://www.sqlite.org/backup.html) describes consistent + live snapshots and the separate `VACUUM INTO` snapshot option. +- [`PRAGMA integrity_check`](https://www.sqlite.org/pragma.html#pragma_integrity_check) + documents one integrity diagnostic, while also making clear that foreign-key + errors require a separate check. + +These references support SQLite-specific test design. They do not establish +that SQLite is the right product architecture or that a naive folder copy or +file-level synchronization protocol is safe. + +### Candidate B: append-only structured project files + +Example shapes include one immutable JSON record per event/revision, a segmented +JSONL log, or content-addressed records plus explicit pointers. + +Potential strengths: + +- inspectable with ordinary tools; +- potentially easier to copy, archive, diff, and include in Git; and +- canonical records naturally live in the project folder. + +Questions and risks: + +- cross-record atomicity, pointer updates, locking, compaction, and crash repair + become custom protocols; +- high record counts may require a derived index; +- partial file sync, rename semantics, duplicate events, and conflicting writers + still need explicit handling; +- migrations may become many-file rewrites or layered readers; and +- "human-readable" files can still be too numerous or relationally complex for + meaningful manual inspection. + +### Candidate C: append-only canonical files plus a derived SQLite index + +The project files would own durable events or records; SQLite would be a +rebuildable local index or materialized view. + +Potential strengths: + +- combines inspectable canonical records with efficient local queries; +- deleting the index would not delete project truth; and +- Git/copy/export behavior may be clearer than a canonical binary database. + +Questions and risks: + +- introduces two representations whose derivation must be deterministic; +- replay, checkpoints, invalidation, and index rebuild time require proof; +- atomic acceptance spanning canonical files and current pointers is still a + custom protocol; and +- sync conflicts in canonical event files remain unresolved. + +### Candidate D: app-local canonical database with explicit portable bundles + +Canonical structured state would remain under `~/.scient`; project export or +backup would create a portable, self-contained bundle. + +Potential strengths: + +- follows a conventional application-state model; +- avoids active database files inside ordinary project folders; and +- can make locking, migration, and local performance operationally simpler. + +Questions and risks: + +- the project folder alone is incomplete; +- move, reinstall, and cross-device behavior depend on users understanding + export/import; +- deletion of app state becomes a higher-consequence event; +- background backups must be reliable and discoverable; and +- it may conflict with the product promise that the researcher owns the local + project rather than an opaque app library. + +### Candidate E: another embedded store or bundle format + +Other embedded databases, archive formats, or content-addressed designs may be +proposed by reviewers. A new candidate should be evaluated against the same +requirements rather than added because of library familiarity. + +## Questions For SQLite Reviewers + +A reviewer assessing project-local SQLite should answer at least these +questions and cite implementation evidence or primary documentation where +possible. + +### Reliability + +1. Which journal mode is appropriate for a portable desktop project, and why? +2. What exactly happens if the process is terminated during each acceptance, + migration, backup, or checkpoint phase? +3. How will Scient distinguish recoverable interruption from corruption? +4. Which SQLite integrity checks run automatically, manually, and before backup + or migration? +5. What is the repair policy, and which failures must remain read-only pending + user action? +6. How are disk-full, read-only filesystem, permission, antivirus, and sudden + device-removal failures surfaced? + +### Copy, backup, and restore + +7. Can the whole project be copied safely while Scient is open? If not, how is + that prevented or explained? +8. Will Scient use the SQLite backup API, `VACUUM INTO`, a closed-file copy, or + another snapshot protocol? +9. How are WAL and shared-memory files handled during close, backup, restore, + crash, and manual folder copying? +10. How is a backup verified before it is declared usable? +11. Can restore be tested into a different path and machine without mutating the + original project? +12. What retention and user-visible recovery points are required? + +### Filesystems and synchronization + +13. Which local, removable, network, and cloud-synchronized filesystems are + supported on macOS, Windows, and Linux? +14. What happens when iCloud, Dropbox, or OneDrive copies an active SQLite file + and its transient companions independently? +15. Can Scient detect known-unsafe locations or simultaneous file-level sync? +16. Is file-level sync prohibited in favor of an application-level sync or + export protocol? +17. What is the behavior after an offline divergent copy returns? + +### Git and developer workflows + +18. Is the project database committed, ignored, exported, or represented by a + separate portable form? +19. What happens across branch switches, worktrees, rebases, and clones? +20. If the database is not Git-tracked, how does a Git clone receive canonical + scientific history? +21. If it is tracked, how are binary merge conflicts prevented or resolved? + +### Concurrency and collaboration + +22. What locking proves that only one writer owns a project? +23. Can multiple readers or processes safely inspect it? +24. How are stale locks distinguished from a live owner after a crash? +25. How would local IDs, mutations, attribution, and conflicts map to a future + cloud/Postgres mirror? +26. Does one database per project fit the likely cloud security and row-level + access-control topology? +27. Which collaboration promises are deliberately deferred? + +### Performance and capacity + +28. What are realistic small, medium, and stress project sizes? +29. What budgets apply to open, common query, acceptance, history, migration, + backup, export, and integrity check? +30. How do indexes, WAL growth, checkpoints, vacuuming, and long-running readers + behave under those sizes? +31. What disk amplification results from revisions, backups, exports, and + content hashes? +32. Can the app remain responsive while maintenance operations run? + +### Schema and maintainability + +33. Which layer owns SQL, migrations, transactions, IDs, and invariants? +34. Should Scient reuse Effect SQL, introduce a query builder, or keep a narrow + owned repository layer? +35. How is the complete schema versioned and inspected for support? +36. How are forward-incompatible projects handled by older app versions? +37. Can migrations be retried safely, and how is rollback handled when they + cannot? +38. How do we avoid freezing the complete future project graph in the first + schema? + +### Transparency and researcher experience + +39. What readable export contains every canonical record, ID, relationship, + decision, and accepted pointer? +40. Can an export be validated and re-imported into an empty installation? +41. How does the UI explain backup health, migration, read-only mode, + corruption, conflicting writers, and recovery without database jargon? +42. What diagnostics can a researcher safely share with support? +43. Can a researcher leave Scient without losing access to their record history? + +## Questions For Every Candidate + +The decision must also answer technology-neutral questions: + +- What is the canonical unit: project, record, event, file, bundle, or database? +- Which identifiers survive move, copy, export, restore, and cloud mirror? +- Which operation constitutes acceptance, and what exact failure states exist? +- Which data is immutable, append-only, mutable, derived, cached, or external? +- How are ordinary files and structured records linked without duplicating or + silently detaching them? +- How is one complete project timeline reconstructed across structured records, + documents, files, Git artifacts, agent evidence, and later cloud state? +- What does "portable" mean for folder copy, Git clone, backup, export, and a + second device? +- What is the smallest implementation that proves the first source-to-note + workflow without pretending to solve full collaboration? +- What evidence would cause us to reject the candidate? +- What is the migration path if the candidate later proves unsuitable? + +## Proposed Evaluation Protocol + +The evaluation must be disposable and must not become production code by +accident. It does not need a real model, native Scient agent, or the user's live +research project. + +### Shared minimal record model + +Each candidate implements only enough to exercise: + +1. create and reopen a project identity; +2. append a source revision and exact excerpt digest; +3. append a task and immutable context receipt; +4. append a proposal revision; +5. accept or reject it while preserving the previous accepted state; +6. append a recovery action; +7. export every record and relationship; +8. close, move, reopen, back up, restore, and verify the project; and +9. detect a conflicting writer and an incompatible schema. + +The executor output is fixed test input. This is a persistence evaluation, not +the deferred fake-executor product implementation. + +### Failure matrix + +Inject interruption or failure: + +- before any durable write; +- after each record write or pointer update; +- before and after commit or equivalent publish step; +- during migration; +- during backup and restore; +- with disk-full and read-only paths; +- with a killed process and stale lock; +- with missing, truncated, duplicated, or modified records; +- while a second process attempts to write; and +- during a representative copy or synchronization operation. + +After every case, verify whether the project is unchanged, fully advanced, or +explicitly read-only/recoverable. No case may produce silently inconsistent +accepted truth. + +### Scale and performance matrix + +Define realistic small, medium, and stress fixtures before measurement. Record: + +- cold and warm open time; +- common source/task/proposal/history query latency; +- acceptance and recovery latency; +- export, backup, integrity-check, and migration duration; +- memory and disk use; +- database, log, index, and backup growth; and +- UI responsiveness during maintenance work. + +Do not accept a candidate using only tiny synthetic records. Do not set final +budgets after seeing results; proposed budgets must be reviewed before the +comparison run. + +### Portability matrix + +Verify at least: + +- folder rename and move on one filesystem; +- move to a different local volume; +- backup and restore into a different path; +- reopen on another supported operating system where practical; +- Git repository and non-Git folder behavior; +- active and closed copy behavior; +- representative cloud-synchronized folder behavior; and +- explicit rejection or warning for unsupported locations. + +## Decision Gates + +### Gate 1: requirements review + +Yaacov reviews the required outcomes, scope, and deliberately deferred +collaboration claims. No storage technology is selected. + +### Gate 2: candidate and test-plan review + +Reviewers confirm that the candidate list and failure, scale, portability, +backup, export, migration, and concurrency tests are sufficient and fair. + +### Gate 3: evidence run + +Run the disposable evaluation and preserve reproducible commands, fixtures, +results, limitations, and failures. Narrow unit tests do not substitute for real +persistence, copy, process, and filesystem behavior. + +### Gate 4: proposed architecture decision + +Write an ADR that states the selected model, rejected alternatives, evidence, +constraints, migration/exit path, unsupported behavior, and remaining risks. +Its status remains Proposed until Yaacov accepts it. + +### Gate 5: implementation authorization + +Only after acceptance should production schema, package APIs, migration paths, +project UI, or agent tools depend on the selected persistence model. + +## Reviewer Assignment + +A reviewer can use this document without reading the complete repository first. +They should receive: + +- this brief; +- the accepted [PRD](../product/PRD.md), especially local ownership, + inspectable history, review, and recovery; +- the [technology stack](technology-stack.md), while honoring its proposed + status; +- the existing [coherence report](../research/spike-reports/coherence-report-2026-06-28.md), + especially findings A1 and A5; +- the [testing philosophy](../quality/testing-philosophy.md); +- the [first-slice source trace](../../lab/notes/first-slice-source-trace-2026-07-18.md); + and +- the placeholder [project format](project-format.md) and + [local-first sync](local-first-sync.md) homes. + +Ask the reviewer to return: + +1. corrected or missing requirements; +2. a critique of every candidate, not only SQLite; +3. any additional candidate worth testing; +4. the minimum fair evaluation implementation; +5. required failure, scale, filesystem, backup, migration, and export tests; +6. primary-source evidence for external technology claims; +7. explicit reasons to reject project-local SQLite; +8. explicit reasons to reject file-based or app-local alternatives; +9. risks that belong in product scope rather than implementation; and +10. a recommendation about what Yaacov must decide before any code begins. + +## Non-Goals + +This brief does not: + +- select SQLite or another store; +- define production tables or the complete scientific object graph; +- authorize `packages/scient-project` or another permanent package seam; +- implement the deferred fake executor; +- implement sync, collaboration, cloud Postgres, CRDTs, object storage, or a web + client; +- claim active cloud-folder copying is safe; +- make T3 Code a product architecture dependency; or +- block completion of the bounded T3 reliability work. + +## Current Verdict + +Document and evaluate; do not implement yet. + +The product need for durable, app-independent, non-Git-recoverable scientific +records is credible. Project-local SQLite remains a strong candidate, but its +reliability, portability, usability, Git, sync, collaboration, backup, and +migration consequences require explicit evidence and human review before it can +become Scient architecture. diff --git a/docs/architecture/technology-stack.md b/docs/architecture/technology-stack.md index 93e0573..aecf2fd 100644 --- a/docs/architecture/technology-stack.md +++ b/docs/architecture/technology-stack.md @@ -62,11 +62,11 @@ Scient app from the planned Scient agent where needed. | Local coordinator | Bun/Node.js WebSocket server | Inherited scaffold candidate; not yet a Scient decision | | Workspace tooling | Bun workspaces, Turborepo, Vite | Inherited scaffold candidate; not yet a Scient decision | | Cloud web app | React, with Next.js as a later candidate | Not scaffolded | -| Local database | SQLite | Proposed; inherited scaffold uses it for app/session projections, not Scient project truth | +| Local structured state | SQLite for inherited app/session projections; canonical Scient project store undecided | App SQLite implemented; project persistence under later review | | Cloud database | Postgres | Proposed; not scaffolded | | Cloud platform | Supabase | Initial default candidate; not scaffolded | | Large file storage | Object storage | Proposed; not scaffolded | -| Sync | Local-first SQLite-to-cloud sync | Under evaluation; not scaffolded | +| Sync | Local-first project-state-to-cloud sync | Under evaluation; storage and sync engines not selected or scaffolded | | Application foundation | Standalone Scient-owned, Synara-derived source | Accepted initial foundation through ADR-0001; ownership authority through ADR-0002; scientific product fit remains unproven | | External-agent layer | Synara provider contracts and service | Inherited machinery for external agents; preservation required, project-task compatibility not yet certified | | First-party agent | Scient, derived from standalone Scient-owned, OpenCode-derived source | Accepted identity and source foundation through ADR-0001; ownership authority through ADR-0002; Scient product/runtime not yet implemented | @@ -166,9 +166,9 @@ The current lab scaffold has this upstream shape: That tree remains foreign source and should not become the Scient package map by accident. Source-tracing notes and disposable adapter experiments may use -`lab/scient-bridge/`. The first vertical-slice implementation belongs in the -permanent location selected from source evidence during the implementation -plan; do not treat the lab as its default code home. +`lab/scient-bridge/`. The first vertical-slice implementation belongs in a +permanent location to be selected from source evidence and the deferred +persistence review; do not treat the lab as its default code home. Possible later Scient-owned package areas include: @@ -197,7 +197,11 @@ where practical. Use Electron for the first desktop experiment. The inherited Synara scaffold already provides the Electron shell. -Electron is the pragmatic first choice because Scient needs React, local files, SQLite, subprocesses, agent CLIs, and local background services. These are all easier to integrate in Electron than in a stricter native shell during the first product build. +Electron is the pragmatic first choice because Scient needs React, local files, +embedded structured storage, subprocesses, agent CLIs, and local background +services. These are all easier to integrate in Electron than in a stricter +native shell during the first product build. This shell choice does not select +the canonical project-storage technology. The immediate validation question is whether the Synara-derived shell can host a Scient-owned project mode without forcing scientific work into coding @@ -223,24 +227,33 @@ cloud/project model, not a separate product with separate semantics. ## Local Data -Use SQLite locally. +Use the inherited SQLite boundary for current global app, session, +orchestration, and projection state. Do not infer from that implementation that +SQLite is selected for canonical Scient project records. The inherited scaffold already uses SQLite for Synara app, session, orchestration, and projection state. That database must not be relabeled as the Scient scientific project database. Scient-owned project persistence has not -been designed or implemented. +been selected, designed, or implemented. The open requirements, candidates, +risks, questions, and evidence gates live in the +[Scient Project Persistence Decision Brief](scient-project-persistence-decision-brief.md). Scient should distinguish: - global app state, such as recent projects, local settings, device identity, and local caches -- per-project scientific state, such as papers, protocol records, evidence records, extraction records, manuscript state, agent runs, and sync metadata +- project-owned scientific state, such as sources, protocol records, evidence records, extraction records, manuscript state, agent runs, and sync metadata -The per-project database is the more important architectural object because projects must be portable and recoverable. +The project-owned scientific record boundary is the more important +architectural object because projects must be portable and recoverable. Its +representation may be a project-local database, append-only structured files, a +canonical-file/derived-index hybrid, an app-local store with explicit portable +bundles, or another reviewed model. The inherited scaffold uses Effect SQL with SQLite through Bun. Do not replace -that layer merely to satisfy the target stack before the scaffold baseline is -known. For Scient-owned project persistence, evaluate Effect SQL, Drizzle, -Kysely, or a narrower owned layer after the first project-state contract exists. +that layer merely to satisfy a candidate target stack. If project persistence +later selects SQLite, evaluate Effect SQL, Drizzle, Kysely, or a narrower owned +layer only after the project-state contract and persistence evidence are +reviewed. ## Cloud Data @@ -270,23 +283,31 @@ Large binary assets should not be stored directly in Postgres. ## Sync -Use local-first sync between local SQLite/project state and the cloud collaboration plane. +The product direction requires local-first sync between project-owned state and +the future cloud collaboration plane. The local representation, cloud authority +model, and exact sync engine are not selected. The exact sync engine is not yet selected. Current candidates: -- PowerSync for SQLite-to-Postgres local-first sync +- PowerSync if a compatible SQLite-to-Postgres topology is proven - Electric for Postgres-backed read sync and live web/cloud views - a Scient-owned sync layer if vendor tools do not fit the required project model -Convex is not selected as the primary database or local-first sync foundation. It may be evaluated for collaboration features or realtime cloud workflows, but the current stack direction requires portable local project state backed by SQLite. +Convex is not selected as the primary database or local-first sync foundation. +It may be evaluated for collaboration features or realtime cloud workflows, but +no candidate may override the requirements for researcher-owned, portable, +recoverable local project state. Scient should maintain domain-level mutation and audit semantics so the product is not locked to one sync vendor. ## Collaboration -Use database sync for structured scientific state. +Use an explicit structured-state synchronization protocol for structured +scientific state once the canonical local representation and cloud authority +model are accepted. Do not assume file-level sync, database sync, or one vendor +before that decision. Use CRDTs only for document-like collaborative surfaces where simultaneous text editing matters. @@ -457,7 +478,7 @@ Completed historical experiments remain evidence, not the roadmap. | Synara-derived application | Standalone owned source, build, isolated Scient identity and state, reviewed upstream process | Scientific-product fit, sustainable domain UI divergence, and long-term maintenance cost | Gate 1 and Gate 1.5 lab reports; ADR-0001 owns adoption; ADR-0002 owns repository authority | | Scient source foundation | Owned OpenCode build, Synara compatibility, project-root fidelity, transcript fidelity, and approval flow for a constrained action | Scient identity and packaging, owned capabilities, isolated Scient state, durable task behavior, and justified inherited-core changes | Gate 1.5 report proves the source baseline; ADR-0001 owns Scient adoption | | External agents | Nine inherited adapters and external OpenCode settings/adapter paths are present in source | Per-agent live compatibility, subscription/auth behavior, project-task certification, and migration protection | [Scient and external agents implementation plan](../planning/scient-and-external-agents-implementation-plan.md) | -| Scient project state | Product responsibilities and trust boundary are documented | Persistence, portable local record, recovery, and first real scientific object relationship | First vertical-slice plan | +| Scient project state | Product responsibilities, approved non-Git recovery requirement, and trust boundary are documented | Canonical representation, package seam, reliability, portability, performance, backup, export, sync, and first real scientific object relationship | [Persistence decision brief](scient-project-persistence-decision-brief.md) and first vertical-slice plan | | Scient-agent and Scient-app boundary | Scient-agent identity plus context, proposal, review, provenance, and permission responsibilities are documented | Actual contract, code placement, event mapping, isolated Scient-agent state, and accepted write-back path | ADR-0001 and linked implementation plans; `agent-runtime.md` remains a future home | | Goose | Source seams, ACP path, and safety risks inspected | Incremental capabilities or architecture lessons for Scient; any future external Goose path is a separate decision | Goose source-depth inspection | | Cloud sync | Postgres, object storage, and local-first sync are proposed directions | Authority, offline behavior, conflicts, revocation, and recovery | Later roadmap and focused architecture work | @@ -474,7 +495,7 @@ The proposed and accepted-by-ADR foundation direction is: TypeScript React Electron -SQLite +SQLite for inherited app state; canonical project persistence undecided Postgres Supabase as initial cloud platform candidate object storage diff --git a/docs/planning/first-scient-vertical-slice-implementation-plan.md b/docs/planning/first-scient-vertical-slice-implementation-plan.md index 5595a46..6d93c58 100644 --- a/docs/planning/first-scient-vertical-slice-implementation-plan.md +++ b/docs/planning/first-scient-vertical-slice-implementation-plan.md @@ -55,9 +55,16 @@ at `57e6b2cde09f64db367b894506f56db605fb91b4`. They initialize only the portable foundation and do not make the host project projection canonical. Phase 2 source tracing is complete in -`../../lab/notes/first-slice-source-trace-2026-07-18.md` and awaits the required -Yaacov review checkpoint. The proposed decision is a permanent Scient project -domain/persistence package with thin host shims and a narrow executor port. +`../../lab/notes/first-slice-source-trace-2026-07-18.md`. It proved the current +state-ownership gaps and candidate seams, but Yaacov deferred the permanent +package, persistence technology, and fake-executor decisions for later review. +The open storage question now has a standalone reviewer brief at +`../architecture/scient-project-persistence-decision-brief.md`. Non-Git +recovery, trusted project filesystem scope, and complete native-Scient/external- +OpenCode runtime independence are approved requirements; they are not yet +fully implemented for ongoing scientific operations. The existing project-init +kernel already enforces path containment for initialization; the later +scientific-operation and native-agent boundaries remain to be built. The selected OpenCode-derived source is `bc125cbc60c36e4b7013f8d7cf755f745af509b3` on `dev`, but the native agent is not yet implemented or packaged. No scientific-state store, Scient agent gateway, proposal/decision ledger, or @@ -381,7 +388,7 @@ Do not design the full project graph or package map. Decide only the first home for project identity, source excerpt, evidence note, task/context, run/proposal/ decision, and recovery responsibilities. -### 3. Produce The Trace Decision +### 3. Produce The Trace And Decision Boundary Create one dated evidence note at: @@ -396,12 +403,14 @@ It must record: 5. the completed state-ownership table; 6. non-Git behavior and recovery findings; 7. the proposed filesystem-scope enforcement boundary; -8. candidate seam comparison and selected permanent placement; +8. candidate seam comparison and either a selected permanent placement or an + explicit owner-approved deferral; 9. existing machinery to reuse unchanged; 10. surfaces Scient must not couple to; 11. any required Synara change, the Scient integration seam, and any proven inherited OpenCode-core gap; -12. the exact first coding backlog; and +12. the exact first coding backlog or the evidence/decision sequence required + before such a backlog is safe; and 13. a go/no-go verdict for implementation. Update this plan only where the trace resolves an open boundary. Update @@ -410,17 +419,25 @@ roadmap or ADR unless the trace invalidates them. ### 4. Review Checkpoint -Stop for Yaacov's review before product code begins. The review should decide -only whether the selected permanent boundary is understandable, serves both -manual and agent work, keeps scientific state outside inherited sessions, -supports credible non-Git recovery, defines enforceable project filesystem -scope, and produces a sufficiently narrow coding backlog. +The first review established three requirements: non-Git recovery, trusted +project filesystem scope, and complete native-Scient/external-OpenCode runtime +independence. Yaacov deferred the permanent package, persistence representation, +portability/sync model, and deterministic fake-executor product proof. -Once accepted, begin implementation. Do not add another exploratory phase -unless the trace identifies a real blocker. +The review exposed an open architecture decision: the reliability, performance, +usability, backup, migration, Git, cloud-folder, concurrency, and future-sync +consequences of canonical project persistence are unproven. Yaacov chose to +document and defer that decision rather than select or implement SQLite now. Use +`../architecture/scient-project-persistence-decision-brief.md` for requirements, +candidate, evidence, and ADR gates. Do not begin scientific-state product code +until that later review produces explicit authorization. ## Phase 3: Permanent Walking Skeleton +Status: Deferred. The ordered work below remains a candidate sequence, not +current authorization. Replan it after the persistence decision and the later +fake-executor discussion. + Implement in this order: 1. **Manual project lifecycle integration.** Connect the reviewed initiation @@ -572,12 +589,12 @@ Stop and report before widening scope if: - five-path map; - completed state-ownership table; - explicit non-Git recovery approach; -- selected permanent code location; +- permanent code-location candidates and explicit owner deferral; - reuse-versus-change list; - Scient integration and inherited OpenCode-core change verdict; - Synara-hosted versus external-topology verdict; -- narrow first coding backlog; and -- Yaacov's approval to implement. +- deferred decision/evidence sequence; and +- an explicit no-go on scientific-state implementation until later review. ### Vertical Slice Done diff --git a/lab/notes/README.md b/lab/notes/README.md index 8dbfed5..1402d3a 100644 --- a/lab/notes/README.md +++ b/lab/notes/README.md @@ -20,7 +20,7 @@ integration observations, and temporary lab decisions. - `synara-gate-1-baseline-2026-07-11.md` - historical inherited-scaffold baseline, official-CLI correction run, and Gate 1 pass result. - `synara-first-inspection-2026-07-07.md` - first source inspection of Synara as desktop base, OpenCode first-agent path, Goose integration path, and Scient ownership boundary. - `goose-source-depth-inspection-2026-07-11.md` - research input for Goose's later role, ACP surfaces, runtime-state boundary, permission risks, and first adapter recommendation. -- `first-slice-source-trace-2026-07-18.md` - exact desktop/agent path trace and proposed permanent boundary for the first scientific source-to-note slice, awaiting the required user review checkpoint. +- `first-slice-source-trace-2026-07-18.md` - exact desktop/agent path trace for the first scientific source-to-note slice; persistence and permanent package choices are explicitly deferred to the reviewer brief. - `t3-code-targeted-review-2026-07-18.md` - bounded T3 Code review through `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0`, including accepted reliability work and explicit deferred/rejected dispositions. Keep notes clear about whether they are: diff --git a/lab/notes/first-slice-source-trace-2026-07-18.md b/lab/notes/first-slice-source-trace-2026-07-18.md index fe77ca1..78fc9d1 100644 --- a/lab/notes/first-slice-source-trace-2026-07-18.md +++ b/lab/notes/first-slice-source-trace-2026-07-18.md @@ -1,57 +1,62 @@ # First Scientific Slice Source Trace -Status: Complete; awaiting Yaacov review +Status: Complete as source evidence; persistence and package decisions deferred Owner: Yaacov Created: 2026-07-18 Last updated: 2026-07-18 -Purpose: Selects the permanent Scient-owned state, recovery, UI, and execution boundary for the first scientific vertical slice. +Purpose: Maps the first scientific slice's current source seams, proven gaps, and decision requirements without selecting a persistence technology or authorizing product implementation. Doc type: Implementation evidence ## Verdict -**Go for the permanent walking skeleton after the review checkpoint.** The -maintained Synara-derived desktop can host the slice without making its project, -thread, provider, or checkpoint projections canonical scientific state. +**Do not implement the permanent scientific-state skeleton yet.** The maintained +Synara-derived desktop can host the slice without making its project, thread, +provider, or checkpoint projections canonical scientific state, but the +permanent package seam and persistence model remain open for later review. -Use a hybrid placement: +A hybrid placement remains a leading candidate, not an accepted design: -1. a permanent `packages/scient-project` package in `scient-desktop` owns the +1. a possible `packages/scient-project` package in `scient-desktop` owns the first-slice domain rules, project-local persistence, proposal decisions, recovery, and filesystem-scope policy; 2. thin contracts, trusted-server RPC, and project-level UI shims call that package; and 3. a narrow executor port accepts immutable task/context receipts and returns a - proposal. A deterministic fake implements that port first. Scient later - implements it as a distinct execution target; external OpenCode remains an - independent adapter. - -Canonical accepted state belongs in the project folder, with `.scient/project.json` -as portable identity and `.scient/project.sqlite` as the first-slice record and -revision ledger. Synara's `~/.scient/userdata/state.sqlite`, provider sessions, -chat transcripts, and Git checkpoint refs remain host state or execution -evidence only. - -The existing Git-backed checkpoint mechanism is not suitable for the required -non-Git guarantee. For the first slice, proposal acceptance should be one SQLite -transaction that creates a recovery point referring to the prior accepted -revisions, appends the decision, and advances the accepted record pointers. -Revert creates new accepted revisions; it does not rewrite history. No Git -repository, worktree, executor session, or transcript is required to reopen or -recover the accepted source-to-note relationship. - -One required native-agent gap is now proven: the selected `scient-agent` source -still defaults its global data/config/state roots and database name to -`opencode`. Native Scient packaging must supply a dedicated first-party runtime -profile before it can be connected. That change must not alter the existing -external OpenCode adapter or its user-owned data paths. + proposal. Deterministic fake-executor implementation is deferred for later + discussion. Scient would eventually implement the port as a distinct + execution target; external OpenCode remains an independent adapter. + +The requirement under review is that canonical accepted state remain +independent of Synara's `~/.scient/userdata/state.sqlite`, provider sessions, +chat transcripts, and Git checkpoint refs. `.scient/project.json` already owns +portable identity. The location and representation of ongoing scientific +records are not selected. Project-local SQLite, append-only structured files, a +hybrid canonical-log/index design, and an app-local store with explicit portable +bundles require evidence-based comparison in +[`scient-project-persistence-decision-brief.md`](../../docs/architecture/scient-project-persistence-decision-brief.md). + +The existing Git-backed checkpoint mechanism is not suitable for the approved +non-Git guarantee. A future persistence design must prove that acceptance is +atomic or equivalently recoverable, records the prior accepted state, appends +the decision, and advances accepted state without rewriting history. No Git +repository, worktree, executor session, or transcript may be the only way to +reopen or recover the accepted source-to-note relationship. The mechanism is +open. + +One required and user-approved native-agent gap is now proven: the selected +`scient-agent` source still defaults its global data/config/state roots and +database name to `opencode`. Native Scient packaging must supply a dedicated +first-party runtime profile before it can be connected. That change must not +alter the existing external OpenCode adapter or its user-owned data paths. ## Controlled Fixture -Use a deterministic synthetic capsule for the first implementation PR. This is -the safer first fixture because no public capsule with compatible excerpt, -dataset, figure, and redistribution rights has yet been validated as one -self-contained unit. Replacing the fixture later with an openly licensed study -does not change the selected architecture. +The deterministic synthetic capsule below remains a candidate for a later +controlled persistence or executor test. Yaacov deferred fake-executor product +implementation and is separately preparing a real project for later manual +testing. The controlled fixture would protect the real project from destructive +crash, corruption, migration, and recovery experiments; it is not authorized by +this trace. The capsule is `greenhouse-seedling-capsule` and lives outside every parent Git repository during runtime tests. Its committed test fixture will contain: @@ -109,12 +114,13 @@ platform user-data profile resolved by ### Scient attachment point -After the host resolves a workspace root, the trusted server should inspect -`.scient/project.json` and open `.scient/project.sqlite` through the new package. -The project-level UI is keyed by the portable Scient project ID, while the -Synara project ID remains a replaceable host reference. Moving the whole folder -preserves Scient identity and history; reopening from a new path may create or -recover a different host project row without changing canonical records. +After the host resolves a workspace root, a future trusted server boundary +should inspect `.scient/project.json` and open the selected project-owned record +boundary through the approved package or service seam. The project-level UI +should be keyed by the portable Scient project ID, while the Synara project ID +remains a replaceable host reference. The persistence review must define what +must move, copy, export, or restore for history to remain portable; this trace +does not assume that a folder copy is sufficient. Failure to open the canonical store must not silently fall back to chat state. It should show an explicit unavailable/migration/recovery state and leave the @@ -123,7 +129,7 @@ project files untouched until the user chooses a safe action. ## Path B: Manual Operations And Minimal UI The current product has the necessary shell but no canonical scientific -operations. The smallest placement is a new project-level route and component, +operations. A candidate UI placement is a new project-level route and component, not another chat-thread projection: - add `_chat.project.$projectId.tsx` as the thin route shim; @@ -135,8 +141,9 @@ not another chat-thread projection: - use a small structured before/proposed-note review card. Do not force the note through Git/file diff machinery merely to reuse `DiffPanel`. -Both UI actions and executor output call the same package commands through the -trusted server: +Both UI actions and later executor output must call the same Scient-owned domain +commands through a trusted boundary. Whether that boundary is a package or +another reviewed seam remains open. - add or revise a source excerpt; - create a task and immutable context receipt; @@ -164,7 +171,7 @@ evidence, task, proposal, or decision truth for this slice. ### Execution contract -Add a Scient-owned `ScientificTaskExecutor` port whose input contains only: +A later Scient-owned `ScientificTaskExecutor` candidate would accept only: - stable execution-target ID; - Scient project ID and run ID; @@ -174,10 +181,10 @@ Add a Scient-owned `ScientificTaskExecutor` port whose input contains only: - allowed operation/capability set; and - cancellation signal. -Its output is a proposed record plus normalized run evidence. It cannot accept -scientific state and cannot write canonical tables directly. The server records -the run and proposal through package commands after validating IDs, hashes, -scope, and current revisions. +Its output would be a proposed record plus normalized run evidence. It cannot +accept scientific state and cannot write canonical records directly. The +trusted Scient boundary would record the run and proposal only after validating +IDs, hashes, scope, and current revisions. ### Filesystem scope @@ -194,10 +201,11 @@ path scanning is advisory and that the shell runs with host-user filesystem, process, and network authority. A cwd plus approval mode is therefore not an enforceable project sandbox. -For the first slice: +Approved scope requirements for a later slice are: 1. canonical operations accept only package IDs and root-relative paths; -2. the fake executor has no filesystem capability; +2. any controlled executor used for proof has no filesystem capability unless + a separately reviewed capability is required; 3. native Scient later runs with a dedicated capability profile that disables unrestricted shell/direct-write tools for this workflow and exposes only scoped Scient gateway tools; @@ -220,16 +228,18 @@ that the current OpenCode permission prompt alone enforces filesystem scope. | External OpenCode session and transcript | External OpenCode plus host adapter | External OpenCode's XDG/Application Support `opencode` data; resume/session projection in host SQLite | Provider-dependent; normally yes | No | | Runtime events and tool logs | Agent plus host ingestion | Provider-native store; normalized host events/projections; optional `~/.scient/userdata/logs/provider/events.log` | Yes where persisted | Evidence only | | Scient project identity | Existing project-init kernel | `.scient/project.json` | Yes and moves with folder | Yes | -| Source excerpt and evidence note | New Scient project package | Versioned rows in `.scient/project.sqlite` | Yes | Yes | -| Task and context receipt | New Scient project package | Versioned task and immutable context-receipt rows in `.scient/project.sqlite` | Yes | Yes | -| Run receipt, proposal, and decision | New Scient project package | Append-only run, proposal revision, and decision rows in `.scient/project.sqlite` | Yes | Yes | -| Recovery state | New Scient project package | Recovery-point and accepted-revision ledger rows in `.scient/project.sqlite`; content-addressed blobs only when later file materialization requires them | Yes | Yes | - -Project-local SQLite must use foreign keys, WAL or an equally safe journaling -mode, explicit schema versioning, deterministic migrations, busy timeouts, and -backup/recovery tests. Secrets and provider credentials never enter this file. -Large source files are out of scope; the first exact excerpt is stored as text -with a digest and local source locator. +| Source excerpt and evidence note | Missing | Project-owned representation and location undecided | Must | Must | +| Task and context receipt | Missing | Project-owned representation and location undecided | Must | Must | +| Run receipt, proposal, and decision | Missing | Project-owned representation and location undecided | Must | Must | +| Recovery state | Missing | Project-owned representation and location undecided | Must | Must | + +The persistence choice must be evaluated against reliability, atomicity, +performance, scale, backup/restore, portability, readable export, Git and cloud- +folder behavior, concurrency, migration, packaging, future sync, and an exit +path. Secrets and provider credentials must never enter project-owned scientific +state. Large source files remain out of the first structured-state experiment. +The complete open question and reviewer assignment live in the +[persistence decision brief](../../docs/architecture/scient-project-persistence-decision-brief.md). ## Path E: Proposal, Review, Non-Git Recovery, And Reopening @@ -247,44 +257,48 @@ Provider live diffs and host proposed plans are useful presentation/evidence inputs, but they remain thread/provider projections and cannot reconstruct an accepted scientific note after their session is deleted. -The first-slice proposal flow is instead: +The approved behavioral requirement for a later proposal flow is: 1. create immutable source, task, and context revisions; 2. open a run receipt before executor invocation; 3. record executor evidence and a proposal linked to exact revision IDs; 4. allow proposal text edits as new proposal revisions; -5. on accept, begin one database transaction; -6. append a recovery point containing the prior accepted revision pointers; +5. on accept, begin one atomic or equivalently recoverable publish operation; +6. append or preserve a recovery point containing the prior accepted state; 7. append the decision and accepted note revision; -8. atomically advance the accepted pointers and commit; and +8. atomically advance the accepted state and publish; and 9. on reject or failure, append the outcome without changing accepted pointers. -Reopening reads the portable project identity and canonical ledger without +Reopening must read the portable project identity and canonical record without starting an agent. Recovery creates a new decision/revision that points back to -the recovery point; audit history remains intact. Interrupted transactions roll -back through SQLite. Corruption/open failures are explicit and read-only until -backup or repair is chosen. +the recovery point; audit history remains intact. Interrupted publication must +leave the old state authoritative or the new state fully authoritative, never a +silent partial mixture. Corruption/open failures must be explicit and read-only +until a verified recovery action is chosen. -This is credible for the fixture because acceptance changes only canonical -records. Later materialized project-file changes require content-addressed -preimages or another reviewed file transaction; they must not be silently -declared covered by the first ledger. +This behavioral boundary is credible for a controlled fixture only if +acceptance changes a bounded set of canonical records atomically or through an +equivalently proven protocol. Later materialized project-file changes require +content-addressed preimages or another reviewed file transaction; they must not +be silently declared covered by the first record mechanism. ## Permanent Seam Comparison -Scores use 1 (poor) to 5 (strong). +Scores use 1 (poor) to 5 (strong). They are preliminary source-trace analysis, +not user acceptance and not a persistence-technology score. | Option | Shared manual/agent operations | Session-independent truth | Non-Git recovery | Low inherited-core change | Upstream cost | Maintainer clarity | Reversible | |---|---:|---:|---:|---:|---:|---:|---:| | One namespaced package with integration left implicit | 4 | 5 | 5 | 5 | 5 | 4 | 5 | | Isolated modules scattered across contracts/server/UI | 3 | 2 | 3 | 3 | 2 | 2 | 2 | -| **Hybrid package plus thin integration shims and executor port** | **5** | **5** | **5** | **4** | **4** | **5** | **5** | +| Hybrid package plus thin integration shims and executor port | 5 | 5 | 5 | 4 | 4 | 5 | 5 | -The hybrid is selected because the package makes ownership and portability -real, while named shims make the UI/server/executor crossings explicit and -testable. Scattered modules would let host projections become accidental truth. -A package with no explicit integration policy would still leave executor and UI -call paths ambiguous. +The hybrid remains the leading code-placement candidate because a package can +make ownership explicit while named shims make UI/server/executor crossings +testable. It is not selected. Yaacov deferred the permanent package and +persistence choice for later review. The persistence evaluation must determine +whether this placement remains appropriate once storage, migration, backup, +portability, and support obligations are understood. ## Reuse Unchanged @@ -313,21 +327,24 @@ call paths ambiguous. - unrestricted shell commands or model-generated paths; or - T3 Code, Goose, cloud, mobile, collaboration, or remote execution. -## Required Changes And Proven Gaps +## Proven Gaps And Candidate Changes -### Scient desktop +### Scient desktop candidates - not authorized -- add `packages/scient-project` with domain commands, SQLite repository, - migrations, revision/recovery ledger, and path-scope policy; +- evaluate whether `packages/scient-project` should own domain commands, + persistence-independent interfaces, revision/recovery rules, and path-scope + policy; +- select a persistence model only through the decision brief's reviewed gates; - add narrow DTO/RPC contracts and server services that resolve portable identity from the workspace root and call the package; - add one project-level route/view and sidebar entry; and -- add the executor port, deterministic fake, and later one Scient adapter. +- later evaluate the executor port, controlled deterministic adapter, and one + Scient adapter; the fake-executor product proof is deferred. No change to Synara's orchestration event schema, `projection_projects`, generic provider event schema, or Git checkpoint store is required for the fixture. -### Scient agent +### Scient agent requirement - approved, implementation later Before native connection, replace the inherited hardcoded global identity/path defaults with a build/runtime profile that gives Scient dedicated data, config, @@ -336,64 +353,54 @@ brand-neutral durable first-party ID where records persist. Keep upstream OpenCode defaults available to external OpenCode builds; never redirect or migrate the user's external OpenCode state implicitly. -Then expose a bounded Scient workflow capability that consumes the gateway -receipt and returns a proposal. The first capability profile must not provide -unrestricted shell or direct canonical writes. - -## Exact First Coding Backlog - -After Yaacov accepts this trace, implement in this order and keep each repository -change independently reviewable: - -1. **Fixture and package contract:** commit the synthetic capsule fixture and - create `@scientfactory/scient-project` with branded IDs, schemas, command - results, revision invariants, and a deterministic in-memory repository. -2. **Canonical store:** add `.scient/project.sqlite` open/create validation, - migrations, source/task/context/run/proposal/decision tables, transactional - acceptance, recovery points, reopen/move tests, busy/corrupt/interrupted - cases, and dependency audit. -3. **Trusted server boundary:** add project-root identity resolution, real-path - scope checks, package service wiring, typed RPC methods, and tests proving - host project/session deletion cannot delete canonical records. -4. **Manual project UI:** add the project-level route/view, manual excerpt and - task/context forms, proposal edit/accept/reject/history UI, explicit store - errors, and close/reopen flow. -5. **Fake executor proof:** implement `ScientificTaskExecutor` with a - deterministic fake that receives only the context receipt and returns the - expected two-sentence proposal; prove cancellation/failure leave accepted - state unchanged. -6. **End-to-end non-Git test:** run initialized -> source -> task -> proposal -> - accept -> close -> move folder -> reopen -> recover, while proving the - folder remains outside Git and no provider transcript is needed. -7. **Execution-target foundation:** add stable agent-connection/execution-target - identity above `ProviderKind`, preserve all external settings and adapters, - and test migration with Scient absent/present. -8. **Native Scient isolation:** in `scient-agent`, add the dedicated first-party - runtime profile and prove simultaneous Scient/external-OpenCode credentials, - processes, paths, sessions, and updates do not overlap. -9. **Native adapter:** connect Scient to the executor port with scoped gateway - tools, normalized evidence, cancellation, and failures; replay a sanitized - live run before the final controlled-fixture smoke. - -Do not combine steps 7-9 with the first domain/store PR. The fake proves the -scientific boundary before provider plumbing can obscure it. +After a later review, expose a bounded Scient workflow capability that consumes +the gateway receipt and returns a proposal. The first capability profile must +not provide unrestricted shell or direct canonical writes. + +## Deferred Decision And Coding Sequence + +No scientific persistence or executor code is authorized by this trace. The +next sequence is documentation and evidence first: + +1. **Requirements review:** revise and accept the technology-neutral ownership, + recovery, portability, export, performance, and collaboration requirements. +2. **Candidate review:** compare project-local SQLite, append-only structured + files, canonical files plus a derived index, app-local storage plus portable + bundles, and any reviewer-supported alternative. +3. **Disposable evidence run:** exercise real persistence, process, filesystem, + copy, backup, restore, migration, concurrency, scale, and corruption behavior + without using production code or the user's live project. +4. **Architecture decision:** propose an ADR with evidence, rejected options, + unsupported behavior, and an exit path; keep it Proposed until Yaacov accepts + it. +5. **Package and implementation plan:** only then select the permanent package + seam and rewrite the coding backlog around the accepted model. +6. **Deferred executor discussion:** decide later when and how a deterministic + executor proof and the user's real project should enter the sequence. +7. **Native Scient isolation:** preserve the approved requirement that native + Scient and external OpenCode never share credentials, processes, paths, + sessions, plugins, databases, or updates; authorize implementation separately. ## Go/No-Go Conditions -Go after review because: +Go now only for completing and publishing the independent T3 reliability work and +for documenting/reviewing persistence requirements. Do not begin scientific- +state product implementation. + +The later design may go to implementation only when evidence proves: - manual and agent paths share one command boundary; - accepted state is independent of host and provider sessions; -- non-Git recovery is transactional and testable for the fixture; +- non-Git recovery is atomic or equivalently recoverable and testable; - project scope is enforced at the canonical/gateway boundary rather than trusted to prompt wording; - external OpenCode remains unchanged; and -- the first coding backlog is bounded. +- the first coding backlog is bounded around an accepted persistence model. Stop and revisit this decision if implementation proves any of these: -- project-local SQLite cannot be opened/moved/recovered safely across supported - desktop platforms; +- no candidate can meet the reviewed reliability, portability, performance, + backup, export, migration, and concurrency requirements at acceptable cost; - accepted state requires host projection IDs or an executor transcript; - scoped gateway tools cannot prevent direct native-agent writes for the controlled workflow; @@ -403,6 +410,9 @@ Stop and revisit this decision if implementation proves any of these: ## Review Checkpoint -No product-code implementation follows from this note until Yaacov reviews the -selected hybrid boundary, `.scient/project.sqlite` ledger, non-Git recovery, -filesystem-scope rule, external OpenCode separation, and backlog above. +The source map is complete, but its former SQLite and hybrid-package selection +is withdrawn pending later review. The approved requirements are non-Git +recovery, trusted filesystem scope, and complete native-Scient/external-OpenCode +runtime independence. Fake-executor work is deferred. Use the +[Scient Project Persistence Decision Brief](../../docs/architecture/scient-project-persistence-decision-brief.md) +for the next review; do not infer implementation authorization from this note. diff --git a/lab/notes/t3-code-targeted-review-2026-07-18.md b/lab/notes/t3-code-targeted-review-2026-07-18.md index 3793ef6..7e667fd 100644 --- a/lab/notes/t3-code-targeted-review-2026-07-18.md +++ b/lab/notes/t3-code-targeted-review-2026-07-18.md @@ -93,12 +93,15 @@ When the first scientific vertical slice reaches its execution contract: - add stable agent-connection identity above it; - represent native Scient and external-agent connections as distinct execution targets; -- use one narrow executor port and a deterministic fake executor; +- later evaluate one narrow executor port; Yaacov deferred the deterministic + fake-executor product proof; - preserve existing external adapters and settings; and - keep canonical scientific state independent of every provider session store. -The first-slice boundary trace and its user review checkpoint remain the gate -before product-code implementation. +The independent T3 intake is complete and is not blocked by the later project- +persistence decision. Before scientific-state product implementation, use the +[`Scient Project Persistence Decision Brief`](../../docs/architecture/scient-project-persistence-decision-brief.md) +and the revised first-slice trace to review requirements and candidates. ## Triggered Shelf From 3fd19d41f38d53c59ec29325e27df52234cbaaee Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sat, 18 Jul 2026 18:59:06 +0300 Subject: [PATCH 3/4] docs: move memory questions to idea inbox --- docs/README.md | 3 +- docs/architecture/README.md | 3 - docs/architecture/local-first-sync.md | 9 +- docs/architecture/project-format.md | 11 +- ...ient-project-persistence-decision-brief.md | 619 ------------------ docs/architecture/technology-stack.md | 33 +- ...ient-vertical-slice-implementation-plan.md | 50 +- docs/planning/idea-inbox.md | 105 ++- lab/notes/README.md | 4 +- .../first-slice-source-trace-2026-07-18.md | 186 +++--- .../t3-code-targeted-review-2026-07-18.md | 9 +- 11 files changed, 239 insertions(+), 793 deletions(-) delete mode 100644 docs/architecture/scient-project-persistence-decision-brief.md diff --git a/docs/README.md b/docs/README.md index 5c2c86f..7869e50 100644 --- a/docs/README.md +++ b/docs/README.md @@ -32,7 +32,8 @@ Start here: - [Scient product identity](product/scient-product-identity.md) - accepted company, app, native-agent, external-agent, and naming vocabulary. - [Product philosophy](product/product-philosophy.md) - draft durable product principles; the accepted PRD governs conflicts. - [Technology stack](architecture/technology-stack.md) - current proposed stack direction. -- [Scient project persistence decision brief](architecture/scient-project-persistence-decision-brief.md) - draft context, alternatives, questions, and evidence gates for later storage review; no project store is selected. +- [Idea inbox](planning/idea-inbox.md) - categorized intake for unresolved ideas, + including the future Scient memory-architecture discovery. - [Product roadmap](planning/product-roadmap.md) - current sequence of coherent product outcomes. - [First vertical-slice implementation plan](planning/first-scient-vertical-slice-implementation-plan.md) - bounded plan for the active product slice. - [Scient and external agents implementation plan](planning/scient-and-external-agents-implementation-plan.md) - proposed plan for building the Scient agent as the owned OpenCode-derived first-party agent while preserving external agents independently. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index e017c3c..23f6205 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -12,9 +12,6 @@ Architecture docs explain how Scient should be structured and why. They must cle Current documents: - `technology-stack.md` - current stack direction. -- `scient-project-persistence-decision-brief.md` - draft reviewer brief for the - unresolved canonical project-state, reliability, portability, backup, sync, - and storage-technology decision; it is not implementation authorization. - `project-format.md` - future home for the Scient project format. - `local-first-sync.md` - future home for local-first and sync architecture. - `collaboration-model.md` - future home for collaboration architecture. diff --git a/docs/architecture/local-first-sync.md b/docs/architecture/local-first-sync.md index 311ee04..ebbf7cf 100644 --- a/docs/architecture/local-first-sync.md +++ b/docs/architecture/local-first-sync.md @@ -3,14 +3,15 @@ Status: Placeholder Owner: Yaacov Created: 2026-06-27 -Last updated: 2026-07-17 +Last updated: 2026-07-18 Purpose: Defines what should be documented about Scient local-first storage and cloud sync once the design is validated. Doc type: Future home This page will document Scient's local-first and sync architecture when it -exists. The upstream decision context is currently captured in the draft -[Scient Project Persistence Decision Brief](scient-project-persistence-decision-brief.md), -which does not select a canonical project store or sync engine. +exists. Unprocessed questions about memory scope, user-selected cloud folders, +offline behavior, conversation continuity, and future Scient cloud sync remain +in the [Idea Inbox](../planning/idea-inbox.md#memory-context-and-continuity). +No canonical memory store or sync engine is selected. Document here: diff --git a/docs/architecture/project-format.md b/docs/architecture/project-format.md index 5c7c800..55382d0 100644 --- a/docs/architecture/project-format.md +++ b/docs/architecture/project-format.md @@ -3,14 +3,15 @@ Status: Placeholder Owner: Yaacov Created: 2026-06-27 -Last updated: 2026-07-17 +Last updated: 2026-07-18 Purpose: Defines what should be documented about Scient project structure once the format is designed. Doc type: Future home -This page will document the Scient project format when it exists. The open -canonical-state requirements, candidate representations, and proof obligations -are currently framed in the draft -[Scient Project Persistence Decision Brief](scient-project-persistence-decision-brief.md). +This page will document the Scient project format when it exists. Unprocessed +questions about project memory, conversations, files, portability, Git, cloud +folders, and storage boundaries remain in the +[Idea Inbox](../planning/idea-inbox.md#memory-context-and-continuity) until a +dedicated memory-architecture discovery begins. Document here: diff --git a/docs/architecture/scient-project-persistence-decision-brief.md b/docs/architecture/scient-project-persistence-decision-brief.md deleted file mode 100644 index e14a6e4..0000000 --- a/docs/architecture/scient-project-persistence-decision-brief.md +++ /dev/null @@ -1,619 +0,0 @@ -# Scient Project Persistence Decision Brief - -Status: Draft -Owner: Yaacov -Created: 2026-07-18 -Last updated: 2026-07-18 -Purpose: Frames the open decision about where Scient-owned scientific records should live and what evidence is required before selecting or implementing a persistence design. -Doc type: Architecture direction - -## Document Rules - -- This is a review brief, not accepted architecture, an implementation plan, or - evidence that a project-local database exists. -- The accepted PRD owns the product outcomes. This brief translates those - outcomes into persistence questions and proof obligations. -- SQLite is one serious candidate. It is not selected by this document. -- The inherited application SQLite database is current implementation, but it - is not automatically the canonical Scient project store. -- No production persistence code, schema, sync layer, or migration should be - created from this brief before the decision process reaches explicit human - acceptance. - -## Executive Summary - -Scient needs a durable home for scientific records that must survive beyond a -chat, agent session, provider, or one installation of the desktop app. The -current product foundation can identify and reopen a Scient project folder, and -the inherited host can persist application projects, threads, messages, and -provider sessions. It does not yet own a canonical source-to-task-to-proposal- -to-decision history. - -Project-local SQLite is attractive because it can provide atomic transactions, -constraints, migrations, indexed history, and non-Git recovery in one embedded -file. It also creates serious questions about cloud-synchronized folders, -active-copy safety, binary Git behavior, multi-device collaboration, readable -exports, backup, schema evolution, corruption response, and the relationship -between project files, database rows, CRDT history, object storage, and a future -cloud mirror. - -The immediate decision is therefore not "use SQLite." The immediate work is to -agree on requirements, compare credible storage models, run a disposable -persistence evaluation against real failure modes, and only then produce an -architecture decision for Yaacov to accept or reject. - -## Why This Decision Exists - -The first scientific workflow eventually needs to preserve relationships such -as: - -```text -exact source revision - -> bounded task revision - -> immutable context receipt - -> run and proposal revision - -> researcher decision - -> accepted scientific record - -> recovery history -``` - -If those relationships live only in application state, deleting or moving the -application may detach a project from its accepted scientific history. If they -live only in an agent transcript, deleting or replacing the provider may do the -same. If they rely only on Git, non-Git researchers cannot receive the promised -recovery behavior. - -The storage choice matters before that workflow is implemented because it will -shape record identity, atomicity, revision semantics, recovery, UI queries, -agent tool contracts, export, backup, sync, migration, and support. Choosing too -early risks freezing an unproven topology; choosing after production records -exist creates a costly and risky migration. - -## Relationship To The T3 Code Work - -The bounded T3 Code review is a separate lane. It produced small reliability -improvements for image parsing, literal Git paths, AppImage child environments, -snapshot/live-event characterization, and browser native-pipe isolation. Those -changes do not require or select a Scient project database. - -T3 supplied implementation evidence and comparison points for desktop runtime -boundaries. It did not supply Scient's scientific record model. This persistence -question comes from Scient's own researcher-ownership, provenance, review, and -non-Git recovery requirements. T3 completion must not be blocked by this later -decision. - -## Explicit User Direction At This Checkpoint - -Yaacov provided the following direction on 2026-07-18: - -Approved requirements: - -- recovery must work without Git; -- project filesystem scope must be enforced at a trusted Scient boundary rather - than delegated to prompt wording or an unrestricted shell; and -- native Scient runtime state must remain completely independent from the - user's external OpenCode installation. - -Deferred: - -- deterministic fake-executor implementation and its controlled product test - will be discussed later. - -Open for later review: - -- the permanent code/package seam for ongoing scientific project operations; -- the canonical storage representation and location; -- whether project-local SQLite is suitable; -- the exact portability, backup, sync, and collaboration model; and -- the implementation sequence that depends on those choices. - -## Current Implemented State - -### Portable project initialization - -The permanent `@scientfactory/project-init` package can inspect, plan, -initialize, recover, and roll back project-folder setup. It creates or preserves -`PROJECT.md`, `AGENTS.md`, and `.scient/project.json`. That JSON file provides a -path-independent project identity. The package intentionally has no SQLite, -agent, React, Electron, or inherited Synara dependency. - -It does not currently store scientific sources, tasks, context receipts, -proposals, decisions, accepted revisions, or recovery history. - -### Host application state - -The Synara-derived desktop server places its application database at -`~/.scient/userdata/state.sqlite` in production. It stores and projects host -concerns such as project registration, workspace paths, threads, messages, -turns, approvals, provider sessions, and application activity. - -That database is valuable current implementation. It is tied to the local app -installation and must not be relabeled as canonical scientific project truth -without a separate decision. - -### Missing project-owned record boundary - -No implemented store currently proves that accepted scientific records: - -- survive deletion of host project, chat, provider, or agent state; -- move or restore with the research project; -- remain coherent after interruption during acceptance; -- recover without Git; -- export completely into a documented researcher-readable representation; or -- synchronize safely across devices or collaborators. - -## Required Outcomes Before Selecting A Technology - -These are candidate requirements for review. They must be accepted, revised, or -rejected independently of any database library. - -### Ownership and authority - -1. Scient-owned scientific records remain authoritative independently of chat, - provider, executor, or host UI projections. -2. Deleting or rebuilding app-level state cannot silently delete accepted - project truth. -3. Provider transcripts and tool logs may be evidence, but are not the only - reconstruction path for accepted records. -4. Secrets, provider credentials, authentication tokens, and unrelated user - settings never enter the project-owned scientific store. - -### Integrity and recovery - -5. Accept, reject, revise, and recover operations have explicit atomicity or an - equivalently proven repair protocol. -6. A crash or forced termination at every durable-write boundary cannot produce - a falsely accepted or partially advanced scientific record. -7. Recovery appends an auditable action; it does not erase prior decisions. -8. Corruption, incompatible schema, or failed migration becomes an explicit - safe state and never triggers silent destructive repair. -9. Backup and restore reproduce IDs, relationships, accepted pointers, and - decision history exactly. - -### Portability and researcher control - -10. Moving or renaming a complete local project preserves its identity and - record history. -11. The supported transfer unit is explicitly defined: folder copy, backup - bundle, export/import, Git clone, cloud mirror, or another mechanism. -12. Researchers can export all canonical records and relationships in a - documented, readable, non-proprietary representation. -13. Scient can explain which files or stores must be copied and whether the app - must be closed first. -14. Unsupported network or cloud-folder behavior is detected or documented - honestly rather than implied safe. - -### Performance and scale - -15. Project open, common reads, proposal review, acceptance, history browsing, - backup, migration, and integrity checks meet explicit budgets on realistic - projects rather than only toy fixtures. -16. Performance remains understandable as sources, revisions, tasks, runs, - proposals, decisions, figures, analyses, and manuscript links grow. -17. Startup does not require scanning or reparsing an unbounded project history - when an index or checkpoint can be validated safely. -18. Large assets remain ordinary files or object-storage content; structured - metadata does not accidentally duplicate entire PDFs, datasets, or outputs. - -### Concurrency, sync, and collaboration - -19. A second local Scient process cannot unknowingly become a conflicting - writer. -20. The design states whether concurrent readers are supported and how stale - views are refreshed. -21. The behavior of active databases or ledgers inside iCloud Drive, Dropbox, - OneDrive, network filesystems, backup tools, and file-level sync is tested or - explicitly unsupported. -22. Multi-device and multi-user writes are not claimed solved by a single local - file format. -23. A future cloud mirror has a defined authority and conflict relationship to - local project truth before bidirectional sync is selected. -24. Structured state, document/CRDT history, large-file revisions, and Git - artifacts can eventually participate in one inspectable project timeline - and restore story. - -### Maintainability and support - -25. Schema and format versions are explicit and migrations are deterministic, - tested, resumable or safely restartable, and backed up before destructive - steps. -26. The chosen library and native dependencies package reliably on supported - macOS, Windows, and Linux targets. -27. Integrity inspection, backup, export, recovery, and support diagnostics are - available without exposing sensitive content unnecessarily. -28. The design has a credible path for future schema evolution without freezing - the complete scientific object model in the first slice. - -## Candidate Storage Models - -This list is a shortlist for investigation, not a verdict. - -### Candidate A: project-local SQLite as canonical structured state - -Example shape: - -```text -project/ - .scient/ - project.json - project.sqlite -``` - -Potential strengths: - -- mature atomic transactions and crash recovery; -- foreign keys, uniqueness, checks, and indexed queries; -- explicit migrations and integrity checks; -- one embedded structured store with no server process; and -- strong local query performance at likely first-slice scale. - -Questions and risks: - -- active WAL and shared-memory side files complicate naive copying or file-level - cloud sync; -- a binary database is not human-readable or meaningfully Git-mergeable; -- branch, clone, backup, and folder-transfer semantics need an explicit policy; -- multi-device writes and cloud collaboration require more than SQLite itself; -- corruption, migration, locking, checkpoint, and backup UX become product - responsibilities; and -- a per-project SQLite-to-single-cloud-database topology is already identified - as a deep unproven sync assumption. - -Primary SQLite references for the review: - -- SQLite documents atomic commit and rollback behavior in - [Atomic Commit In SQLite](https://www.sqlite.org/atomiccommit.html). -- The [Write-Ahead Logging](https://www.sqlite.org/wal.html) documentation - explains the single-writer model, checkpointing, additional `-wal` and - `-shm` files, and the limitation that all WAL processes must be on the same - host. -- [WAL-mode File Format](https://www.sqlite.org/walformat.html) describes the - persistent database, WAL, and shared-memory files that copy, backup, and - recovery procedures must account for. -- [SQLite Backup API](https://www.sqlite.org/backup.html) describes consistent - live snapshots and the separate `VACUUM INTO` snapshot option. -- [`PRAGMA integrity_check`](https://www.sqlite.org/pragma.html#pragma_integrity_check) - documents one integrity diagnostic, while also making clear that foreign-key - errors require a separate check. - -These references support SQLite-specific test design. They do not establish -that SQLite is the right product architecture or that a naive folder copy or -file-level synchronization protocol is safe. - -### Candidate B: append-only structured project files - -Example shapes include one immutable JSON record per event/revision, a segmented -JSONL log, or content-addressed records plus explicit pointers. - -Potential strengths: - -- inspectable with ordinary tools; -- potentially easier to copy, archive, diff, and include in Git; and -- canonical records naturally live in the project folder. - -Questions and risks: - -- cross-record atomicity, pointer updates, locking, compaction, and crash repair - become custom protocols; -- high record counts may require a derived index; -- partial file sync, rename semantics, duplicate events, and conflicting writers - still need explicit handling; -- migrations may become many-file rewrites or layered readers; and -- "human-readable" files can still be too numerous or relationally complex for - meaningful manual inspection. - -### Candidate C: append-only canonical files plus a derived SQLite index - -The project files would own durable events or records; SQLite would be a -rebuildable local index or materialized view. - -Potential strengths: - -- combines inspectable canonical records with efficient local queries; -- deleting the index would not delete project truth; and -- Git/copy/export behavior may be clearer than a canonical binary database. - -Questions and risks: - -- introduces two representations whose derivation must be deterministic; -- replay, checkpoints, invalidation, and index rebuild time require proof; -- atomic acceptance spanning canonical files and current pointers is still a - custom protocol; and -- sync conflicts in canonical event files remain unresolved. - -### Candidate D: app-local canonical database with explicit portable bundles - -Canonical structured state would remain under `~/.scient`; project export or -backup would create a portable, self-contained bundle. - -Potential strengths: - -- follows a conventional application-state model; -- avoids active database files inside ordinary project folders; and -- can make locking, migration, and local performance operationally simpler. - -Questions and risks: - -- the project folder alone is incomplete; -- move, reinstall, and cross-device behavior depend on users understanding - export/import; -- deletion of app state becomes a higher-consequence event; -- background backups must be reliable and discoverable; and -- it may conflict with the product promise that the researcher owns the local - project rather than an opaque app library. - -### Candidate E: another embedded store or bundle format - -Other embedded databases, archive formats, or content-addressed designs may be -proposed by reviewers. A new candidate should be evaluated against the same -requirements rather than added because of library familiarity. - -## Questions For SQLite Reviewers - -A reviewer assessing project-local SQLite should answer at least these -questions and cite implementation evidence or primary documentation where -possible. - -### Reliability - -1. Which journal mode is appropriate for a portable desktop project, and why? -2. What exactly happens if the process is terminated during each acceptance, - migration, backup, or checkpoint phase? -3. How will Scient distinguish recoverable interruption from corruption? -4. Which SQLite integrity checks run automatically, manually, and before backup - or migration? -5. What is the repair policy, and which failures must remain read-only pending - user action? -6. How are disk-full, read-only filesystem, permission, antivirus, and sudden - device-removal failures surfaced? - -### Copy, backup, and restore - -7. Can the whole project be copied safely while Scient is open? If not, how is - that prevented or explained? -8. Will Scient use the SQLite backup API, `VACUUM INTO`, a closed-file copy, or - another snapshot protocol? -9. How are WAL and shared-memory files handled during close, backup, restore, - crash, and manual folder copying? -10. How is a backup verified before it is declared usable? -11. Can restore be tested into a different path and machine without mutating the - original project? -12. What retention and user-visible recovery points are required? - -### Filesystems and synchronization - -13. Which local, removable, network, and cloud-synchronized filesystems are - supported on macOS, Windows, and Linux? -14. What happens when iCloud, Dropbox, or OneDrive copies an active SQLite file - and its transient companions independently? -15. Can Scient detect known-unsafe locations or simultaneous file-level sync? -16. Is file-level sync prohibited in favor of an application-level sync or - export protocol? -17. What is the behavior after an offline divergent copy returns? - -### Git and developer workflows - -18. Is the project database committed, ignored, exported, or represented by a - separate portable form? -19. What happens across branch switches, worktrees, rebases, and clones? -20. If the database is not Git-tracked, how does a Git clone receive canonical - scientific history? -21. If it is tracked, how are binary merge conflicts prevented or resolved? - -### Concurrency and collaboration - -22. What locking proves that only one writer owns a project? -23. Can multiple readers or processes safely inspect it? -24. How are stale locks distinguished from a live owner after a crash? -25. How would local IDs, mutations, attribution, and conflicts map to a future - cloud/Postgres mirror? -26. Does one database per project fit the likely cloud security and row-level - access-control topology? -27. Which collaboration promises are deliberately deferred? - -### Performance and capacity - -28. What are realistic small, medium, and stress project sizes? -29. What budgets apply to open, common query, acceptance, history, migration, - backup, export, and integrity check? -30. How do indexes, WAL growth, checkpoints, vacuuming, and long-running readers - behave under those sizes? -31. What disk amplification results from revisions, backups, exports, and - content hashes? -32. Can the app remain responsive while maintenance operations run? - -### Schema and maintainability - -33. Which layer owns SQL, migrations, transactions, IDs, and invariants? -34. Should Scient reuse Effect SQL, introduce a query builder, or keep a narrow - owned repository layer? -35. How is the complete schema versioned and inspected for support? -36. How are forward-incompatible projects handled by older app versions? -37. Can migrations be retried safely, and how is rollback handled when they - cannot? -38. How do we avoid freezing the complete future project graph in the first - schema? - -### Transparency and researcher experience - -39. What readable export contains every canonical record, ID, relationship, - decision, and accepted pointer? -40. Can an export be validated and re-imported into an empty installation? -41. How does the UI explain backup health, migration, read-only mode, - corruption, conflicting writers, and recovery without database jargon? -42. What diagnostics can a researcher safely share with support? -43. Can a researcher leave Scient without losing access to their record history? - -## Questions For Every Candidate - -The decision must also answer technology-neutral questions: - -- What is the canonical unit: project, record, event, file, bundle, or database? -- Which identifiers survive move, copy, export, restore, and cloud mirror? -- Which operation constitutes acceptance, and what exact failure states exist? -- Which data is immutable, append-only, mutable, derived, cached, or external? -- How are ordinary files and structured records linked without duplicating or - silently detaching them? -- How is one complete project timeline reconstructed across structured records, - documents, files, Git artifacts, agent evidence, and later cloud state? -- What does "portable" mean for folder copy, Git clone, backup, export, and a - second device? -- What is the smallest implementation that proves the first source-to-note - workflow without pretending to solve full collaboration? -- What evidence would cause us to reject the candidate? -- What is the migration path if the candidate later proves unsuitable? - -## Proposed Evaluation Protocol - -The evaluation must be disposable and must not become production code by -accident. It does not need a real model, native Scient agent, or the user's live -research project. - -### Shared minimal record model - -Each candidate implements only enough to exercise: - -1. create and reopen a project identity; -2. append a source revision and exact excerpt digest; -3. append a task and immutable context receipt; -4. append a proposal revision; -5. accept or reject it while preserving the previous accepted state; -6. append a recovery action; -7. export every record and relationship; -8. close, move, reopen, back up, restore, and verify the project; and -9. detect a conflicting writer and an incompatible schema. - -The executor output is fixed test input. This is a persistence evaluation, not -the deferred fake-executor product implementation. - -### Failure matrix - -Inject interruption or failure: - -- before any durable write; -- after each record write or pointer update; -- before and after commit or equivalent publish step; -- during migration; -- during backup and restore; -- with disk-full and read-only paths; -- with a killed process and stale lock; -- with missing, truncated, duplicated, or modified records; -- while a second process attempts to write; and -- during a representative copy or synchronization operation. - -After every case, verify whether the project is unchanged, fully advanced, or -explicitly read-only/recoverable. No case may produce silently inconsistent -accepted truth. - -### Scale and performance matrix - -Define realistic small, medium, and stress fixtures before measurement. Record: - -- cold and warm open time; -- common source/task/proposal/history query latency; -- acceptance and recovery latency; -- export, backup, integrity-check, and migration duration; -- memory and disk use; -- database, log, index, and backup growth; and -- UI responsiveness during maintenance work. - -Do not accept a candidate using only tiny synthetic records. Do not set final -budgets after seeing results; proposed budgets must be reviewed before the -comparison run. - -### Portability matrix - -Verify at least: - -- folder rename and move on one filesystem; -- move to a different local volume; -- backup and restore into a different path; -- reopen on another supported operating system where practical; -- Git repository and non-Git folder behavior; -- active and closed copy behavior; -- representative cloud-synchronized folder behavior; and -- explicit rejection or warning for unsupported locations. - -## Decision Gates - -### Gate 1: requirements review - -Yaacov reviews the required outcomes, scope, and deliberately deferred -collaboration claims. No storage technology is selected. - -### Gate 2: candidate and test-plan review - -Reviewers confirm that the candidate list and failure, scale, portability, -backup, export, migration, and concurrency tests are sufficient and fair. - -### Gate 3: evidence run - -Run the disposable evaluation and preserve reproducible commands, fixtures, -results, limitations, and failures. Narrow unit tests do not substitute for real -persistence, copy, process, and filesystem behavior. - -### Gate 4: proposed architecture decision - -Write an ADR that states the selected model, rejected alternatives, evidence, -constraints, migration/exit path, unsupported behavior, and remaining risks. -Its status remains Proposed until Yaacov accepts it. - -### Gate 5: implementation authorization - -Only after acceptance should production schema, package APIs, migration paths, -project UI, or agent tools depend on the selected persistence model. - -## Reviewer Assignment - -A reviewer can use this document without reading the complete repository first. -They should receive: - -- this brief; -- the accepted [PRD](../product/PRD.md), especially local ownership, - inspectable history, review, and recovery; -- the [technology stack](technology-stack.md), while honoring its proposed - status; -- the existing [coherence report](../research/spike-reports/coherence-report-2026-06-28.md), - especially findings A1 and A5; -- the [testing philosophy](../quality/testing-philosophy.md); -- the [first-slice source trace](../../lab/notes/first-slice-source-trace-2026-07-18.md); - and -- the placeholder [project format](project-format.md) and - [local-first sync](local-first-sync.md) homes. - -Ask the reviewer to return: - -1. corrected or missing requirements; -2. a critique of every candidate, not only SQLite; -3. any additional candidate worth testing; -4. the minimum fair evaluation implementation; -5. required failure, scale, filesystem, backup, migration, and export tests; -6. primary-source evidence for external technology claims; -7. explicit reasons to reject project-local SQLite; -8. explicit reasons to reject file-based or app-local alternatives; -9. risks that belong in product scope rather than implementation; and -10. a recommendation about what Yaacov must decide before any code begins. - -## Non-Goals - -This brief does not: - -- select SQLite or another store; -- define production tables or the complete scientific object graph; -- authorize `packages/scient-project` or another permanent package seam; -- implement the deferred fake executor; -- implement sync, collaboration, cloud Postgres, CRDTs, object storage, or a web - client; -- claim active cloud-folder copying is safe; -- make T3 Code a product architecture dependency; or -- block completion of the bounded T3 reliability work. - -## Current Verdict - -Document and evaluate; do not implement yet. - -The product need for durable, app-independent, non-Git-recoverable scientific -records is credible. Project-local SQLite remains a strong candidate, but its -reliability, portability, usability, Git, sync, collaboration, backup, and -migration consequences require explicit evidence and human review before it can -become Scient architecture. diff --git a/docs/architecture/technology-stack.md b/docs/architecture/technology-stack.md index aecf2fd..b030f64 100644 --- a/docs/architecture/technology-stack.md +++ b/docs/architecture/technology-stack.md @@ -62,7 +62,7 @@ Scient app from the planned Scient agent where needed. | Local coordinator | Bun/Node.js WebSocket server | Inherited scaffold candidate; not yet a Scient decision | | Workspace tooling | Bun workspaces, Turborepo, Vite | Inherited scaffold candidate; not yet a Scient decision | | Cloud web app | React, with Next.js as a later candidate | Not scaffolded | -| Local structured state | SQLite for inherited app/session projections; canonical Scient project store undecided | App SQLite implemented; project persistence under later review | +| Local application state | SQLite for inherited app/session projections; future memory and project-state storage undecided | App SQLite implemented; memory architecture not yet designed | | Cloud database | Postgres | Proposed; not scaffolded | | Cloud platform | Supabase | Initial default candidate; not scaffolded | | Large file storage | Object storage | Proposed; not scaffolded | @@ -167,8 +167,8 @@ The current lab scaffold has this upstream shape: That tree remains foreign source and should not become the Scient package map by accident. Source-tracing notes and disposable adapter experiments may use `lab/scient-bridge/`. The first vertical-slice implementation belongs in a -permanent location to be selected from source evidence and the deferred -persistence review; do not treat the lab as its default code home. +permanent location to be selected from source evidence and later focused +product/architecture work; do not treat the lab as its default code home. Possible later Scient-owned package areas include: @@ -234,26 +234,25 @@ SQLite is selected for canonical Scient project records. The inherited scaffold already uses SQLite for Synara app, session, orchestration, and projection state. That database must not be relabeled as the Scient scientific project database. Scient-owned project persistence has not -been selected, designed, or implemented. The open requirements, candidates, -risks, questions, and evidence gates live in the -[Scient Project Persistence Decision Brief](scient-project-persistence-decision-brief.md). +been selected, designed, or implemented. The future memory-architecture project +will decide the roles of conversations, user memory, project memory, raw +history, files, local application storage, and cloud storage before evaluating +their persistence technologies. Unprocessed questions remain in the +[Idea Inbox](../planning/idea-inbox.md#memory-context-and-continuity). Scient should distinguish: - global app state, such as recent projects, local settings, device identity, and local caches - project-owned scientific state, such as sources, protocol records, evidence records, extraction records, manuscript state, agent runs, and sync metadata -The project-owned scientific record boundary is the more important -architectural object because projects must be portable and recoverable. Its -representation may be a project-local database, append-only structured files, a -canonical-file/derived-index hybrid, an app-local store with explicit portable -bundles, or another reviewed model. +The relationship among project-owned scientific records, future memory, raw +history, and ordinary files remains an open product and architecture question. +Do not turn one candidate representation into architecture before that broader +memory discovery. The inherited scaffold uses Effect SQL with SQLite through Bun. Do not replace -that layer merely to satisfy a candidate target stack. If project persistence -later selects SQLite, evaluate Effect SQL, Drizzle, Kysely, or a narrower owned -layer only after the project-state contract and persistence evidence are -reviewed. +that layer merely to satisfy a candidate target stack. Whether any part of a +future memory architecture reuses it is explicitly undecided. ## Cloud Data @@ -478,7 +477,7 @@ Completed historical experiments remain evidence, not the roadmap. | Synara-derived application | Standalone owned source, build, isolated Scient identity and state, reviewed upstream process | Scientific-product fit, sustainable domain UI divergence, and long-term maintenance cost | Gate 1 and Gate 1.5 lab reports; ADR-0001 owns adoption; ADR-0002 owns repository authority | | Scient source foundation | Owned OpenCode build, Synara compatibility, project-root fidelity, transcript fidelity, and approval flow for a constrained action | Scient identity and packaging, owned capabilities, isolated Scient state, durable task behavior, and justified inherited-core changes | Gate 1.5 report proves the source baseline; ADR-0001 owns Scient adoption | | External agents | Nine inherited adapters and external OpenCode settings/adapter paths are present in source | Per-agent live compatibility, subscription/auth behavior, project-task certification, and migration protection | [Scient and external agents implementation plan](../planning/scient-and-external-agents-implementation-plan.md) | -| Scient project state | Product responsibilities, approved non-Git recovery requirement, and trust boundary are documented | Canonical representation, package seam, reliability, portability, performance, backup, export, sync, and first real scientific object relationship | [Persistence decision brief](scient-project-persistence-decision-brief.md) and first vertical-slice plan | +| Scient project state and memory | Product responsibilities, high-level memory principles, approved non-Git recovery requirement, and trust boundary are documented | Memory scopes, canonical representation, conversation relationship, package seam, portability, recovery, cloud sync, and first real scientific object relationship | PRD, [Idea Inbox](../planning/idea-inbox.md#memory-context-and-continuity), and future focused architecture work | | Scient-agent and Scient-app boundary | Scient-agent identity plus context, proposal, review, provenance, and permission responsibilities are documented | Actual contract, code placement, event mapping, isolated Scient-agent state, and accepted write-back path | ADR-0001 and linked implementation plans; `agent-runtime.md` remains a future home | | Goose | Source seams, ACP path, and safety risks inspected | Incremental capabilities or architecture lessons for Scient; any future external Goose path is a separate decision | Goose source-depth inspection | | Cloud sync | Postgres, object storage, and local-first sync are proposed directions | Authority, offline behavior, conflicts, revocation, and recovery | Later roadmap and focused architecture work | @@ -495,7 +494,7 @@ The proposed and accepted-by-ADR foundation direction is: TypeScript React Electron -SQLite for inherited app state; canonical project persistence undecided +SQLite for inherited app state; future memory storage undecided Postgres Supabase as initial cloud platform candidate object storage diff --git a/docs/planning/first-scient-vertical-slice-implementation-plan.md b/docs/planning/first-scient-vertical-slice-implementation-plan.md index 6d93c58..bc76342 100644 --- a/docs/planning/first-scient-vertical-slice-implementation-plan.md +++ b/docs/planning/first-scient-vertical-slice-implementation-plan.md @@ -56,14 +56,16 @@ foundation and do not make the host project projection canonical. Phase 2 source tracing is complete in `../../lab/notes/first-slice-source-trace-2026-07-18.md`. It proved the current -state-ownership gaps and candidate seams, but Yaacov deferred the permanent -package, persistence technology, and fake-executor decisions for later review. -The open storage question now has a standalone reviewer brief at -`../architecture/scient-project-persistence-decision-brief.md`. Non-Git -recovery, trusted project filesystem scope, and complete native-Scient/external- -OpenCode runtime independence are approved requirements; they are not yet -fully implemented for ongoing scientific operations. The existing project-init -kernel already enforces path containment for initialization; the later +state-ownership gaps and candidate seams. Yaacov clarified that conversations, +project memory, user memory, recovery, cloud synchronization, and their storage +boundaries belong to a dedicated future memory-architecture project, not an +immediate persistence decision. Those unprocessed ideas now live in the +[`Idea Inbox`](idea-inbox.md#memory-context-and-continuity). The permanent +scientific-operation package and fake-executor product proof also remain +deferred. Non-Git recovery, trusted project filesystem scope, and complete +native-Scient/external-OpenCode runtime independence remain product +requirements; they are not a selected memory design. The existing project-init +kernel already enforces path containment for initialization, while later scientific-operation and native-agent boundaries remain to be built. The selected OpenCode-derived source is `bc125cbc60c36e4b7013f8d7cf755f745af509b3` on `dev`, but the native agent is not yet implemented or packaged. No @@ -421,22 +423,24 @@ roadmap or ADR unless the trace invalidates them. The first review established three requirements: non-Git recovery, trusted project filesystem scope, and complete native-Scient/external-OpenCode runtime -independence. Yaacov deferred the permanent package, persistence representation, -portability/sync model, and deterministic fake-executor product proof. - -The review exposed an open architecture decision: the reliability, performance, -usability, backup, migration, Git, cloud-folder, concurrency, and future-sync -consequences of canonical project persistence are unproven. Yaacov chose to -document and defer that decision rather than select or implement SQLite now. Use -`../architecture/scient-project-persistence-decision-brief.md` for requirements, -candidate, evidence, and ADR gates. Do not begin scientific-state product code -until that later review produces explicit authorization. +independence. Yaacov later clarified that the review had grouped future memory- +architecture questions too narrowly as a current persistence decision. The +scopes and relationships among conversations, user memory, project memory, raw +history, files, local storage, and future cloud storage must be discovered +together in a dedicated future project. + +The candidate questions are preserved in the +[`Idea Inbox`](idea-inbox.md#memory-context-and-continuity). They do not select +SQLite, define a project ledger, authorize memory implementation, or block the +independent T3 reliability work. The permanent scientific-operation package and +deterministic fake-executor product proof remain separate deferred decisions. ## Phase 3: Permanent Walking Skeleton Status: Deferred. The ordered work below remains a candidate sequence, not -current authorization. Replan it after the persistence decision and the later -fake-executor discussion. +current authorization. Replan the memory-dependent steps only when the future +memory-architecture project begins, and revisit the fake-executor question +separately. Do not treat that future discovery as a current T3 dependency. Implement in this order: @@ -588,13 +592,13 @@ Stop and report before widening scope if: - controlled fixture; - five-path map; - completed state-ownership table; -- explicit non-Git recovery approach; +- approved non-Git recovery requirement and unresolved future memory handoff; - permanent code-location candidates and explicit owner deferral; - reuse-versus-change list; - Scient integration and inherited OpenCode-core change verdict; - Synara-hosted versus external-topology verdict; -- deferred decision/evidence sequence; and -- an explicit no-go on scientific-state implementation until later review. +- future memory questions routed to the idea inbox; and +- no implied authorization for scientific-state or memory implementation. ### Vertical Slice Done diff --git a/docs/planning/idea-inbox.md b/docs/planning/idea-inbox.md index 4bceb68..819c49d 100644 --- a/docs/planning/idea-inbox.md +++ b/docs/planning/idea-inbox.md @@ -25,7 +25,9 @@ remove the raw inbox entry. Do not leave duplicate copies here and elsewhere. Use the lightest useful form: ```md -### YYYY-MM-DD — Short title +### Area + +#### YYYY-MM-DD — Short title - Idea: ... - Context or source: ... @@ -46,7 +48,9 @@ is being triaged. ## Unprocessed Ideas -### 2026-07-12 — Default project workspace and starting material +### Project And Workspace + +#### 2026-07-12 — Default project workspace and starting material - Idea: Plan how a new Scient user's basic desktop project workspace should be set up when the app creates and works with local files and folders. @@ -62,3 +66,100 @@ is being triaged. should work when opening an existing folder. - Possible area: product planning, project-format architecture, onboarding, and product design. + +### Memory, Context, And Continuity + +#### 2026-07-18 — Future Scient memory architecture + +- Idea: Plan Scient's complete memory architecture as a dedicated future + product and architecture project before selecting schemas, databases, or + synchronization machinery. +- Context or source: Questions about project records, conversations, SQLite, + Git, user-selected cloud folders, recovery, and future Scient cloud sync arose + during the first-slice source review. They belong to the broader memory-system + discussion, not the completed T3 reliability work or an immediate persistence + decision. The reusable questions from an oversized standalone persistence + brief were condensed here before that out-of-scope architecture file was + removed. +- Possible area: product planning, future memory architecture, agent runtime, + project format, security, provenance, synchronization, and product design. + +Candidate scopes to discuss, not accepted layers: + +- **Conversation memory:** short-lived or derived context from one conversation, + distinct from the complete transcript. +- **Task or run memory:** working state for one delegated task or agent run, + including what may expire when the run completes. +- **Project memory:** durable project direction, decisions, source judgments, + analysis choices, unresolved questions, collaborator decisions, and prior + work needed for continuity. +- **User memory:** personal preferences, recurring choices, and working style + that may apply across projects without silently overriding project rules. +- **Team or organization memory:** shared methods, conventions, and + institutional knowledge with explicit membership, permission, and ownership + boundaries. +- **Scient-maintained knowledge:** built-in product guidance, scientific skills, + and maintained procedures; this may require different authority and update + rules from user-generated memory. +- **Raw history and provenance:** complete conversations, events, actions, and + evidence that may support memory but are not automatically trusted memory. + +Questions to preserve for the future discovery project: + +- Which candidate scopes are actually needed, and what are their precise names + and responsibilities? +- Who owns, reads, edits, shares, exports, deletes, or promotes information in + each scope? +- What is ephemeral, retained for continuity, durable, canonical, derived, or + rebuildable? +- What is the difference between a complete conversation transcript, + conversation context, a summary, and trusted memory? +- Can a conversation or task propose project memory, and which promotions + require explicit researcher review? +- How are source, authority, confidence, freshness, conflict, staleness, + distrust, archival, forgetting, and supersession represented? +- What happens when user memory conflicts with project memory, or project + memory conflicts with current files and evidence? +- How can researchers inspect, correct, pin, challenge, archive, forget, or + disable remembered information? +- Which memory can Scient use, and which memory may be disclosed to an external + agent for one bounded task? +- How does task context include only the appropriate user, project, + conversation, and run information? +- How do project memory and provenance relate to ordinary researcher-owned + files without turning generated summaries into project authority? +- How do projects remain friendly to Git while never requiring Git for ordinary + use, history, or recovery? +- How should projects behave in iCloud Drive, Dropbox, OneDrive, external + drives, network locations, and other user-selected folders? +- Which information belongs in the project folder, local application storage, + a user account, or future Scient cloud storage? +- What remains fully useful offline, and what is restored or synchronized when + cloud access returns? +- How are concurrent edits, offline divergence, deletion, restoration, device + loss, and collaborator removal handled? +- How are conversations, memory, decisions, and provenance retained, backed up, + exported, transferred, encrypted, redacted, or permanently deleted? +- Which privacy, sensitive-data, institutional-control, and regional-storage + requirements constrain the design? +- What scale, latency, reliability, recovery, migration, portability, and exit + requirements must be accepted before evaluating storage technologies? +- Only after the memory model is understood, which persistence approaches + should be evaluated, including SQLite, structured files, derived indexes, + local databases, cloud databases, and combinations of them? +- If SQLite remains a candidate at that later stage, what evidence is required + for crash behavior, journal/WAL handling, active copying, cloud-folder sync, + backup and restore, integrity checks, locking, migrations, packaging, + performance, readable export, and exit from the format? + +Explicit non-decisions: + +- These scopes are prompts for discussion, not accepted memory architecture. +- Conversation, user, project, task, team, and system memory are not yet formal + product objects or storage boundaries. +- No database, schema, project ledger, cloud-sync protocol, or retention policy + is selected or authorized. +- The existing application SQLite database remains current app/session + implementation; it does not settle the future memory architecture. +- This future discovery does not block T3 reliability work or unrelated product + work. diff --git a/lab/notes/README.md b/lab/notes/README.md index 1402d3a..d781a6b 100644 --- a/lab/notes/README.md +++ b/lab/notes/README.md @@ -3,7 +3,7 @@ Status: Active Owner: Yaacov Created: 2026-07-08 -Last updated: 2026-07-17 +Last updated: 2026-07-18 Purpose: Maps temporary inspection notes and lab decisions before promotion into durable docs. Doc type: Repo orientation @@ -20,7 +20,7 @@ integration observations, and temporary lab decisions. - `synara-gate-1-baseline-2026-07-11.md` - historical inherited-scaffold baseline, official-CLI correction run, and Gate 1 pass result. - `synara-first-inspection-2026-07-07.md` - first source inspection of Synara as desktop base, OpenCode first-agent path, Goose integration path, and Scient ownership boundary. - `goose-source-depth-inspection-2026-07-11.md` - research input for Goose's later role, ACP surfaces, runtime-state boundary, permission risks, and first adapter recommendation. -- `first-slice-source-trace-2026-07-18.md` - exact desktop/agent path trace for the first scientific source-to-note slice; persistence and permanent package choices are explicitly deferred to the reviewer brief. +- `first-slice-source-trace-2026-07-18.md` - exact desktop/agent path trace for the first scientific source-to-note slice; future memory architecture and the permanent package remain explicitly unselected. - `t3-code-targeted-review-2026-07-18.md` - bounded T3 Code review through `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0`, including accepted reliability work and explicit deferred/rejected dispositions. Keep notes clear about whether they are: diff --git a/lab/notes/first-slice-source-trace-2026-07-18.md b/lab/notes/first-slice-source-trace-2026-07-18.md index 78fc9d1..e4aebd0 100644 --- a/lab/notes/first-slice-source-trace-2026-07-18.md +++ b/lab/notes/first-slice-source-trace-2026-07-18.md @@ -1,24 +1,24 @@ # First Scientific Slice Source Trace -Status: Complete as source evidence; persistence and package decisions deferred +Status: Complete as source evidence; memory and package architecture not selected Owner: Yaacov Created: 2026-07-18 Last updated: 2026-07-18 -Purpose: Maps the first scientific slice's current source seams, proven gaps, and decision requirements without selecting a persistence technology or authorizing product implementation. +Purpose: Maps the first scientific slice's current source seams and proven gaps without selecting memory layers, persistence technology, or permanent product architecture. Doc type: Implementation evidence ## Verdict -**Do not implement the permanent scientific-state skeleton yet.** The maintained -Synara-derived desktop can host the slice without making its project, thread, -provider, or checkpoint projections canonical scientific state, but the -permanent package seam and persistence model remain open for later review. +The maintained Synara-derived desktop can host a later scientific workflow +without making its project, thread, provider, or checkpoint projections +canonical scientific memory. This source trace does not select the future +memory architecture, its storage, or the permanent scientific-operation package. -A hybrid placement remains a leading candidate, not an accepted design: +A hybrid placement was one source-trace candidate, not an accepted design: 1. a possible `packages/scient-project` package in `scient-desktop` owns the - first-slice domain rules, project-local persistence, proposal decisions, - recovery, and filesystem-scope policy; + first-slice domain rules, proposal decisions, recovery behavior, and + filesystem-scope policy; 2. thin contracts, trusted-server RPC, and project-level UI shims call that package; and 3. a narrow executor port accepts immutable task/context receipts and returns a @@ -26,22 +26,19 @@ A hybrid placement remains a leading candidate, not an accepted design: discussion. Scient would eventually implement the port as a distinct execution target; external OpenCode remains an independent adapter. -The requirement under review is that canonical accepted state remain -independent of Synara's `~/.scient/userdata/state.sqlite`, provider sessions, -chat transcripts, and Git checkpoint refs. `.scient/project.json` already owns -portable identity. The location and representation of ongoing scientific -records are not selected. Project-local SQLite, append-only structured files, a -hybrid canonical-log/index design, and an app-local store with explicit portable -bundles require evidence-based comparison in -[`scient-project-persistence-decision-brief.md`](../../docs/architecture/scient-project-persistence-decision-brief.md). +The trace proved that `.scient/project.json` already owns portable project +identity while ongoing scientific memory and records have no selected location +or representation. Conversations, task/run context, project memory, user +memory, raw history, files, recovery, and cloud sync must be discussed together +in a dedicated future memory-architecture project. The raw candidate layers and +questions are preserved in the +[`Idea Inbox`](../../docs/planning/idea-inbox.md#memory-context-and-continuity). The existing Git-backed checkpoint mechanism is not suitable for the approved -non-Git guarantee. A future persistence design must prove that acceptance is -atomic or equivalently recoverable, records the prior accepted state, appends -the decision, and advances accepted state without rewriting history. No Git -repository, worktree, executor session, or transcript may be the only way to -reopen or recover the accepted source-to-note relationship. The mechanism is -open. +non-Git guarantee. A future memory and recovery design must determine how +accepted work remains coherent and recoverable without making a Git repository, +worktree, executor session, or transcript the only reconstruction path. The +mechanism and record model are open. One required and user-approved native-agent gap is now proven: the selected `scient-agent` source still defaults its global data/config/state roots and @@ -52,7 +49,7 @@ alter the existing external OpenCode adapter or its user-owned data paths. ## Controlled Fixture The deterministic synthetic capsule below remains a candidate for a later -controlled persistence or executor test. Yaacov deferred fake-executor product +controlled memory/recovery or executor test. Yaacov deferred fake-executor product implementation and is separately preparing a real project for later manual testing. The controlled fixture would protect the real project from destructive crash, corruption, migration, and recovery experiments; it is not authorized by @@ -114,17 +111,13 @@ platform user-data profile resolved by ### Scient attachment point -After the host resolves a workspace root, a future trusted server boundary -should inspect `.scient/project.json` and open the selected project-owned record -boundary through the approved package or service seam. The project-level UI -should be keyed by the portable Scient project ID, while the Synara project ID -remains a replaceable host reference. The persistence review must define what -must move, copy, export, or restore for history to remain portable; this trace -does not assume that a folder copy is sufficient. - -Failure to open the canonical store must not silently fall back to chat state. -It should show an explicit unavailable/migration/recovery state and leave the -project files untouched until the user chooses a safe action. +After the host resolves a workspace root, later project-aware capabilities can +inspect `.scient/project.json` and key their UI to the portable Scient project +ID while keeping the Synara project ID as a replaceable host reference. This +trace does not decide which memory or record boundary is then opened, what must +move with the folder, or how export, restore, and cloud continuation work. +Existing host or chat state must not be described as accepted memory merely +because no future store has been selected. ## Path B: Manual Operations And Minimal UI @@ -217,7 +210,7 @@ If a later workflow genuinely requires arbitrary shell execution, add an OS sandbox or isolated staged workspace as a separate safety slice. Do not claim that the current OpenCode permission prompt alone enforces filesystem scope. -## Path D: Persistence And State Ownership +## Path D: Current State Ownership And Future Memory Questions | State | Current owner | Location | Survives restart? | Canonical for Scient? | |---|---|---|---|---| @@ -233,13 +226,15 @@ that the current OpenCode permission prompt alone enforces filesystem scope. | Run receipt, proposal, and decision | Missing | Project-owned representation and location undecided | Must | Must | | Recovery state | Missing | Project-owned representation and location undecided | Must | Must | -The persistence choice must be evaluated against reliability, atomicity, -performance, scale, backup/restore, portability, readable export, Git and cloud- -folder behavior, concurrency, migration, packaging, future sync, and an exit -path. Secrets and provider credentials must never enter project-owned scientific -state. Large source files remain out of the first structured-state experiment. -The complete open question and reviewer assignment live in the -[persistence decision brief](../../docs/architecture/scient-project-persistence-decision-brief.md). +The future memory-architecture project must decide which of these rows represent +memory, raw history, provenance, ordinary files, application state, or another +kind of project record before comparing storage technologies. Its questions +include portability, Git independence and compatibility, user-selected cloud +folders, recovery, conversation retention, future Scient cloud sync, privacy, +and export. They are preserved in the +[`Idea Inbox`](../../docs/planning/idea-inbox.md#memory-context-and-continuity). +Secrets and provider credentials must never become project memory merely for +convenience. ## Path E: Proposal, Review, Non-Git Recovery, And Reopening @@ -257,7 +252,9 @@ Provider live diffs and host proposed plans are useful presentation/evidence inputs, but they remain thread/provider projections and cannot reconstruct an accepted scientific note after their session is deleted. -The approved behavioral requirement for a later proposal flow is: +The trace sketched the following candidate later proposal flow. Only the high- +level non-Git recovery outcome is approved; these record and transaction details +are not accepted memory architecture: 1. create immutable source, task, and context revisions; 2. open a run receipt before executor invocation; @@ -269,18 +266,11 @@ The approved behavioral requirement for a later proposal flow is: 8. atomically advance the accepted state and publish; and 9. on reject or failure, append the outcome without changing accepted pointers. -Reopening must read the portable project identity and canonical record without -starting an agent. Recovery creates a new decision/revision that points back to -the recovery point; audit history remains intact. Interrupted publication must -leave the old state authoritative or the new state fully authoritative, never a -silent partial mixture. Corruption/open failures must be explicit and read-only -until a verified recovery action is chosen. - -This behavioral boundary is credible for a controlled fixture only if -acceptance changes a bounded set of canonical records atomically or through an -equivalently proven protocol. Later materialized project-file changes require -content-addressed preimages or another reviewed file transaction; they must not -be silently declared covered by the first record mechanism. +The future memory discovery must decide whether this is the right model, what +reopening and recovery mean at each memory layer, and how interrupted changes or +corruption are surfaced. This trace does not select immutable records, +transactions, accepted pointers, content-addressed preimages, or another repair +protocol. ## Permanent Seam Comparison @@ -293,12 +283,11 @@ not user acceptance and not a persistence-technology score. | Isolated modules scattered across contracts/server/UI | 3 | 2 | 3 | 3 | 2 | 2 | 2 | | Hybrid package plus thin integration shims and executor port | 5 | 5 | 5 | 4 | 4 | 5 | 5 | -The hybrid remains the leading code-placement candidate because a package can +The hybrid scored highest in this preliminary comparison because a package can make ownership explicit while named shims make UI/server/executor crossings -testable. It is not selected. Yaacov deferred the permanent package and -persistence choice for later review. The persistence evaluation must determine -whether this placement remains appropriate once storage, migration, backup, -portability, and support obligations are understood. +testable. It is not selected. A future memory architecture may change which +responsibilities belong together, so this comparison remains historical source- +trace evidence rather than a current package recommendation. ## Reuse Unchanged @@ -334,7 +323,7 @@ portability, and support obligations are understood. - evaluate whether `packages/scient-project` should own domain commands, persistence-independent interfaces, revision/recovery rules, and path-scope policy; -- select a persistence model only through the decision brief's reviewed gates; +- do not select persistence or memory boundaries from this trace; - add narrow DTO/RPC contracts and server services that resolve portable identity from the workspace root and call the package; - add one project-level route/view and sidebar entry; and @@ -357,62 +346,33 @@ After a later review, expose a bounded Scient workflow capability that consumes the gateway receipt and returns a proposal. The first capability profile must not provide unrestricted shell or direct canonical writes. -## Deferred Decision And Coding Sequence - -No scientific persistence or executor code is authorized by this trace. The -next sequence is documentation and evidence first: - -1. **Requirements review:** revise and accept the technology-neutral ownership, - recovery, portability, export, performance, and collaboration requirements. -2. **Candidate review:** compare project-local SQLite, append-only structured - files, canonical files plus a derived index, app-local storage plus portable - bundles, and any reviewer-supported alternative. -3. **Disposable evidence run:** exercise real persistence, process, filesystem, - copy, backup, restore, migration, concurrency, scale, and corruption behavior - without using production code or the user's live project. -4. **Architecture decision:** propose an ADR with evidence, rejected options, - unsupported behavior, and an exit path; keep it Proposed until Yaacov accepts - it. -5. **Package and implementation plan:** only then select the permanent package - seam and rewrite the coding backlog around the accepted model. -6. **Deferred executor discussion:** decide later when and how a deterministic - executor proof and the user's real project should enter the sequence. -7. **Native Scient isolation:** preserve the approved requirement that native - Scient and external OpenCode never share credentials, processes, paths, - sessions, plugins, databases, or updates; authorize implementation separately. - -## Go/No-Go Conditions - -Go now only for completing and publishing the independent T3 reliability work and -for documenting/reviewing persistence requirements. Do not begin scientific- -state product implementation. +## Deferred Memory-Architecture Handoff -The later design may go to implementation only when evidence proves: +This trace does not authorize memory, persistence, or executor implementation. +It hands the unresolved relationships among conversation history, task/run +context, user memory, project memory, raw history, provenance, files, recovery, +and cloud sync to a dedicated future discovery project. The candidate layers, +questions, and explicit non-decisions are preserved in the +[`Idea Inbox`](../../docs/planning/idea-inbox.md#memory-context-and-continuity). -- manual and agent paths share one command boundary; -- accepted state is independent of host and provider sessions; -- non-Git recovery is atomic or equivalently recoverable and testable; -- project scope is enforced at the canonical/gateway boundary rather than - trusted to prompt wording; -- external OpenCode remains unchanged; and -- the first coding backlog is bounded around an accepted persistence model. +The permanent scientific-operation package and deterministic fake-executor +product proof remain separate deferred questions. Native Scient isolation is an +approved independent requirement: native Scient and external OpenCode must not +share credentials, processes, paths, sessions, plugins, databases, or updates. -Stop and revisit this decision if implementation proves any of these: +## Go/No-Go Conditions -- no candidate can meet the reviewed reliability, portability, performance, - backup, export, migration, and concurrency requirements at acceptable cost; -- accepted state requires host projection IDs or an executor transcript; -- scoped gateway tools cannot prevent direct native-agent writes for the - controlled workflow; -- native Scient cannot isolate every durable path from external OpenCode without - a broad upstream-hostile rewrite; or -- the project-level UI requires a broad workbench redesign. +The independent T3 reliability work may complete without any memory decision. +This trace also does not create a broad blocker for unrelated product work. +Memory-dependent workflow behavior should be planned only when the dedicated +memory project begins; the package, executor proof, and native-agent integration +require their own explicit authorization. ## Review Checkpoint The source map is complete, but its former SQLite and hybrid-package selection -is withdrawn pending later review. The approved requirements are non-Git -recovery, trusted filesystem scope, and complete native-Scient/external-OpenCode -runtime independence. Fake-executor work is deferred. Use the -[Scient Project Persistence Decision Brief](../../docs/architecture/scient-project-persistence-decision-brief.md) -for the next review; do not infer implementation authorization from this note. +is withdrawn. The approved requirements are non-Git recovery, trusted +filesystem scope, and complete native-Scient/external-OpenCode runtime +independence. Fake-executor work is deferred. Future memory questions live in +the [`Idea Inbox`](../../docs/planning/idea-inbox.md#memory-context-and-continuity); +do not infer memory architecture or implementation authorization from this note. diff --git a/lab/notes/t3-code-targeted-review-2026-07-18.md b/lab/notes/t3-code-targeted-review-2026-07-18.md index 7e667fd..14e1658 100644 --- a/lab/notes/t3-code-targeted-review-2026-07-18.md +++ b/lab/notes/t3-code-targeted-review-2026-07-18.md @@ -98,10 +98,11 @@ When the first scientific vertical slice reaches its execution contract: - preserve existing external adapters and settings; and - keep canonical scientific state independent of every provider session store. -The independent T3 intake is complete and is not blocked by the later project- -persistence decision. Before scientific-state product implementation, use the -[`Scient Project Persistence Decision Brief`](../../docs/architecture/scient-project-persistence-decision-brief.md) -and the revised first-slice trace to review requirements and candidates. +The independent T3 intake is complete and has no dependency on the future +memory-architecture project. Raw questions about conversation, user, project, +and task/run memory; portability; recovery; Git and cloud folders; and future +Scient cloud sync are preserved separately in the +[`Idea Inbox`](../../docs/planning/idea-inbox.md#memory-context-and-continuity). ## Triggered Shelf From f9ae9fd2da868fc3596bd5461c1b44bf6576f73c Mon Sep 17 00:00:00 2001 From: Yaacov Date: Sat, 18 Jul 2026 19:09:38 +0300 Subject: [PATCH 4/4] docs: reconcile T3 review with merged source heads --- docs/architecture/technology-stack.md | 4 ++-- ...ient-vertical-slice-implementation-plan.md | 4 ++-- ...and-external-agents-implementation-plan.md | 4 ++-- lab/external/owned-sources.json | 4 ++-- lab/external/sources.lock.md | 20 +++++++++++++++---- .../first-slice-source-trace-2026-07-18.md | 4 ++-- .../t3-code-targeted-review-2026-07-18.md | 3 ++- 7 files changed, 28 insertions(+), 15 deletions(-) diff --git a/docs/architecture/technology-stack.md b/docs/architecture/technology-stack.md index b030f64..61afb23 100644 --- a/docs/architecture/technology-stack.md +++ b/docs/architecture/technology-stack.md @@ -90,10 +90,10 @@ v0.5.5 passed hosted CI at `d4b10c27` and advanced owned `main` to owned `main` as `d9d8992a`, based on tested upstream `9be46c3c`. Subsequent reviewed UI and project-init status follow-ups advanced maintained `main` to `2ecfbe19`. Standalone ownership and upstream-maintenance follow-ups then -advanced maintained `main` to `57e6b2cd`; exact provenance is recorded in +advanced maintained `main` to `bd2a6eed`; exact provenance is recorded in `lab/external/sources.lock.md`. The owned OpenCode-derived repository—the current source foundation for the Scient -agent—is in the workspace sibling `../scient-agent/` on `dev` at `bc125cbc`, +agent—is in the workspace sibling `../scient-agent/` on `dev` at `67e7f3f0`, after a reviewed sync through source version 1.18.3 at official upstream `69a80663` and the standalone upstream-maintenance rollout. Historical Gate 1 and Gate 1.5 commits, tags, and ignored runtime evidence remain diff --git a/docs/planning/first-scient-vertical-slice-implementation-plan.md b/docs/planning/first-scient-vertical-slice-implementation-plan.md index 37c900d..e904f7b 100644 --- a/docs/planning/first-scient-vertical-slice-implementation-plan.md +++ b/docs/planning/first-scient-vertical-slice-implementation-plan.md @@ -51,7 +51,7 @@ and the reviewed desktop implementation added `@scientfactory/project-init` with zero-write inspection, explicit plan/apply behavior, conservative recovery, and focused tests. The package, trusted-server RPC, project-open/setup dialog, and interrupted-initialization recovery UI are present on maintained desktop `main` -at `57e6b2cde09f64db367b894506f56db605fb91b4`. They initialize only the portable +at `bd2a6eed6243b13fc1423b21b2454ae060bce5c7`. They initialize only the portable foundation and do not make the host project projection canonical. Phase 2 source tracing is complete in @@ -67,7 +67,7 @@ native-Scient/external-OpenCode runtime independence remain product requirements; they are not a selected memory design. The existing project-init kernel already enforces path containment for initialization, while later scientific-operation and native-agent boundaries remain to be built. -The selected OpenCode-derived source is `bc125cbc60c36e4b7013f8d7cf755f745af509b3` +The selected OpenCode-derived source is `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a` on `dev`, but the native agent is not yet implemented or packaged. No scientific-state store, Scient agent gateway, proposal/decision ledger, or complete scientific workflow is claimed as implemented. diff --git a/docs/planning/scient-and-external-agents-implementation-plan.md b/docs/planning/scient-and-external-agents-implementation-plan.md index a09cf3e..26fb4b1 100644 --- a/docs/planning/scient-and-external-agents-implementation-plan.md +++ b/docs/planning/scient-and-external-agents-implementation-plan.md @@ -125,7 +125,7 @@ Source lineage does not merge product identities: ## Current Implementation Truth At maintained desktop-source revision -`57e6b2cde09f64db367b894506f56db605fb91b4`, inspected on 2026-07-18, the +`bd2a6eed6243b13fc1423b21b2454ae060bce5c7`, inspected on 2026-07-18, the inherited host contains a shared provider adapter contract and adapters for: - Codex; @@ -158,7 +158,7 @@ paths first, then certify compatibility honestly per agent. The owned OpenCode-derived checkout in the workspace sibling `../scient-agent/` (relative to the Scient repository root), maintained on -`dev` at `bc125cbc60c36e4b7013f8d7cf755f745af509b3`, is the accepted +`dev` at `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a`, is the accepted source foundation for the Scient agent. Its repository and maintenance-verifier identity are Scient-owned while its current runtime remains upstream-aligned OpenCode source. Scient-agent packaging, private state diff --git a/lab/external/owned-sources.json b/lab/external/owned-sources.json index 05e5ae9..83cdddf 100644 --- a/lab/external/owned-sources.json +++ b/lab/external/owned-sources.json @@ -5,7 +5,7 @@ "ownedRepository": "ScientFactory/scient-desktop", "sourceLockLabel": "Scient desktop", "ownedDefaultBranch": "main", - "testedHead": "57e6b2cde09f64db367b894506f56db605fb91b4", + "testedHead": "bd2a6eed6243b13fc1423b21b2454ae060bce5c7", "officialRepository": "Emanuele-web04/synara", "officialDefaultBranch": "main", "reviewedThrough": "69304bc1d59d86da8afbac367118c75db8c9dbfe", @@ -18,7 +18,7 @@ "ownedRepository": "ScientFactory/scient-agent", "sourceLockLabel": "Scient agent source", "ownedDefaultBranch": "dev", - "testedHead": "bc125cbc60c36e4b7013f8d7cf755f745af509b3", + "testedHead": "67e7f3f0341c7a5bad8d68e0a29f113b450eb02a", "officialRepository": "anomalyco/opencode", "officialDefaultBranch": "dev", "reviewedThrough": "fab213312927ea64cf968832c527206e8c944f9e", diff --git a/lab/external/sources.lock.md b/lab/external/sources.lock.md index b78a134..62fedde 100644 --- a/lab/external/sources.lock.md +++ b/lab/external/sources.lock.md @@ -26,9 +26,9 @@ siblings. A deferred source with no retained checkout says so explicitly. | Source | Local path | Official upstream | Owned repository | Tested integrated upstream base | Maintained/tested commit | Role and update mode | |---|---|---|---|---|---|---| -| Scient agent source (OpenCode-derived) | `../scient-agent/`; canonical workspace sibling on `dev` at `bc125cbc60c36e4b7013f8d7cf755f745af509b3` | `https://github.com/anomalyco/opencode.git`, `dev` | `https://github.com/ScientFactory/scient-agent`, public standalone repository | `69a80663a2ed7d671d2b4d5dd6f2d605714675a5` | Current owned `dev` `bc125cbc60c36e4b7013f8d7cf755f745af509b3`; exact rename and maintenance evidence below | Owned source foundation for the planned Scient agent; `adapter-maintained`; native Scient runtime identity is not yet implemented. | +| Scient agent source (OpenCode-derived) | `../scient-agent/`; canonical workspace sibling on `dev` at `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a` | `https://github.com/anomalyco/opencode.git`, `dev` | `https://github.com/ScientFactory/scient-agent`, public standalone repository | `69a80663a2ed7d671d2b4d5dd6f2d605714675a5` | Current owned `dev` `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a`; exact rename and maintenance evidence below | Owned source foundation for the planned Scient agent; `adapter-maintained`; native Scient runtime identity is not yet implemented. | | Goose | No local checkout is retained. | `https://github.com/aaif-goose/goose.git`, `main` | None; owned repository deferred | Not tested in Gate 1.5 | Last inspected commit `3c1fdd692cc8aaa5f09b9175410c09a09d4dfe49` | Deferred broader-agent research input. Repository, build, ACP adapter, runtime, credentials, and adoption wait until after the first Scient gateway. | -| Scient desktop (Synara-derived) | `../scient-desktop/`; canonical workspace sibling on `main` at `57e6b2cde09f64db367b894506f56db605fb91b4` | `https://github.com/Emanuele-web04/synara.git`, `main` | `https://github.com/ScientFactory/scient-desktop`, public standalone repository | `9be46c3ce6a7521b64436b7334bc6fce16e3cac4` | Current owned `main` `57e6b2cde09f64db367b894506f56db605fb91b4`; exact rename and maintenance evidence below | Accepted initial application foundation; `divergent-cherry-pick`; must not own scientific project truth. | +| Scient desktop (Synara-derived) | `../scient-desktop/`; canonical workspace sibling on `main` at `bd2a6eed6243b13fc1423b21b2454ae060bce5c7` | `https://github.com/Emanuele-web04/synara.git`, `main` | `https://github.com/ScientFactory/scient-desktop`, public standalone repository | `9be46c3ce6a7521b64436b7334bc6fce16e3cac4` | Current owned `main` `bd2a6eed6243b13fc1423b21b2454ae060bce5c7`; exact rename and maintenance evidence below | Accepted initial application foundation; `divergent-cherry-pick`; must not own scientific project truth. | | T3 Code | No canonical local checkout is retained. | `https://github.com/pingdotgg/t3code.git`, `main` | None | Not tested in Gate 1.5 | Targeted review completed through `bf76535fe4da71d8de7b8bd5ffa0d2086b7af8d0`; see [`t3-code-targeted-review-2026-07-18.md`](../notes/t3-code-targeted-review-2026-07-18.md) | Trigger-driven desktop/runtime/provider/process reference only; not a continuously monitored upstream. | ## Maintained Upstream Review State @@ -40,8 +40,8 @@ review is accepted. | Source | Tested owned head | Reviewed through | Integration base | Update mode | Review evidence | |---|---|---|---|---|---| -| Scient desktop | `57e6b2cde09f64db367b894506f56db605fb91b4` | `69304bc1d59d86da8afbac367118c75db8c9dbfe` on 2026-07-18 | `9be46c3ce6a7521b64436b7334bc6fce16e3cac4` | `divergent-cherry-pick` | [`2026-07-18-scient-desktop.md`](upstream-reviews/2026-07-18-scient-desktop.md); no code intake | -| Scient agent source | `bc125cbc60c36e4b7013f8d7cf755f745af509b3` | `fab213312927ea64cf968832c527206e8c944f9e` on 2026-07-18 | `69a80663a2ed7d671d2b4d5dd6f2d605714675a5` | `adapter-maintained` | [`2026-07-18-scient-agent.md`](upstream-reviews/2026-07-18-scient-agent.md); no code intake | +| Scient desktop | `bd2a6eed6243b13fc1423b21b2454ae060bce5c7` | `69304bc1d59d86da8afbac367118c75db8c9dbfe` on 2026-07-18 | `9be46c3ce6a7521b64436b7334bc6fce16e3cac4` | `divergent-cherry-pick` | [`2026-07-18-scient-desktop.md`](upstream-reviews/2026-07-18-scient-desktop.md); no code intake | +| Scient agent source | `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a` | `fab213312927ea64cf968832c527206e8c944f9e` on 2026-07-18 | `69a80663a2ed7d671d2b4d5dd6f2d605714675a5` | `adapter-maintained` | [`2026-07-18-scient-agent.md`](upstream-reviews/2026-07-18-scient-agent.md); no code intake | ## Standalone Ownership And Maintenance Rollout @@ -86,6 +86,12 @@ source-repository pull requests: distribution-signed and fails strict code-sign verification, so public release remains blocked by [issue #6](https://github.com/ScientFactory/scient-desktop/issues/6). +- Desktop [PR #14](https://github.com/ScientFactory/scient-desktop/pull/14) + adapted six bounded T3-informed reliability protections and browser-session + isolation fixes; exact head `8a8398e817b803ccf7811d6f4f378bee1fa85d77` + passed hosted CI run `29646625880`, including browser, Windows process, build, + and release-smoke coverage, and merged as + `bd2a6eed6243b13fc1423b21b2454ae060bce5c7`. - Agent [PR #1](https://github.com/ScientFactory/scient-agent/pull/1) established the operator card, review state, verifier modes, owned source quality workflow, and monitor; exact head @@ -123,6 +129,12 @@ source-repository pull requests: `e6a06de63ce668144bb00e20dbd8f392a4da230a` passed hosted source-quality run `29645764713` without annotations and merged as `bc125cbc60c36e4b7013f8d7cf755f745af509b3`. +- Agent [PR #8](https://github.com/ScientFactory/scient-agent/pull/8) + refreshed the immutable `apple-actions/import-codesign-certs` pin in the + retained, upstream-guarded publish workflow; exact head + `08a9ccec50bf1100d9ad32211a9bbaec0db06717` passed hosted source-quality run + `29646968673` and merged as + `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a`. No source code from the reviewed official ranges was integrated during this rollout. The PRs above establish ownership, review, monitoring, and verification diff --git a/lab/notes/first-slice-source-trace-2026-07-18.md b/lab/notes/first-slice-source-trace-2026-07-18.md index e4aebd0..276d659 100644 --- a/lab/notes/first-slice-source-trace-2026-07-18.md +++ b/lab/notes/first-slice-source-trace-2026-07-18.md @@ -81,8 +81,8 @@ files are context for future slices and are not ingested in this one. | Source | Selected revision | Working state | Relevant upstream result | Minimal health evidence | |---|---|---|---|---| -| Scient desktop (`scient-desktop`) | owned `main` `57e6b2cde09f64db367b894506f56db605fb91b4` | Canonical checkout clean when selected | Official Synara reviewed through `69304bc1d59d86da8afbac367118c75db8c9dbfe`; verifier current with no unreviewed commits | Existing installed-app smoke reached project initialization. On reliability branch `8a8398e8`, full tests, typecheck, build, release smoke, and 171 browser tests passed; the branch does not alter this trace's product seams. | -| Scient agent (`scient-agent`) | owned `dev` `bc125cbc60c36e4b7013f8d7cf755f745af509b3` | Clean and equal to `origin/dev` | Official OpenCode reviewed through `fab213312927ea64cf968832c527206e8c944f9e`; verifier current with no unreviewed commits | Maintained upstream verifier and public-identity check passed. A live Scient action was not run because native Scient identity, private state, packaging, and gateway are correctly still absent. | +| Scient desktop (`scient-desktop`) | owned `main` `bd2a6eed6243b13fc1423b21b2454ae060bce5c7` | Canonical checkout clean when selected | Official Synara reviewed through `69304bc1d59d86da8afbac367118c75db8c9dbfe`; verifier current with no unreviewed commits | Existing installed-app smoke reached project initialization. Reliability PR #14 passed full tests, typecheck, build, release smoke, and 171 browser tests at exact head `8a8398e8` before merging; the change does not alter this trace's product seams. | +| Scient agent (`scient-agent`) | owned `dev` `67e7f3f0341c7a5bad8d68e0a29f113b450eb02a` | Clean and equal to `origin/dev` | Official OpenCode reviewed through `fab213312927ea64cf968832c527206e8c944f9e`; verifier current with no unreviewed commits | Maintained upstream verifier and public-identity check passed. A live Scient action was not run because native Scient identity, private state, packaging, and gateway are correctly still absent. | No upstream code was merged during this trace. The agent revision advanced only through already-merged repository automation changes after the prior source-lock diff --git a/lab/notes/t3-code-targeted-review-2026-07-18.md b/lab/notes/t3-code-targeted-review-2026-07-18.md index 14e1658..9c13e0a 100644 --- a/lab/notes/t3-code-targeted-review-2026-07-18.md +++ b/lab/notes/t3-code-targeted-review-2026-07-18.md @@ -78,7 +78,8 @@ owning socket, send notifications only through that socket, reject cross-client attach, detach, and CDP requests, dispose the session listener on disconnect, and preserve the other socket. The test exercises real framed native-pipe requests and two distinct tabs rather than only testing an internal helper. The -complete bounded intake is published for review in +complete bounded intake passed hosted CI at exact head `8a8398e8` and merged as +`bd2a6eed` through [Scient desktop PR #14](https://github.com/ScientFactory/scient-desktop/pull/14). ## Use During Existing Scient Work