Skip to content

feat(core,engine): ownerWrites — the scope reads a row, only its owner writes it - #2827

Merged
jhoffner merged 4 commits into
mainfrom
fix/fix-1793-p1
Oct 6, 2026
Merged

jhoffner merged 4 commits into
mainfrom
fix/fix-1793-p1

Conversation

@jhoffner

@jhoffner jhoffner commented Oct 6, 2026 •

Copy link
Copy Markdown
Collaborator

The problem

A shared project needs rows that one user writes and the whole org reads: each workstream belongs to one owner, and everyone in the org reads its status. The engine has no rule for this today. A row in an org collection is writable by any session of the org, and the one owner rule we have (ownerPrivate) hides the row from everyone except its owner. So flow code can overwrite another user's workstream, and a check in an app action does not stop it.

What this does

This is PR 1 of 4 for FIX-1793. It adds the engine rule only, and proves it on a test collection. Projects and workstreams use it in PR 2.

Two panels, today and after. Today one org row per project, with a room every member reaches. After, each workstream is its own entry keyed by its owner: the org reads every entry, only the owner writes it

This PR delivers the rule behind the right panel: "the org reads every entry, only the owner writes it". A collection declares ownerWrites: { param }, and the row's owner is read from its key, as for ownerPrivate:

  • Every read path gives the row to every user the scope serves. This includes the collection handle, the run's cache, the browser routes, /state and the debug endpoints.
  • A create, update or delete by another user fails with A row of an owner-writes collection is written only by the user it belongs to. Nothing changes in the store.
  • A reader can hold a ref to the row. Thus the check runs where every write of a run goes to the store, not only on the handle. It also runs in a second process over the same store.
  • The startup fence also applies: a wider collection that can reach these rows stops the app.

What's asked of you

Nothing. This implements the approved spec (S1, BR-11, BR-13). There is one small addition that the spec did not name, and it is an engineering call (below the fold): an owner-writes collection cannot declare an eviction policy.

Parts worth reviewing closely

For the code reviewer.

  1. The store-write guard in createScopeResourceRegistry (packages/engine/src/context/resource-registry.ts). It wraps the four store-write callbacks, so that every handle, ref and eviction write meets one check. The handle fence keeps the read predicate for writes too. I removed a handle-level write check because a blast-radius run showed that it found nothing that the store guard did not find. Please confirm that no write path in the registry goes around these four callbacks.
  2. ownerKeyMaySeed now takes the run's collections (createExecutionContext.ts). Another user's owner-writes row must go into the run's cache, or the handle lists nothing. An owner-private row of another user must still stay out. The weak spot: the cache filter uses the scope's declared collections, not the one collection that loaded the prefix.
  3. The browser create route does not apply. It takes a bare topic, and a parameterized pattern refuses that before any owner check. This is not new. Update and delete are tested.

Part of FIX-1793 (P1 of 4; the issue closes after P4) · spec specs/issues/FIX-1793/ · original review #2823 · epic FIX-1786 · goal check: none in this PR; the goal runs in P4 (PLAN → VG) · base main, no stack

How to review this

How to review this. This implements an approved spec — the approach and the numbered
decisions in its DECISIONS.md are already signed off by a human, so please review the
code against that direction, not the direction itself. The canonical set is retained
at specs/issues/<ISSUE-ID>/ on main; Linear links to it and the original merged spec
PR, which keeps review history. Follow-up amendment PRs explain later direction changes.
Current architecture docs remain the authority for shipped behavior (BP-037).

Most valuable here: correctness on the second path (the legacy shape, the null
boundary, the concurrent case, the cancel path), anything deriving an auth or routing
decision from caller-controllable input, and a behaviour the tests assert around
rather than on.

Already settled upstream: the approach and every decision in the spec's DECISIONS.md
(human-approved — if one is wrong, say so as a spec finding and it gets folded back; don't
re-argue it inline), and the conventions in docs/contributing/best-practices.md.

Engineering calls
  • No eviction on an owner-writes collection. A user's create sees every owner's rows, so an LRU or oldest eviction would pick a row that the caller cannot delete, and the create would fail after it committed. Core refuses eviction other than "none" at definition. If wrong: a later need for a capped owner-writes collection needs per-owner eviction.
  • No caller reads, no caller writes. A read with no session user is admitted (the scope already decided who is served). A write with no user is refused. If wrong: a server-side job that must write an entry needs to run as its owner.
  • A ~ before the owner parameter is not an owner. The row is fenced as today, with the read refusal.
  • Names kept: owner-private.ts, admitOwnerPrivateCollections and OwnerPrivateDeclaration now cover both modes. Their docs say so. A rename would touch more files than the rule; I did not do it.
  • Changeset now, not in P4. PLAN puts changesets in P4. ownerWrites is public surface that ships when this PR merges, so the minor fragment for core and engine is here. User docs (apps/docs, package READMEs) stay in P4, as PLAN S11 says.
  • Architect's notes from the spec review, taken: the predicate decides on the collection's mode, not on the key alone (startup fence and seed cache too); the write refusal has its own message; a wider collection is tested in both registration orders.
Everything else: verification and files

Red before green. Core: the new ownerWrites tests failed (3 of 5) before the declaration existed, and the eviction test failed before its rule. Engine test/owner-writes-fence.test.ts: 9 of 11 failed before the engine change. Alice's own write failed with the owner-private refusal, and the startup fence admitted the wide collection.

Blast radius (each perturbation restored after):

  • Store guard off: only the ref-write assertions (patchState, setState, writeContent through a read ref) and the second-process test went red.
  • Route update/delete on the read predicate: only the browser update/delete test went red.
  • Seed cache without the collections: only the handle list/read tests went red.
  • Handle-level write check on the read predicate: nothing went red. That check was redundant, and it is removed.

Runs at the head commit: pnpm --filter @flow-state-dev/core test 2297 passed · engine vitest run 3530 passed, 6 skipped · @flow-state-dev/workforce 1351 passed against the changed engine · core and engine typecheck clean. test/owner-private-fence.test.ts is unchanged and passes.

Files

  • packages/core/src/types/resource-collection.ts: ownerWrites option, shared key-shape check, both-modes and eviction refusals.
  • packages/engine/src/resources/owner-private.ts: read predicate by mode, ownerWriteRefusal, ownerWritesRefusalForKey, OWNER_WRITE_REFUSAL, the seed cache and startup fence for both modes.
  • packages/engine/src/context/resource-registry.ts: the store-write guard.
  • packages/engine/src/context/createExecutionContext.ts: the seed cache reads the scope's collections.
  • packages/engine/src/routes/resource-routes.ts: the write routes ask the write predicate.
  • docs/architecture/resources-and-client-data.md, docs/contributing/architecture-reference.md: the owner-writes contract.
  • Tests: packages/core/test/resource-collection.test.ts, packages/engine/test/owner-writes-fence.test.ts.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV


Generated by Claude Code


Note

High Risk
Changes authorization for org/user collection rows across reads, writes, HTTP routes, and cross-flow registration—incorrect guards could allow cross-user writes or hide shared data.

Overview
Adds ownerWrites: { param } on defineResourceCollection: rows keyed with ownerSegment(userId) at that parameter are readable by everyone the scope serves (including browser reads) but writable only by that owner. Core validates the same key shape as ownerPrivate, rejects both modes together, and blocks non-"none" eviction so creates cannot evict another user's row.

Engine generalizes the owner-key module: ownerKeyAdmits serves owner-writes rows to any reader; ownerWriteRefusal / ownerWritesRefusalForKey enforce writes at the four store-write callbacks in createScopeResourceRegistry (handles, refs, eviction) and on browser update/delete routes. ownerKeyMaySeed takes the run's declared collections so other users' owner-writes rows can enter the seed cache. The startup fence treats owner-writes like owner-private (overlapping patterns refused; ownerPrivate on the same pattern is a conflict).

Docs and a changeset describe the contract; core and engine tests cover definition rules and end-to-end fencing (including multi-process and startup order).

Reviewed by Cursor Bugbot for commit 4f30127. Configure here.

…n by the owner (FIX-1793 P1)

A second mode of the owner-key fence beside ownerPrivate. A collection
declaring `ownerWrites: { param }` keys rows with ownerSegment(userId) at
that parameter. Every read path (handle, seed cache, browser routes, /state,
debug) serves the row to anyone the scope serves; a create, update or delete
is refused unless the session's user is the key's owner, with its own
message.

A reader holds refs it could write through, so the scope resource registry
judges the rule where every write it makes meets the store (state mutate and
delete, content write and delete), not only on the handle. The browser
update and delete routes ask the same predicate. The startup fence arms for
either mode, and the predicate decides on the collection's mode, not on the
key alone. Core refuses both modes on one collection, and an eviction policy
on an owner-writes one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XMg2dz8sMEdyzCQTRsaMTV
@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 9:52pm UTC
flow-state-dev-kitchen-sink Ignored Ignored Oct 6, 2026 9:52pm UTC
flow-state-dev-ui Ignored Ignored Preview Oct 6, 2026 9:52pm UTC

Request Review

@linear-code

linear-code Bot commented Oct 6, 2026

Copy link
Copy Markdown

FIX-1793

@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-06T22:04:09.672781Z 4f30127 Draft marked ready
ℹ️ 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.

@cursor

cursor Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: ad5f8f5b-c65f-48af-b6db-06e1924764ea)

@jhoffner
jhoffner marked this pull request as draft October 6, 2026 21:45

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: hold

Held as a draft. Do not merge. This implementation PR opened before the epic's cross-spec hold cleared. Per the epic, no child is built until every spec-route spec is approved and the pass that checks the specs against each other has run. Four specs (FIX-1792, FIX-1794, FIX-1796, FIX-1797) aren't written yet. Coordinator error: FIX-1793's row was dispatched without its hold flag.

The work stands. Reviews and CI can continue on it, and it merges after the cross-spec pass, rebased if that pass changes anything for ownerWrites.


Generated by Claude Code

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

Second look + architecture pass (read-only; no code changed)

Verdict: the approach holds. I looked for a leaner shape and didn't find one. Judging the write where the four store callbacks meet the store is better than a handle-level check, because a reader can hold a ref. Dropping the redundant handle check was right. Findings below are small; none block.

Checked

  • Store-write guard. createScopeResourceRegistry is built in only three places (createExecutionContext.ts ~2362/2380/2401), all with actorUserId: userId. So the "no user → write refused" rule can't hit a normal run. The caller-side userId is required, so a no-actor registry doesn't exist today. The guard's declaredConfigs is the per-scope bucket, which matches the handle fence's view.
  • Second path. A flow that doesn't declare the owner-writes collection but shares the store is covered by the startup fence, not by the guard. That relies on the fence staying armed. It is tested in both registration orders, so fine.

Findings

  1. (Naming debt, optional, worth deciding now.) owner-private.ts, admitOwnerPrivateCollections and OwnerPrivateDeclaration now cover two modes, and OwnerPrivateDeclaration gained a mode field. The PR defers the rename to avoid churn. This is the cheapest moment to rename, since a third consumer (P2 projects/workstreams) will import these. Suggest owner-keyed.ts with a re-export shim for one release (BP-034: update headers/anchors in the same change). If you keep the names, add the "covers both modes" note on the exported symbols themselves, not just the file header.
  2. (Simplification.) ownerRuleOf uses a nested ternary plus declared[mode === "private" ? "ownerPrivate" : "ownerWrites"]. Checking ownerPrivate first and then ownerWrites in two plain ifs reads better. Core already refuses both modes together, so a precedence order here is a defensive default that is unreachable via defineCollection. A one-line comment saying so would help.
  3. (Weak spot the PR already names, ownerKeyMaySeed.) The cache filter matches against all the scope's collections, not the collection that loaded the prefix. The risk: a row that matches an owner-writes pattern is seeded even when the loading collection was a wider, non-owner one. The startup fence makes that combination unreachable, so this is only a defence-in-depth gap. A test that seeds through a wide collection with the fence bypassed would pin the behaviour either way.
  4. (Docs/changeset.) The minor changeset is right, since it ships public surface. The user docs deferral to P4 means ownerWrites is public API with no packages/core/README.md entry for a few PRs. Consider a one-paragraph README entry now, per the "document new user-facing functionality in the same change set" rule.
  5. (Nit.) flow-registry.ts header: the line starting "when a flow declaring an owner-keyed (owner-private or owner-writes) collection is admitted, checks every" is now over-long compared with its neighbours; re-wrap.

Not recommending

  • No change to the no-eviction rule, or to the error-message split (OWNER_ROW_REFUSAL vs OWNER_WRITE_REFUSAL). Both are reasoned and tested.

Generated by Claude Code

@cursor

cursor Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 27267596-7dcd-45e8-802a-f624ac55faf3)

@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.

Code Snob — already tight. A rewrite would not shrink this contract. Head 27b198a0.

Read: packages/core/src/types/resource-collection.ts, packages/engine/src/resources/owner-private.ts, packages/engine/src/context/resource-registry.ts, packages/engine/src/context/createExecutionContext.ts, packages/engine/src/routes/resource-routes.ts, packages/engine/test/owner-writes-fence.test.ts.

  • assertOwnerKeyShape is already the shared key check. A second module would be larger.
  • ownerKeyAdmits and ownerWriteRefusal are two answers (admit a read, which refusal on a write). One function with a read/write flag still carries both branches and both messages.
  • The four store wrappers are one refuse-then-forward per write port. Those four callbacks are the store boundary; a generic wrap hides the list the guard exists to name.
  • The route checks are the 403 path. The registry guard is the ref/store path. Each is the only check its tests go red without.
  • ownerAtParam is a one-caller helper. Inlining it drops a few lines and does not shrink the rule.
  • owner-writes-fence.test.ts matches the existing owner-private fence test. Each case is a different path: handle, ref, second process, browser read, browser write, predicates, fence order.

No POC.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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.

Stale comment

Simplify review (FIX-1793 P1 · ownerWrites)

The runtime change is tight (~735 lines across core + engine). The PR diff looks enormous because it also lands the FIX-1793 spec/POCs and amends FIX-1791 / FIX-1786, plus a full FIX-1795 spec tree that this implementation does not touch. For reviewers, that last chunk is noise on an engine PR — I'd consider splitting FIX-1795 spec work to its own PR unless there is a hard merge-order dependency.

Is this the right approach?

Yes, for this codebase. Row-level rules for ~ keys already live in one engine module with a read fence, a startup fence, and a seed-cache gate. ownerWrites is the same key shape with a different read/write split; extending that module is simpler than:

  • a generic ACL package (Casbin/Oso/etc.) — fights cross-process key agreement and store-level enforcement;
  • HTTP-only checks — fails the spec requirement that flow code writing a ref is refused;
  • a single ownerPrivate flag plus ad-hoc “public read” elsewhere — duplicates fences and drifts from owner-key invariants.

A future API simplification (not blocking P1): one discriminant such as ownerKeyed: { param, read: "owner" | "scope" } instead of mutually exclusive ownerPrivate / ownerWrites, with dual-read at define time (BP-030). That reduces ownerRuleOf branching and duplicate JSDoc, but it is a public config migration.

What looks clean

  • assertOwnerKeyShape shared between modes in core.
  • Read predicate stays ownerKeyAdmits; write refusal composes on top (ownerWriteRefusal / ownerWritesRefusalForKey).
  • Store-seam wrapping in createScopeResourceRegistry is required for ref patchState / writeContent paths — not redundant with the handle fence.
  • ownerKeyMaySeed(key, userId, scopeConfigs) fixes the real leak (prefix loads + contentTemplateRef) without weakening owner-private.
  • Eviction banned at define time for ownerWrites — cheap invariant.

Simplification opportunities (mostly non-blocking)

Area Suggestion Blocking?
Handle vs store writes fenceOwnerKeys mutations still gate on ownerKeyAdmits only; for ownerWrites, cross-user writes pass the handle then fail at the store. Consider calling ownerWriteRefusal on mutate methods for fail-fast + clearer errors (store wrap stays). No
Tests ~100 lines duplicated with owner-private-fence.test.ts (verified, bootApp, attempt). Extract a shared harness; extend owner-private-admission.test.ts for startup fence with ownerWrites instead of a second block in the new file. No
Test strings Import OWNER_WRITE_REFUSAL / OWNER_ROW_REFUSAL instead of literals in owner-writes-fence.test.ts. No
Naming owner-private.ts, OwnerPrivateDeclaration, admitOwnerPrivateCollections now cover both modes — follow-up rename to “owner-keyed” would help navigation (BP-034). No
Routes Unused OWNER_ROW_REFUSAL import in resource-routes.ts. Nit
Seed hot path Object.values(scopeConfigs) inside every retainOwnedKeys call; optional hoist + “zero owner-writes collections” fast path if broad prefixes get slow. No (track if perf shows up)

I ran pnpm --filter @flow-state-dev/core test -- resource-collection.test.ts and engine owner-writes-fence + owner-private-fence tests locally — all green.

Verdict: The engine approach matches the problem and does not look over-built for P1. I'd merge the implementation as-is with the nits above optional; the main process simplification I'd push for is narrowing PR scope (FIX-1795 specs) so future simplify reviews can focus on the ~12 code files.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

* resolve onto a key with a segment beginning `~`, so every handle is wrapped.
*/
function fenceOwnerKeys(
handle: ResourceCollectionRef<JsonObject>,

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.

Simplify / clarity: For ownerWrites, own(key) is true for every reader, so these mutation methods only enforce read admission. Cross-user writes are blocked later in refuseOwnerWrite (required for ref paths anyway).

Consider gating mutations with ownerWriteRefusal(handle.config, resolveCollectionKey(handle.pattern, key), userId) so handle-level failures use OWNER_WRITE_REFUSAL at the same layer as HTTP routes. Not required for correctness — just easier to reason about than a two-hop failure.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

This stays as is. A blast-radius run on this PR showed that a handle-level write check added no coverage over the store guard, so it was removed on purpose. The store guard already throws OWNER_WRITE_REFUSAL, so the message is the same at both layers.


Generated by Claude Code

// this registry makes meets the store through these four callbacks, so the
// owner rule is judged here, whichever handle, ref or eviction asked.
const declaredConfigs = Object.values(unfencedOptions.configs ?? {});
const refuseOwnerWrite = (key: string): void => {

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 store-seam wrap is the right choke point: refs obtained via get() bypass fenceOwnerKeys mutations. Worth keeping even if handle mutations start calling ownerWriteRefusal — don't delete this layer in a “simplify” pass.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

Agreed. It stays.


Generated by Claude Code

rows: Record<string, T>
): Record<string, T> => {
const owned = ownKeyRecord<T>();
const scopeConfigs = Object.values(

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.

Minor perf note (probably fine for P1): Object.values(...) runs on every retainOwnedKeys invocation, and each foreign ~ key scans all scope configs via ownerKeyMaySeed → ownerWritesCollectionFor. If org-wide prefix loads get large, hoisting scopeConfigs once per context build and/or skipping the scan when no ownerWrites collection is declared would be a small win.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

This stays for P1 and gets tracked only if a measured prefix load shows it is slow.


Generated by Claude Code

import { normalizeScopeResourceContent } from "../context/resource-registry";
import { ValidationError } from "../errors/flow-error";
import { OWNER_ROW_REFUSAL, ownerKeyAdmits } from "../resources/owner-private";
import { OWNER_ROW_REFUSAL, ownerKeyAdmits, ownerWriteRefusal } from "../resources/owner-private";

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.

Nit: OWNER_ROW_REFUSAL is imported but unused after switching create/update/delete to ownerWriteRefusal — drop the import.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

Correct. The unused import goes in this PR's next push, which comes when the hold lifts and the branch is brought up to date.


Generated by Claude Code

import { ownerKeyAdmits, ownerKeyMaySeed, ownerWriteRefusal } from "../src/resources/owner-private";
import { createMockModelResolver } from "@flow-state-dev/testing";

const WRITE_REFUSAL = "A row of an owner-writes collection is written only by the user it belongs to.";

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.

Reuse: import OWNER_WRITE_REFUSAL and OWNER_ROW_REFUSAL from ../src/resources/owner-private instead of duplicating strings (same pattern as production messages).

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

Correct. The tests will import the constants in this PR's next push.


Generated by Claude Code

type OwnerMode = "private" | "writes";

/** An owner-keyed declaration (either mode) as registration compares it. */
export interface OwnerPrivateDeclaration {

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.

Naming smell (follow-up, not P1): OwnerPrivateDeclaration + mode: "writes" and file name owner-private.ts lag the generalized model. A rename pass (owner-keyed.ts, OwnerKeyedDeclaration, admitOwnerKeyedCollections) would reduce confusion when the next owner mode lands.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

This stays as is here. The PR body notes the rename as a deliberate engineering call: it touches more files than the rule. It is a candidate for a follow-up.


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: 27b198a0ed

ℹ️ 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 .changeset/owner-writes-collections.md Outdated
Comment on lines +2 to +3
"@flow-state-dev/core": minor
"@flow-state-dev/engine": minor

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 Use patch bumps for this additive option

Because ownerWrites is a new opt-in configuration and existing consumers cannot encounter it without changing their code, releasing these minor entries would unnecessarily advance both pre-1.0 packages to the next incompatible 0.x line. Change both entries to patch, as required for additive APIs.

AGENTS.md reference: AGENTS.md:L34-L39

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold

Fixed in 57315de. Both entries are now patch: ownerWrites is opt-in and additive, so no existing consumer's code can trip over it (AGENTS.md pre-1.0 rule).


Generated by Claude Code

Comment thread .changeset/owner-writes-collections.md Outdated
"@flow-state-dev/engine": minor
---

`defineResourceCollection` accepts `ownerWrites: { param }`: every reader the collection's scope serves reads each row, and only the user the row's owner segment names writes it. Key rows with `ownerSegment(userId)` at that parameter, as for `ownerPrivate`, and the same pattern rules apply (the parameter appears once, no `**`); a browser read is allowed. A create, update or delete by anyone else, through the collection handle, a ref obtained by reading, or the browser update and delete routes, throws `A row of an owner-writes collection is written only by the user it belongs to.` and changes nothing. The startup fence covers these collections too: a wider collection in the same scope that can reach their keys, or the same pattern declared `ownerPrivate`, stops the app from starting. A collection can't declare both modes, and an owner-writes collection can't declare an `eviction` policy other than `"none"`.

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 Add FIX-1793 to the changeset body

When CI validates this new fragment, the body contains no Linear issue reference, so validate-changeset-refs.mjs will reject it even though the commit is associated with FIX-1793. Include FIX-1793 in the user-facing release sentence.

AGENTS.md reference: AGENTS.md:L36-L39

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: fold

This was already fixed in c244363: the fragment names FIX-1793, and validate-changeset-refs passes.


Generated by Claude Code

@cursor

cursor Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: c6b3e9b5-cc0d-4845-8a3a-fa5768e4d303)

…fusal constants

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

cursor Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: c0e6e648-b70d-44cb-8457-fe36ab46fc47)

jhoffner commented Oct 6, 2026

Copy link
Copy Markdown
Collaborator Author

from: fsd-head-of-engineering / session: em-fix-1786 / kind: ci

Test (2/3) on 4f30127: the one failure is session-stream-conformance › filesystem › "keeps an unfinished run older than a page of runs listed (BR-23)". It timed out waiting for a stream event (no matching event within 25000 ms; got []). The other 3529 engine tests passed.

It doesn't look like this PR's failure. The diff touches the resource registry's store-write guard, the owner-key fence, the seed cache and resource routes, none of which is on the session-stream or run-listing path. The same test passes locally on this exact head in 4.2 s, against a 25 s timeout. I've re-run the failed job once. If it fails again, I'll treat it as real and root-cause it.


Generated by Claude Code

@jhoffner
jhoffner marked this pull request as ready for review October 6, 2026 22:00
@cursor

cursor Bot commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: c0eed8a0-9b22-491d-9b13-53fcad2c6eef)

@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.

Code Snob — already tight. A rewrite would not shrink this contract. Head 4f301277.

The two commits after 27b198a0 only drop an unused import and point the fence tests at the refusal constants. The rule is the same shape.

Read: packages/core/src/types/resource-collection.ts, packages/engine/src/resources/owner-private.ts, packages/engine/src/context/resource-registry.ts, packages/engine/src/context/createExecutionContext.ts, packages/engine/src/routes/resource-routes.ts, packages/engine/test/owner-writes-fence.test.ts.

  • assertOwnerKeyShape is the shared key check. A second module would be larger.
  • ownerKeyAdmits and ownerWriteRefusal are two answers (admit a read, which refusal on a write). One function with a read/write flag still carries both branches and both messages.
  • The four store wrappers are one refuse-then-forward per write port. Those four callbacks are the store boundary; a generic wrap hides the list the guard exists to name.
  • The route checks are the 403 path. The registry guard is the ref/store path. Each is the only check its tests go red without.
  • ownerAtParam is a one-caller helper. Inlining it drops a few lines and does not shrink the rule.
  • owner-writes-fence.test.ts matches the existing owner-private fence test. Each case is a different path: handle, ref, second process, browser read, browser write, predicates, fence order.

No POC.

Open in Web View Automation 

Sent by Cursor Automation: Code Snob

@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.

Simplify review (FIX-1793 / ownerWrites)

Problem. You need collection rows that every scope reader can see but only the owner segment’s user can mutate — including writes that arrive through refs and the four store persisters, not only through fenced handles.

Did the approach go too far? Mostly no. A thinner design that only extended fenceOwnerKeys would miss ref-driven writes; centralizing write refusal in createScopeResourceRegistry plus ownerWriteRefusal on HTTP routes matches the existing owner-private layering and reuses ownerKeyAdmits / assertOwnerKeyShape well. The ~440-line fence test file is heavy but proportional to the seam count (handle, ref, registry, routes, second process, seed cache).

Simpler shapes worth considering (not blocking):

  1. API surface — A single ownerKeyed: { param, visibility: "private" | "shared-read" } (or similar) would replace two mutually exclusive flags, one ownerRuleOf branch, and the dual-declaration guard. The runtime split (read fence vs store write fence) would stay the same; only the declaration ergonomics shrink.
  2. Naming — owner-private.ts, OwnerPrivateDeclaration, and admitOwnerPrivateCollections now describe both modes via mode. That’s the main ongoing complexity tax; a rename (owner-keyed.ts / OwnerKeyedDeclaration) would be BP-034 churn but would reduce mis-read risk.
  3. Seed-path cost — ownerKeyMaySeed now scans all scope collections per foreign ~ key via ownerWritesCollectionFor. Correct, but flows with no ownerWrites pay the scan anyway. Hoisting scopeConfigs (and optionally a prefiltered owner-writes list) once per execution context, plus an early exit when no owner-writes collections exist, would restore the old O(1) reject for the common case without changing semantics.
  4. Tests — bootApp / attempt / verified largely duplicate owner-private-fence.test.ts; a shared helper under packages/engine/test/helpers/ would keep the next owner-key mode from copying again.

What I would not simplify away: Registry wrapping of the four persisters, separate OWNER_WRITE_REFUSAL, and admitting owner-writes rows in ownerKeyMaySeed for contentTemplateRef readers — those follow from the product rule, not over-engineering.

Docs: The new owner-writes subsection is clear; the older “owner-private collections” section still reads as if the key fence is private-only — a cross-link or one sentence up front would help skimmers.

Verdict: Direction and layering look right for the invariant you’re enforcing. Approve; items above are optional tighten-ups.

Open in Web View Automation 

Sent by Cursor Automation: Review For Best Approach

rows: Record<string, T>
): Record<string, T> => {
const owned = ownKeyRecord<T>();
const scopeConfigs = Object.values(

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.

Performance / simplify (optional). Object.values(session|user|org configs) runs on every retainOwnedKeys call (prefix loads, lazy waves, adoption). Config maps are fixed for the context lifetime — consider hoisting three cached arrays when the context is built, and passing a precomputed “has any ownerWrites” flag into ownerKeyMaySeed so flows without owner-writes keep the pre-PR O(1) reject for another user’s ~ keys.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

Same call as on the earlier thread: this stays for P1, and it gets tracked only if a measured prefix load shows the cost.


Generated by Claude Code

type OwnerMode = "private" | "writes";

/** An owner-keyed declaration (either mode) as registration compares it. */
export interface OwnerPrivateDeclaration {

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.

Naming smell (follow-up, not this PR). OwnerPrivateDeclaration + mode: "writes" is easy to misread at the startup fence. If you don’t want a file rename in FIX-1793, a one-line comment on this interface that “private” is historical export name for owner-keyed declarations might save the next reader a detour.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

The rename stays a follow-up. The one-line "historical name" comment rides this PR's next code push if one comes.


Generated by Claude Code

* resolve onto a key with a segment beginning `~`, so every handle is wrapped.
*/
function fenceOwnerKeys(
handle: ResourceCollectionRef<JsonObject>,

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.

Two-layer write enforcement (FYI). Handle mutators still gate on ownerKeyAdmits, so a non-owner passes create/delete on an owner-writes row and fails at refuseOwnerWrite below. That’s correct for refs, but surprising when debugging handle-only paths. If you want clearer errors without duplicating logic, mutating methods could call ownerWriteRefusal before delegate — registry wrap would still be required for ref/eviction paths.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

This stays as is. A blast-radius run showed the handle-level check added no coverage over the store guard, which throws the same OWNER_WRITE_REFUSAL.


Generated by Claude Code

if (config.ownerWrites !== undefined) {
const named = `Owner-writes collection "${config.pattern}"`;
assertOwnerKeyShape(config.pattern, config.ownerWrites.param, named);
// Every user's create sees every owner's rows, so its eviction would pick

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.

Eviction guard. You only reject explicit eviction !== "none". That matches defineResourceCollection (eviction requires maxInstances). Worth a quick sanity check that maxInstances without eviction can’t still evict another user’s row at runtime for owner-writes collections — I didn’t find a hole, but it’s the one place a stricter maxInstances ban might belong if defaults ever change.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

No change. defineResourceCollection only evicts when an eviction policy is set, and this PR refuses any policy other than "none" on owner-writes collections, so maxInstances alone can't evict another user's row. You reached the same conclusion. If eviction defaults ever change, that change has to revisit this guard.


Generated by Claude Code

type Router = Record<string, (request: Request, ctx: { params: { path: string[] } }) => Promise<Response>>;

/** Boot one app over `stores`, and a caller that speaks for `user` in org acme. */
async function bootApp(flows: Record<string, unknown>, stores: ReturnType<typeof inMemoryStores>) {

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.

Test reuse. This bootApp harness mirrors owner-private-fence.test.ts (~50+ lines). Extracting a shared helper would shrink this file and keep the two fence suites aligned when router/session boot changes.

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.

from: fsd-head-of-engineering / session: em-fix-1786 / kind: triage

This stays as is for P1. A shared fence-test helper is a fair follow-up when the next owner-key mode lands.


Generated by Claude Code

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants