Skip to content

spec(FIX-1790): A user's data is kept per org, for every flow - #2810

Merged
jhoffner merged 2 commits into
mainfrom
spec/FIX-1790
Oct 6, 2026
Merged

jhoffner merged 2 commits into
mainfrom
spec/FIX-1790

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator
Someone who… Today After
works in Acme and Globex Globex shows her the preferences, notes and private flow data that she saved in Acme Each org shows only the data that she saved there. Globex starts empty
gets a private roster of workers (FIX-1788) Her workers are user data, so one roster shows in the two orgs Her Acme roster is not her Globex roster
uses a hired seat and the app's chat flow in one org The seat keeps its own copy for the org. The chat flow keeps one copy for all orgs. They do not see each other The two flows use her one cell in that org, as other flows that share user data do
upgrades a deployment that has saved user data n/a Each person starts empty until the operator does a documented copy step. The step copies a saved cell only into the one org that its sessions name. Nothing is read across orgs. Nothing is deleted
sends a request with no org Refused since FIX-1442 Still refused. The cross-org cell is never the answer

Goal: a person who works in two orgs sees, in each org, only the data that they saved there, in every flow. The data that they saved before the upgrade comes back in one org at most.

flowchart LR
  A["one app flow · no pin · two orgs · two people"] --> L1["leg a · Alice saves in Acme"]
  L1 --> L2["leg b · Alice in Globex and Bob in Acme read"]
  P0["a record saved before the upgrade"] --> L3["leg c · the upgrade and the copy step"]
  L2 -->|"no marker crosses"| P["PASS · goal met"]
  L3 -->|"reads in one org at most"| P
  C1["control · the key without the org"] -.-> L2
  L2 -.->|"under the control"| F["must FAIL · Globex reads Acme's marker"]
Loading

The check reads what each caller gets back. It does not read the keys. The dashed path removes the org from the key, and it must fail. Check: goals/user-scope/keeps-a-users-data-in-the-org-it-was-saved-in/, no model, controls GOAL_CONTROL=cross-org-key and GOAL_CONTROL=fallback-read. Why this goal: SPEC.md.

Today, the chat flow for Alice in Acme and in Globex writes one cell, alice, and her Acme seat keeps its own cell. After, every flow writes a cell for its person and org; the seat and the chat flow share alice in acme. The old cell is below a fence, and only the operator step copies it into one org

The red lines on the left are the leak. On the right, each flow writes into the box of its org. The old cell stays, but nothing reads it.

How: one function makes every user key. It now adds the org of the run or of the stored session. A schedule dispatch names its org. The test harness uses the same function.

Sign off

The goal, at that size: every flow, every view, user state and the two kinds of resource, and old records in one org at most. If wrong: FIX-1788 builds private rosters on a key that still crosses orgs at one location.

Old data is read by nothing until an operator copies it. Until then, each person starts empty in each org · D1

D1. Old data read by nothing, chosen, beside a migration-required refusal. Decides it: a person who worked in two orgs works in both, and is not refused on every flow. Price: an operator who skips the step sees no error

It comes down to a person who worked in two orgs: a refusal stops them on every flow. If wrong: a deployment that skips the step shows empty preferences and collections to all people, with no error.

The step copies a saved cell into an org only when all sessions that could write it name that org, and the operator vouches that none was deleted · D2

D2. The one org that the sessions of its writers name, chosen, beside membership records. Decides it: Alice moved from Acme to Globex, and membership copies the Acme data into Globex. Price: a person with a deleted session stops, unless the records of the operator clear every other org

It comes down to a person who changed orgs: membership copies the data of the old org into the new org. A deleted session leaves no trace, so the sessions that are left are proof only when none is missing. If wrong: a person who worked in two orgs, or whose sessions were deleted, gets their shared data back in no org, until a person decides by hand.

Open: none. D1 is the one to weigh. Reasons and the options that lost: DECISIONS.md. The cases: BUSINESS-RULES.md.

Reviewers · look here

  • Decisions → D1. Is "start empty, no error" better than a loud refusal for an operator who forgets the step?
  • Rules → BR-16 and BR-17. Is "the sessions that could write the cell" the correct writer set? A flow-isolated cell counts only the sessions on its flow.
  • Plan → S4. The schedule dispatch now names the org. Do the three dispatch producers (default parser, Vercel tick, BullMQ worker) cover all hosts?

Not here: workers and private projects as user data (FIX-1788, FIX-1793). Removal of owner pins (FIX-1798).

Spec · Decisions · Rules · Plan · Docs · Evolution
· Linear FIX-1790 · epic FIX-1786 (#2795) · builds on FIX-1538 · merges after human approval and required checks (merge contract)

How to review this — altitude, what's in scope, what's deliberately unsettled

This is a direction set, not an implementation. Reviewing it well means
answering one question: is this the right approach?

In scope to challenge:

  • The goal and the problem framing in SPEC.md — is the goal the real need at full size,
    for the people named, or a smaller goal that would let us call this done early? Would the
    named check fail if the goal were not met?
  • The approach — will it work, does it fit the architecture and docs/philosophy.md?
  • Any numbered decision in DECISIONS.md — that's the sign-off surface.
  • A case BUSINESS-RULES.md misses, or a rule that would invalidate the design.
  • Scope — a deliverable that shouldn't ship, or one that's missing.
  • The reader-facing promises in DOCS.md and their fit with the rules; a missing or
    misleading lineage claim in conditional EVOLUTION.md.

Out of scope — deliberately unsettled here, and owned by the implementing agent:

  • Names, signatures, file paths, and module layout beyond the few PLAN.md pins on purpose.
  • Local structure: which helper, how a function is decomposed, error-message wording.
  • Micro-optimizations and style preferences.
  • Test names and internal test structure (the behaviours are the rules; the tests are not).
  • Anything PLAN.md left open on purpose — it is directional by design, and a gap at that
    altitude is intended, not an omission.
  • The figures, at the pixel level. A figure is right when it reads right. A misplaced label
    or a colour you'd have chosen differently is not a finding; a figure that shows a shape the
    decisions don't say is.
  • The solution sketch, at the line level. PLAN.md may include a rough pseudocode sketch
    showing the shape of the proposed solution. It is knowingly incomplete, is not real code,
    and is not what will ship. Review it for directional viability only. Do not report
    that it lacks error handling, omits edge cases, names things that don't exist in the repo, or
    wouldn't build: all of that is true on purpose.
  • POC implementation polish. Experiments under the owning spec's poc/ are retained,
    not production code. Read them for directional evidence, not production completeness.
    Their isolation from production/default discovery and absence of secrets or generated
    dependencies are in scope; retention is not permission to weaken repository checks.

One request, if you are an automated reviewer: the two lists above are the whole difference
between a useful review of this document and a long one. Volume is not signal here — a single
finding above the line is worth more than twenty below it.

Feedback in the second list is welcome and gets recorded verbatim in PLAN.md → Notes from review for the implementer to weigh against real code. It will not be argued with, and it
will not be folded into the design prose. Please don't re-raise it: one mention is enough.

The one exception is the sketch and the POC. Line-level feedback on either is dropped, not
recorded — there is nothing for an implementer to weigh about code that isn't shipping. Feedback
about their direction is not line-level and is treated like any other above-the-bar finding.

Direction approval does not waive merge-time required checks, approvals or thread policy.
Optional comments do not require another design round merely to reach zero comments.

Engineering calls — decided, not asked
  • One cell per (person, org) for every flow: <person>:~org:<org>, the cell that hired seats use now, plus the flow when the data is flow-isolated. The seat data does not move. A seat now shares the person's cell with the other flows of the app in that org.
  • The org comes from the admitted run or the stored session. A header or a body never sets it.
  • A missing or blank org throws. No path makes the cross-org key.
  • The schedule dispatch names the org, and the stored row must name the same org.
  • The test harness seeds through the same key function, with the org of the run.
  • The copy step is a documented procedure for each store adapter, not a command. The original cells stay.
  • Old-term exports that stay for FIX-1796 and FIX-1798: IsolationFlow.ownerPin (ignored, deprecated), ScheduleResolutionContext.ownerPin, InstanceOwnerPin.
POC — two retained checks, not production code
  • node specs/issues/FIX-1790/poc/key-shape/check.mjs (and --plant, which must fail). Question: can a new key be equal to an old key, or to the key of a different person, org or flow? Result: no, for about four million keys. Without the ~org marker: 24,964 collisions.
  • node specs/issues/FIX-1790/poc/key-sites/check.mjs (and --plant, which must fail). Question: which source files make a user key, and which org does each file have? Result: nine files. Only the schedule resolver has no org (plan S4).

These checks are retained design evidence. CI does not run them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV


Generated by Claude Code


Generated by Claude Code

Retained issue spec: one (person, org) cell for every flow, reusing the
hired seat's cell shape; old cross-org cells are read by nothing and
copied by a documented operator step that attributes a cell to the one
org its writers' sessions name. Two POCs: key-shape (no new key equals
an old one) and key-sites (every user key site, and its org source).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@jhoffner jhoffner added the spec label Oct 6, 2026 — with Claude
@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1790

@vercel

vercel Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments
Project Deployment Actions Updated
flow-state-dev-docs Ignored Ignored Oct 6, 2026 7:53pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 6, 2026 7:53pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 6, 2026 7:53pm UTC

Request Review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 6, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-06T19:25:08.975658Z 947e164 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (direction only)

The core approach holds. One key derivation, the org taken from the admitted run or stored session, and old cells made unreachable by construction rather than by a fallback read. I found no leaner shape for the key itself. The leaner options sit around it: how the schedule dispatch carries the org, how many adapters get a copy step, and how the PR is cut. Checked against fbecfe6f2. I read the spec docs and scope-keys.ts, and grepped the engine, scheduled and workforce call sites. I did not run the POCs.

Above the bar

1. The copy step ships for "each adapter" but is only walked on SQLite (D1 / V7 / S7).

  • BR-16 to BR-19 and the goal's "Not done if" row require the step to be walked "on a real store". V7 walks it once, on a SQLite file.
  • The Postgres adapter, and any third-party store, get a documented procedure that nothing exercised. These are the procedures an operator runs on production data, with writers stopped, and with no undo other than "the original stays".
  • Recommendation: either require the walk on each adapter the framework ships (SQLite and Postgres), or scope the published step to the adapters that were walked and say so in DOCS.md. Do not publish unwalked SQL.

2. The seat and the chat flow now share one cell. The upgrade cost of that is not priced (BR-4, BR-5, "Decided, not asked").

  • FIX-1538 kept a seat's cell apart from the app's cell. This spec merges them and says "the registry still refuses incompatible schemas".
  • For a deployment that already hires seats whose user state or user resources differ from the app flows', that refusal is a boot failure at upgrade. It is not the "start empty" outcome D1 describes. No rule or check covers it (V2 does the pair only with compatible schemas).
  • Recommendation: add a rule and a V-row for "an app that hires a seat with an incompatible user schema". Decide whether it fails loudly at startup with a message that names both flows, or whether the schema check should be relaxed for this case. Also say which in DOCS.md. FIX-1538's own note, quoted in PLAN.md under At implement time, says the check is "stricter than needed for seats", and the plan then calls it "exactly right". That reversal needs a sentence of reasoning.

3. The silent-empty failure mode (D1) is the main cost, and nothing detects it.

  • D1 is well argued against the refusal option. But "no error, everyone looks empty" is the failure an operator hits first.
  • The follow-up (a startup warning) is deferred because stores can't list scope ids. This design has no detection for it, and the step's doc can't help once the upgrade has run.
  • Recommendation: do not leave this as an unowned follow-up. Either file it now as a sibling of this issue and gate FIX-1788 on it, or put a copy-paste smoke query in the step's doc, so an operator can see uncopied cells before they open the app. The changeset note alone is easy to miss.

Plausible simplifications to weigh

4. S4 changes three schedule dispatch producers and a public id shape. The index may make that smaller.

  • packages/scheduled/src/testing.ts shows index rows already carry cell, userId and orgId per row. The Vercel tick and the BullMQ worker hold such a row when they dispatch.
  • If those two producers pass the row's org and cell through, the only producer that needs the <orgId>/<userId>/<key> id is the default HTTP parser. That would shrink the plan's "three producers change together" and the number of operator-visible cloud scheduler URLs that break.
  • This is a question, not a finding. If the row can't be trusted as the source (the resolver must re-derive the cell from the stored session), say so in PLAN.md S4. The reviewer prompt asks whether the three producers cover all hosts. A host that builds its own dispatch from the old two-part id still compiles, and the resolver returns null, so that schedule stops firing without an error. The upgrade note needs to list this.

5. "1 PR" across five packages, 35 test and goal files, docs and a walked operator step is the multi-PR shape.

  • The plan already has a DAG: S1/S2/S3/S5 (key, context, read side, harness) → S4 (schedule) → S6/S7 (goal, docs, step). The schedule slice and the docs and step slice also have different reviewers and different risk (public URLs; production data).
  • Recommendation: declare a PR plan so each slice merges green on its own. The one constraint is that the key change and its read-side must land together, or a view reads a different cell than the run wrote. The goal check (VG) should land with the slice that makes it pass, not after it.

Architecture notes, not requests

  • After S1, the pin parameter in scope-keys.ts (IsolationFlow.ownerPin, the pin forwarding in toIsolationFlow, the FIX-1538 header paragraph) is dead. The spec keeps ownerPin as "accepted, ignored, deprecated" for FIX-1796 and FIX-1798. That is fine, but give it a removal owner in the code comment, not only in the spec. Otherwise it becomes a permanent no-op field.
  • packages/workforce/src/clear-shadowed-references.ts keeps its own copy of the engine's org-key escaping. It is an org-scope key, not a user key, so it is correctly outside this issue and outside the nine-file count. It is the same drift risk FIX-1323 warned about. If the implementer exports the escaping helper from the engine while in scope-keys.ts, that copy can be deleted. Otherwise, leave it alone.

Line-level feedback (naming, URL escaping, helper structure) is deliberately not raised here.


Generated by Claude Code

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

The epic needs per-(user, org) cells for every flow, and this spec picks the right core mechanism: reuse FIX-1538’s ~org shape, one convergence in scope-keys.ts, no fallback reads from legacy keys, and D1/D2 aligned with how this repo already does offline attribution. Unifying hired seats and app flows in the same cell per org is simpler than inventing a second key grammar or a deployment-wide “default org” read path.

Where the PR feels heavier than “medium · 1 PR” is mostly artifact surface, not wrong architecture: verification and prose are triplicated (SPEC goal ↔ BR “Proved by” ↔ PLAN V*), DOCS.md is a full future-site paste, and the operator playbook + V7 matrix is a lot for a migration command that is explicitly deferred.

Simpler paths worth weighing (non-blocking)

  1. Schedule identity vs storage key — S4 changes the public schedule id and every dispatch URL (<orgId>/<userId>/<key>) across scheduled, vercel, bullmq, guides, and cloud jobs. The schedule index already carries orgId on rows. If every producer can bind dispatch to that trusted field (and still enforce BP-031 on the stored row), you might get the same isolation with storage-key + resolver changes only and avoid a second breaking surface beside resolveUserStorageKey(userId, orgId, …). I’m not sure the tick paths allow that without re-reading the Vercel/BullMQ contracts; if they don’t, the spec’s URL change is justified — but it’s the highest blast-radius choice in the plan and worth a one-paragraph “why id segment, not index-only” in DECISIONS Decided.

  2. poc/key-sites exact counts — Totality is valuable; hard-coded derive/store counts will fail on innocent refactors. Consider classification-only (file → role + org source) and keep --plant for drift; promote invariants to engine vitest after S1 (as FIX-1538 never wired cell-sites to CI, but blast radius is larger now).

  3. DOCS.md shape — For spec retention, a page checklist + acceptance bullets (what must be true after publish) may age better than ~200 lines of replacement prose that will be re-derived by docs-writer anyway. Keep the upgrade SQL canonical in one place (persistence overview target), not duplicated across PLAN V7 narrative and DOCS.

  4. Verification layering — Make PLAN § Checks the single index; SPEC can keep the mermaid goal check; BR table could drop the “Proved by” column or only link V-ids to cut sync cost.

  5. V7 scope — Walking the full six-step SQL + schedule re-register in the implementation PR is the right proof once; spec could narrow to “one attributed copy, one migration-required stop, one schedule re-fire” unless epic closure truly needs the full matrix in PR-1.

Performance / ops (note for implementer, not a spec blocker)

Runtime path stays one derivation + same getAll fan-out; D1 correctly avoids per-run legacy probes. Upgrade cost is offline: full-store legacy scope scan, session attribution at scale (index (user_id, org_id) / flow variants in the runbook), and schedule index + external job re-registration — call that out in V7 evidence.

Verdict

Direction: approve-worthy. I’m not requesting changes on the technical approach; the inline notes are simplify / trim suggestions before or during implementation. If you already ruled out index-only schedule dispatch after tracing Vercel/BullMQ, a short DECISIONS bullet would close the main open alternative.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

| Flow-isolated user key | `<person>:~org:<org>:<flow>` | Persisted and named by the step. The `~org` marker keeps it apart from every other form (`poc/key-shape/`) |
| Public helper | `resolveUserStorageKey(userId, orgId, flow)` | Public; the scheduled docs show it. Taking the org positionally makes an old call fail to compile and throw at runtime |
| Default dynamic schedule id | `<orgId>/<userId>/<key>` | Public: the guides, cloud scheduler jobs and the operator step name it |
| The goal | `goals/user-scope/keeps-a-users-data-in-the-org-it-was-saved-in/` | Cited by path |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This pinned name is the widest public break in the issue (guides, cloud scheduler jobs, operator step §5, three dispatch producers). Before implementation freezes, worth one explicit sentence in DECISIONS: why the org must live in the schedule id string rather than only in storage keys + schedule_index.org_id at dispatch time. If tick URLs can carry org from the index row set at registration time, you might shrink S4 to resolver + key shape only.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Answered in DECISIONS → Decided, not asked (1e169dd): the Vercel tick and BullMQ both reach the resolver through the one dispatch id (packages/vercel/src/schedules.ts:55), and one person can hold daily in two orgs, so a two-part id names neither cell. Resolving it from the index would be a read across orgs. The id change stays.


Generated by Claude Code

|---|---|
| The org comes from the admitted run or the stored session, never a header or body (BP-031). A schedule dispatch's org only selects a cell; the stored row must name the same one | A caller who could choose the org could choose whose org's data a person reads |
| Nothing reads a one-part or two-part user cell, not even to see whether it exists (D1) | An existence check is a read across orgs, and a store call on every run |
| Every user-key site passes the org into S1. Re-run `poc/key-sites/check.mjs` and update its table in the same PR (tenet 5) | Nine files touch user keys; one that keeps the old call reopens the leak silently |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guardrail is right; the exact derive/store counts in poc/key-sites will churn on harmless refactors (extract helper, split route file). Simpler maintenance: require every scanner hit ∈ SITES with class + org source, drop per-family counts, keep --plant. Also align this “nine files” inventory with PLAN’s “35 literal scope_id” note — one sentence on derivation sites vs raw scope literals would save implementers maintaining two mental lists.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The count-vs-classification point is about the retained POC, so it is dropped per the review contract. The derivation-sites vs raw-literals sentence is recorded verbatim in PLAN → Notes from review.


Generated by Claude Code

Comment thread specs/issues/FIX-1790/PLAN.md Outdated
| V4 | S2 | BR-15: values planted in a person's old one-part and two-part cells before a run are read by no org, and are still there, unchanged, after it |
| V5 | S4 | BR-12 for each dispatch producer (default parser, Vercel tick, BullMQ worker): a schedule a run saved fires for its org; the same row under another org's dispatch, a dispatch with no org, and a row in the old cell all resolve as missing; a user-owned seat's other-person check still holds. BR-19 |
| V6 | S5 | BR-13: a value seeded through each helper, with and without `orgId`, is what the run reads |
| V7 | S7 | The published step walked once on a SQLite file, recorded in the PR. Copied: a one-org person; a two-org person's flow-isolated cell whose flow ran in one org; a deletion marker with its collection; a user record, id rewritten. Stopped: that person's shared cell; a person with no sessions; a written destination, keys named. A schedule fires once after the index rebuild |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

V7 is a strong bar for a spec that defers a shipped migration command (DECISIONS Considered and dropped). Consider scoping V7 to a minimal smoke (one attributed shared cell, one two-org migration-required, one schedule re-index) and treating the rest as runbook depth in published docs — unless epic ER-30 closure truly needs the full six-step walk in the first implementation PR.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kept the matrix: V7 is the only proof of BR-16 to BR-20 before an operator runs the step on production data. In 1e169dd it also walks Postgres, per another review. Your narrowing is recorded verbatim in PLAN → Notes from review.


Generated by Claude Code

> u_evil saved a schedule there. A row found under one organization that names another is
> refused too, so an id cannot fire a schedule into an organization its creator didn't choose.

## CREATE · `apps/docs/docs/persistence/overview.md` · "Upgrading: moving user data into its organization", replacing "Upgrading: moving hired seats' stored data"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is valuable as the canonical operator procedure, but at ~80 lines inside the spec it duplicates what will land on persistence/overview.md and what V7 must walk. For spec hygiene: could DOCS.md be a checklist of pages + “upgrade section must include steps 1–6, SQLite canonical, Postgres/fs pointers” instead of full replacement paragraphs? Reduces drift risk when docs-writer rewrites voice.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recorded verbatim in PLAN → Notes from review for the implementer. DOCS.md keeps the template draft shape.


Generated by Claude Code

> const [orgId, userId, key] = scheduleId.split("/").map(decodeURIComponent);
> const scopeId = resolveUserStorageKey(userId, orgId, { id: ctx.flowKind, isolateUserState: false });
> const row = await ctx.stores.resourceState.get("user", scopeId, `schedules/${key}`);
> if (row?.state.orgId !== orgId) return null;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Double gate: dispatch org selects the cell via resolveUserStorageKey, then row?.state.orgId !== orgId. If schedule rows don’t persist orgId today, this example implies a new persisted field; if scope already implies org, the check may be redundant in user-facing docs. One clarifying sentence in BR-12 or here would keep app authors from copying extra state they don’t need.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a new field: schedule rows already persist orgId, and the resolver checks it today (createResourceCollectionScheduleResolver.ts:135). The extra comparison stops a row found in one org cell that names another org. No spec change.


Generated by Claude Code


## Where a person's data lives

| # | When | Then | Proved by |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

“Proved by” duplicates SPEC goal legs and PLAN V1–VC. Not wrong, but it’s a third place to update when checks move. Optional trim: BR tables state behavior only; link to PLAN § Checks for verification IDs.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recorded in PLAN → Notes from review. The column stays for this spec.


Generated by Claude Code

|---|---|
| A new cell shape for unpinned flows, seats kept apart | Keys on the pin the epic is deprecating, and two cells per person per org isolate nothing |
| A deployment-wide "old data belongs to org X" setting | A permanent second read path, wrong for any deployment that ever had two orgs |
| A shipped migration command now | The stores' normal calls mint versions and drop deletion markers; the per-adapter procedures already have raw access. Revisit on D1's *change my mind* |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deferring a framework migrate-user-scope is consistent with store capabilities, but paired with a long SQL runbook + V7 it’s the main complexity budget of the issue. If D1’s change my mind stays theoretical, fine; if not, even a dry-run CLI that only runs steps 1–2 (list + attribute) would shrink operator error without full copy logic in the framework.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recorded verbatim in PLAN → Notes from review. D1 what would change my mind is the trigger for a shipped command.


Generated by Claude Code

| Is it the right goal? | |
|---|---|
| **The real need** | The PRD: "what a user keeps in one org never appears in another", for every flow, nothing deleted. The epic set "data stored before still reads" to "in one org at most, after an operator step" ([ER-3](../../epics/FIX-1786/BUSINESS-RULES.md#what-a-team-gets-and-what-it-doesnt)) |
| **Smaller, and rejected** | "The key carries the org." A one-line change that leaves a view, the schedule resolver or the test harness on the old cell |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good explicit rejection of “key carries org only” — calling out views + schedule resolver + harness is what makes this more than a one-line scope-keys change. That framing helps justify scope; consider mirroring it once in PLAN Surfaces intro so “medium” doesn’t read like S1-only.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PLAN intro now says why this is one PR (1e169dd). The rest is recorded as a note.


Generated by Claude Code

* `content.*` call whose scope argument is not a literal
* `"session"`, `"org"` or `"lineage"`
*
* Totality, not a spot check: every file with a hit must appear in `SITES` with

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adaptation from FIX-1538 cell-sites is the right reuse pattern. Post-S1, consider lifting the scanner + allowed-set assertion into packages/engine/test (or a single shared manifest) so CI enforces totality without two frozen copies (cell-sites + key-sites) diverging over time.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recorded verbatim in PLAN → Notes from review.


Generated by Claude Code

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 947e164a1a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread specs/issues/FIX-1790/DOCS.md Outdated
Comment on lines +162 to +165
> On Postgres, write `COUNT(*) FILTER (WHERE org_id IS NULL)` for `unknown`. A cell is
> attributed when `orgs` is one, `unknown` is zero, and your own records don't place those
> runs anywhere else. Anything else, including a person with no sessions left, is a
> `migration-required` stop for that cell: write it down and leave it.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Require complete session history before attribution

When only part of a user's session history remains, orgs = 1 and unknown = 0 do not prove that the legacy cell was written in only that organization. Sessions are explicitly deletable in packages/engine/src/routes/session-routes.ts:422-446; if Alice wrote the shared cell from Acme and Globex and her Globex session was later deleted, this procedure copies the mixed cell into Acme and exposes Globex data there. Require operator evidence that history is complete, or leave the cell migration-required whenever completeness cannot be established.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Folded in 1e169dd. A deleted session leaves no trace, so D2, BR-16/BR-17 and step 2 now need the operator to vouch that none of the person sessions was deleted, or that their own records never placed the person in another org. Otherwise the cell stops. V7 gains that stop, and the D2 card, figure and sign-off line say it.


Generated by Claude Code

>
> ```ts
> resolve: async (scheduleId, ctx) => {
> const [orgId, userId, key] = scheduleId.split("/").map(decodeURIComponent);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve the remainder of slash-bearing schedule keys

When a schedule collection permits nested keys such as daily/report, this destructuring keeps only daily, so the resolver reads the wrong resource and the schedule 404s. It also cannot distinguish structural separators from / inside an org or user ID after the wildcard router decodes and rejoins segments (packages/engine/src/routes/router.ts:343-365), contradicting the plan's round-trip requirement. Use a reversible component encoding and parse only the two structural separators while preserving the entire key remainder.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Recorded verbatim in PLAN → Notes from review. The escaping is the implementer call under the pinned round-trip rule, and the scheduled.md example will match what ships.


Generated by Claude Code

Comment thread specs/issues/FIX-1790/DOCS.md Outdated
Comment on lines +153 to +159
> For a flow-isolated cell, only that person's sessions on that flow. A session written before
> sessions recorded `flow_id` belongs to the flow named by its `flow_kind`:
>
> ```sql
> SELECT user_id, COALESCE(flow_id, flow_kind) AS flow, COUNT(DISTINCT org_id) AS orgs,
> SUM(org_id IS NULL) AS unknown, MIN(org_id) AS org
> FROM sessions GROUP BY user_id, COALESCE(flow_id, flow_kind);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Keep null flow owners migration-required

For a collection flow with sessions written before flow_id existed, a null owner does not mean the session belongs to the instance named by flow_kind; the current contract explicitly refuses such history because the instance cannot be inferred (apps/docs/docs/persistence/overview.md:109-113). This fallback can copy an isolated cell to a kind-addressed destination that no collection instance reads, while the procedure reports success. Require the existing flow-owner attribution first, or stop null-owner rows for collection kinds.

AGENTS.md reference: AGENTS.md:L12-L15

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 1e169dd: step 2 now requires the existing owner attribution first. Until it runs, a collection flow isolated cells are a stop. BR-17 and V7 carry it.


Generated by Claude Code

Comment on lines +63 to +67
| Default dynamic schedule id | `<orgId>/<userId>/<key>` | Public: the guides, cloud scheduler jobs and the operator step name it |
| The goal | `goals/user-scope/keeps-a-users-data-in-the-org-it-was-saved-in/` | Cited by path |

How each part is escaped in the URL is yours, provided the default parser and both producers
change together and an org or user id containing `/` round-trips.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update the schedule-ID validator for organization IDs

When a valid organization ID contains uppercase characters or punctuation, or when prepending it pushes a previously valid dynamic ID over 128 characters, the dispatch is rejected before the new parser runs. isValidOrgId accepts any nonblank well-formed Unicode string (packages/core/src/types/auth.ts:41-57), but packages/scheduled/src/routes.ts:25-45 accepts only lowercase [a-z0-9:/_-] IDs up to 128 characters and rejects percent encoding. Include that validator in S4 and add boundary cases to V5, otherwise organizations such as Acme.EU cannot use the default schedule helper.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed and fixed in 1e169dd: S4 now includes the dispatch route id validator. Today the pattern rejects even the default org id __fsd_default_org__. V5 adds the default org and an org id with uppercase, . and /.


Generated by Claude Code

@jhoffner

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

You are still using seat. A seat is a worker and we should only have one name for something wherever possible.

…alk the step on Postgres too

- D2/BR-16/BR-17: a deleted session leaves no trace, so the operator vouches none is
  missing (or their records clear every other org); otherwise the cell stops.
- DOCS step 2: a collection flow's null-owner sessions need owner attribution first.
- V7 walks the step on SQLite and Postgres; no unwalked SQL is published.
- S4/V5: the dispatch id validator admits every valid org id, the default org included.
- DECISIONS: why the schedule id, not only the index row, names the org.
- PLAN: why one PR; why the schema check adds no boot failure; notes from review.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Review round 1, pushed as 1e169dd.

Second look.

  1. Copy step walked only on SQLite: folded. V7 now walks it on SQLite and on Postgres (PGlite, as the adapter suite runs it). No SQL is published for a store it was not walked on.
  2. Shared cell, incompatible schemas, boot failure: not a new failure. The registry already compares a pinned flow shared user declarations with every other flow today, without looking at the pin (flow-registry.ts, collectScopeDeclaration). A deployment that boots now passes the same check after. PLAN → At implement time now says so.
  3. Silent empty after upgrade: recorded verbatim in PLAN → Notes from review. The first query in the step already lists uncopied cells, and it can run at any time after the upgrade.
  4. Schedule id vs index only: answered in DECISIONS → Decided, not asked. Every producer reaches the resolver through the one dispatch id, and one person can hold the same key in two orgs. Your point about a host that builds its own dispatch is a note.
  5. Multi-PR: one PR stays. The required org argument breaks every caller at compile time, so the slices cannot merge green apart. PLAN intro says why.
    Architecture notes: both recorded.

Also folded from Codex: D2 now needs the operator to vouch that no session is missing. Fixed inline: owner attribution comes before step 2, and the dispatch id validator is in S4.

Terminology (seat → worker): agreed, and ER-25 says the same. This push does not include it yet. It is still to do on this branch.


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants