diff --git a/spec/_projects/framework-simplification-and-cleanup/BUSINESS-RULES.md b/spec/_projects/framework-simplification-and-cleanup/BUSINESS-RULES.md new file mode 100644 index 0000000000..c40c90ba3a --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/BUSINESS-RULES.md @@ -0,0 +1,36 @@ +# Rules — Framework simplification & cleanup + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · **Rules** · [Plan](PLAN.md) + +What every epic under this project obeys. Each rule has **exactly one owner**, the epic that +implements and proves it; the others inherit it. A rule with two owners is a seam; a rule with none +is a wish. + +| | Rule | Owner | Checked where | +|---|---|---|---| +| **PR-1** | When an epic's docs show how a host is mounted or called over HTTP, then they teach a verified caller; a caller-typed `userId` appears only as the named local-development escape, never as a shipped mode | FIX-1503 | FIX-1503's consumer cutover, over every docs example it names; FIX-1637's own docs review for any page it adds | +| **PR-2** | When an epic removes a published root export, then the release carries it in the one removed-root-exports summary line, with the total count, never a name per export | FIX-2447 | j5 in the adopter-goal check: the line on every run, the exact count on the Version Packages PR only | + +**PR-1 is FIX-1503's ER-10, raised to this altitude** because a sibling now writes the pages it +governs: FIX-1637's config matrix covers the host mount for webhooks, cron and event ingress. +Whichever lands second reads the other's pages ([Plan](PLAN.md) → seams). + +**PR-2 is owned by a wrapped epic.** Clean SDK built and proved it at closure +([Decisions](DECISIONS.md) → 8); every later epic that drops a root export inherits it and edits no +changeset until release. Folding j5 into the CI checks after release moves to +[FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739), under the docs revamp. The repo-wide grounding, +including BP-031 on caller input, binds every epic already and is not restated here. + +**No epic may:** + +- **Collapse a block kind or a state scope, or deprecate scope state.** Decided once, twice + ([Decisions](DECISIONS.md) → 1, 2). +- **Merge the two durable-storage primitives**, or re-derive the rejected splits by scope range or + by persistence (→ 3). +- **Remove capabilities, skills, tools, `ui` or thought-fabric**, or cut the sequencer's public + surface (→ 4, 5). +- **Make client data visible by default** (→ 6). +- **Alias a moved or renamed published export**, or keep it reachable from its old path (→ 7). +- **Drop the install docs' `--allow-build=better-sqlite3` flag** before FIX-2737 lands (→ 9). +- **Add a capability under this project's name.** A cleanup that needs a new feature files it + where features live; this is the fence in the [territory](SPEC.md). diff --git a/spec/_projects/framework-simplification-and-cleanup/DECISIONS.md b/spec/_projects/framework-simplification-and-cleanup/DECISIONS.md new file mode 100644 index 0000000000..e98d463a21 --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/DECISIONS.md @@ -0,0 +1,86 @@ +# Decisions — Framework simplification & cleanup + +[Spec](SPEC.md) · **Decisions** · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +Calls that bind **more than one epic**. A call that touches one epic belongs to that epic's own +`DECISIONS.md`; absorbing it here would make this a design nobody signed off. + +## Cards + +None yet. The calls that bind more than one epic so far were each settled once by the owner and +are not live forks, so they sit under *decided once* below; the shared seams are in +[Plan](PLAN.md) and the rules in [Rules](BUSINESS-RULES.md). The first live call a second epic +would otherwise have to make again gets card PD-1. + +## Decided once + +Answered at project altitude, so a later epic reads the answer instead of re-litigating it. Each +carries where it was settled. + +1. **The block kinds are not collapsed.** Four when the review was written, five since the + evaluator joined. The review proposed merging them; the validation pass went to the code and + retracted it. *From the project's original description.* +2. **The state scopes are not collapsed, and scope state is not deprecated.** The review + retracted the collapse. FIX-1157 then tested the narrower version, deprecating session, user + and org state, and abandoned it: request scope keeps the same machinery anyway, so the removal + buys about a third of the prize while deleting the client-facing half. The trial removal of org + state was closed unmerged. *Validation pass; FIX-1157, Aug 20.* +3. **The two durable-storage primitives stay two: symmetry, not merger.** Where scope state and + resources can offer the same verb without importing each other's semantics, they do. Where they + must differ, the reason lives in one place. **Rejected, do not re-derive:** splitting them by + scope range (request scope is multi-writer), and splitting them by persistence (both persist). + The two conflict-retry drivers cannot be shared, only eliminated, because the stores model + deletion differently. *FIX-1157, wrapped Aug 28.* +4. **Capabilities, skills, tools, `ui` and thought-fabric are not removed.** Retracted by the + validation pass. *Original description.* +5. **The sequencer's public surface is not cut.** The review named two exceptions: `validate()`, + which is still on the surface, and `background()`, since renamed `sideChain` under its own + spec. *Original description; the rename settled separately.* +6. **Client data is private by default.** "Expose everything, with a hidden list" was rejected; + a scope names what crosses to the client. *Original description.* +7. **No backward-compat aliases.** A moved or renamed published export's old path is removed, not + aliased or re-exported. This is BP-034 held at scale: the owner made the call for clean SDK + ("break, no backward-compat code") and it applied to every export the epic moved. Binds any + later epic that moves or renames a published export, vocabulary's renames included. + *FIX-2447, wrapped Nov 15.* +8. **The removed-root-exports release note is one summary line with the count**, not a name per + export. The owner's call. The adopter-goal check's upgrade journey, j5, confirms the line is + present on every run and checks the exact count only on the Version Packages PR + (`changeset-release/main`). So an epic that drops a root export from here on edits no changeset + until release; the count is reconciled there ([Rules](BUSINESS-RULES.md) → PR-2). + *FIX-2447 closure, FIX-2562.* +9. **The install docs keep pnpm's `--allow-build=better-sqlite3` flag until + [FIX-2737](https://linear.app/fixpoint-labs/issue/FIX-2737) lands**, moving store-sqlite to + `node:sqlite` so an install needs no native build. The owner's call. Binds the docs revamp, + which rewrites those pages: the flag goes when FIX-2737 merges, not before. *FIX-2447 wrap.* +10. **Removing exports from a package root is a `minor` bump before 1.0**, under BP-022. *FIX-2447.* + +The source reports the original description names, a team synthesis and a validation synthesis +under `docs/internal/review*`, are not on `main` today. Where they disagreed, the validation +synthesis won; the list above is what it concluded. + +## Open + +### Does this project end at the public release, or stay open as the standing cleanup bucket? + +**Plain terms.** This project was a three-week pass with a May 22 target. That pass is done bar +two package extractions. Since August it has become where "FSD says one thing, does another" fixes land: twelve +epics, 100 open issues, 68 under no epic. Nothing says when it is finished, so no epic can be +tested against a finish, and the bug count in [the outcome](SPEC.md) has no date to reach zero by. + +**The trade-off.** Ending it at the public release gives it a finish line and forces one triage of +the 68: each either ships before release, moves to Public Launch's hard gates, or moves to a +post-release project. That costs a triage pass and some issues changing project. Keeping it as a +standing bucket costs nothing now, but it can never be called done, and it becomes a label. + +**My recommendation.** End it at the public release. FIX-1127 made the case in August that the surface is +cheapest to make true before people build on it; the public release is the last point where that +holds, and after it each fix here is a breaking change for somebody outside. Set the Linear target to the release date once there is one; Public Launch +has none yet. + +**What would change my mind.** If the release is a quarter or more away, tying this project to it +is a bucket with a date on it, and a narrower finish ("the 28 bugs") is the better line. Or if +cleanup is already tracked another way you would rather keep. + +**What being wrong costs.** Low and reversible: a date and a label. The costly failure is the +other one, a project nobody can ever call done. diff --git a/spec/_projects/framework-simplification-and-cleanup/PLAN.md b/spec/_projects/framework-simplification-and-cleanup/PLAN.md new file mode 100644 index 0000000000..a065724941 --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/PLAN.md @@ -0,0 +1,67 @@ +# Plan — Framework simplification & cleanup + +[Spec](SPEC.md) · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · **Plan** + +Sequencing, not building. What order the epics run in, what each hands the next, and what is +deliberately not next. Each epic's own plan owns its checks. + +![The arc: twelve epic lanes from Aug 10 to Nov 15. Declared surface ran inside one day, Aug 12, and is done. Durable storage ran Aug 13 to Aug 28 and is done. Verified identity's direction merged Sep 22 and its bar runs to the now line with its one child not started. Keeping flows alive's direction merged Sep 29 and its bar runs to the now line with four of eight children done. One owner per fact, filed Oct 15, and durable agents, filed Oct 24, have no bar: both are in Backlog, though some of their children are done. The mechanism sweep ran Oct 30 to 31 and is done. Clean SDK's direction merged Nov 5 and it wrapped Nov 15. Vocabulary, feature kits and docs revamp each had their direction merged within a day or two of filing, Nov 7, Nov 9 and Nov 12, and run to the now line. Kit reads in the apps was filed Nov 11 and has no bar.](figures/arc.svg) + +Two short closed bars in August, two long live ones since late September, then eight epics filed +in four weeks. Clean SDK is the first of those to close a long bar: ten days from direction to +wrap. Three more run behind it, each approved within two days of filing. Verified identity's bar +is still direction only, eight weeks on, and two Backlog epics have children landing with no +approved direction above them. + +## What each epic consumes and releases + +| Epic | Consumes | Releases | +|---|---|---| +| **declared surface** · FIX-1127 | A verification pass over this project's then 29 open issues, which closed 12 as shipped or superseded | **Released Aug 12:** a getting-started path that runs, flow options that are honoured or refused, declarations that stay on their block. Eight follow-ups filed | +| **durable storage** · FIX-1157 | Both storage primitives and their two conflict-retry drivers | **Released Aug 28:** increment and append on resources, one mutation contract, a delete that stays deleted; the write contract given one home in the docs. Decided once 2 and 3 | +| **verified identity** · FIX-1503 | Principal-owned org identity, already done outside any epic | A host-proof token mint, `/api/flows` verified by default, the two open reads closed, every HTTP consumer cut over, proved by the pentest Lab. **Not** login | +| **keeping flows alive** · FIX-1637 | The existing webhook, schedule and dispatch docs; Public Launch's queue-host session fence, pointed to and not moved | One guide, one glossary, one config matrix. **Not** a runtime change and **not** a new product noun | +| **clean SDK** · FIX-2447 | A review of what the Oct 16–31 window put on the public surface; every package root | **Released Nov 15:** curated package roots with no aliases, the adopter-goal check on installed tarballs passing on main `4d97cdc9a` with one expected-fail cell, `first-hour.quickstart`. Decided once 7 to 10, and PR-2. **Not** released: the quick start passing, 31 old `stores` lines, j5 in CI, all handed to [FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739) | + +## Coordination seams + +- **Verified identity → keeping flows alive: one set of host-mount pages.** The config matrix + teaches how a host is mounted for webhooks, cron and event ingress; the identity cutover changes + how an HTTP caller proves who it is. Whichever lands second reads the other's pages, and + [PR-1](BUSINESS-RULES.md) holds both. If the guide ships first, the cutover's docs sweep must + include it. +- **Clean SDK → docs revamp: three leftovers in one issue.** [FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739), + owned by FIX-2696, flips `first-hour.quickstart` to pass once the rewritten quick start uses the + `flows` list form, removes the 31 old `stores` lines, and folds j5 into the CI checks after + release. The revamp also inherits decided once 8 and 9: one summary line for removed exports, + and the install flag until FIX-2737. +- **Feature kits → kit reads in the apps.** FIX-2683 deletes the Teammates and Shift Manager read + models only once FIX-2618's views, reads by scope, notice ids and kits have shipped. +- **Keeping flows alive → Public Launch: a pointer, not a dependency.** The guide documents the + queue-host fence on delivering into an existing session honestly and links the fix in the hard + gates epic. It never waits on that fix and never absorbs it. + +## Before the epics + +The original pass ran in May as 19 issues in three tiers: cleanup, editorial, refactors. **16 done, +1 canceled, 2 open.** Both open ones are package extractions: the model layer, still here and +waiting on the model-layer complexity question, and voice, since moved to the Realtime Voice +project. The tier structure is not carried forward; later work runs as epics or as single issues. + +**68 open issues sit under no epic**, 24 of them bugs, among them clean SDK's handoff and +follow-up, FIX-2739 and [FIX-2737](https://linear.app/fixpoint-labs/issue/FIX-2737). The two largest clusters are resource-store +correctness, where stores disagree or silently discard a write, and model strings. Neither has an +epic yet. + +## What is deliberately not next + +- **An epic for every open issue.** A single bug with a known fix takes the bug route on its own; + an epic is for a set sharing one objective. +- **The model-layer extraction** before the question of how much of that layer is essential is + answered. +- **Session delivery on a queue host.** It is Public Launch's hard gate; this project only + documents the fence. +- **A heartbeat or keep-alive product.** Keeping flows alive teaches what exists. +- **Writing the task-collection methods once** + ([FIX-2462](https://linear.app/fixpoint-labs/issue/FIX-2462)), taken out of clean SDK into + Backlog until it is settled whether workforce keeps its own task-collection methods. diff --git a/spec/_projects/framework-simplification-and-cleanup/SPEC.md b/spec/_projects/framework-simplification-and-cleanup/SPEC.md new file mode 100644 index 0000000000..f0cc9caede --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/SPEC.md @@ -0,0 +1,83 @@ +# Framework simplification & cleanup — what FSD says is what it does + +**Spec** · [Decisions](DECISIONS.md) · [Rules](BUSINESS-RULES.md) · [Plan](PLAN.md) + +This project began in May as an editorial and structural pass driven by a first-principles +review: keep the power, tighten the first hour. That pass is done bar two package extractions. +Since August it has been where FSD fixes the places its surface says one thing and does another, +or offers two of something where a builder needs one, while FSD is pre-1.0 and ahead of its +public release, when a fix breaks the fewest people. + +## The outcome + +| | | +|---|---| +| **Winning when** | A builder can take every FSD doc, type and default at its word: nothing declared is silently dropped, no job makes them choose between two primitives, a reachable host is not open by default, and a common job such as keeping a flow alive has one published path. Nothing a builder can do today is cut to get there | +| **The read** | Open issues labelled **Bug** in this project. Almost every one is a statement the runtime contradicts. **28 today; zero is done.** It rises when a bug is found as well as falls when one is fixed, so read it beside what was filed that week | +| **Now** | 4 epics done · 5 in flight · 3 filed, not started. 100 open issues, **68 under no epic**. No finish date: the Linear target, May 22, passed with the original pass ([Decisions](DECISIONS.md) → Open) | +| **Kill line** | If a surface cut here keeps coming back within a release because builders needed it, the project is aimed at the wrong thing. What changes is layering, hiding power behind progressive disclosure, not the remaining cut list | + +![The territory: four things this project owns (declared equals real, one of each, honest defaults, one published path); the substrate it touches but others own (Public Launch hard gates, Workforce channels and boards, orchestration dispatch and schedules, the core block kinds); and what it never does (collapse block kinds or state scopes, remove capabilities, ship login, mint a product noun).](figures/territory.svg) + +Above the fence is what this project changes; below it is what its epics touch but other projects +own. The fence is one test: does the change make an existing statement true, or remove a second of +something? A change that adds a capability belongs to another project. + +## The epics — derived live 2026-11-15 00:50 UTC + +| Epic | Outcome it owns | State | Surface | +|---|---|---|---| +| [FIX-1127](https://linear.app/fixpoint-labs/issue/FIX-1127) · **declared surface** | Everything FSD declares or documents is true: four flow options that were silently dropped, a crash on the getting-started path, a resource declaration that leaked between blocks | **done** · 3/3 · Aug 12 | [PR #1249](https://github.com/fixpoint-labs/flow-state-dev/pull/1249), closed at wrap | +| [FIX-1157](https://linear.app/fixpoint-labs/issue/FIX-1157) · **durable storage** | Scope state and resources offer the same verbs where safe; the asymmetry is stated once | **done** · 6/7, 1 canceled · Aug 28 | [PR #1365](https://github.com/fixpoint-labs/flow-state-dev/pull/1365), closed at wrap | +| [FIX-1503](https://linear.app/fixpoint-labs/issue/FIX-1503) · **verified identity** | A reachable host requires a verified principal on every `/api/flows` route but the mint | **in flight** · 0/1 | [`specs/epics/FIX-1503/`](https://github.com/fixpoint-labs/flow-state-dev/tree/main/specs/epics/FIX-1503), merged Sep 22 | +| [FIX-1637](https://linear.app/fixpoint-labs/issue/FIX-1637) · **keeping flows alive** | One published path for how a flow stays alive 24/7, with no new product noun | **in flight** · 4/8, 2 canceled · closure [FIX-1642](https://linear.app/fixpoint-labs/issue/FIX-1642) spec approved | [`specs/epics/FIX-1637/`](https://github.com/fixpoint-labs/flow-state-dev/tree/main/specs/epics/FIX-1637), merged Sep 29 | +| [FIX-2036](https://linear.app/fixpoint-labs/issue/FIX-2036) · **one owner per fact** | Callers stop rebuilding facts the framework already knows: the bugs that causes, and the deletions existing APIs allow | *filed, not started* · 3/10, 1 duplicate | No epic spec | +| [FIX-2171](https://linear.app/fixpoint-labs/issue/FIX-2171) · **durable agents** | Each gap a durable-harness comparison found is closed or decided against | *filed, not started* · 2/15 | No epic spec | +| [FIX-2316](https://linear.app/fixpoint-labs/issue/FIX-2316) · **mechanism sweep** | Each job the October parallel work left with two or three mechanisms gets one | **done** · 5/5 · Oct 31 | No epic spec; children's implementation PRs merged | +| [FIX-2447](https://linear.app/fixpoint-labs/issue/FIX-2447) · **clean SDK** | An adopter importing a package root sees only what an app author needs, one way to do each thing, and a quick start that runs as written | **done** · 32/33, 1 canceled · Nov 15 | [`specs/epics/FIX-2447/`](https://github.com/fixpoint-labs/flow-state-dev/tree/main/specs/epics/FIX-2447), merged Nov 5; closure passed on main `4d97cdc9a` | +| [FIX-2600](https://linear.app/fixpoint-labs/issue/FIX-2600) · **vocabulary** | One word per thing, kept in one glossary | **in flight** · 4/5 · closure [FIX-2602](https://linear.app/fixpoint-labs/issue/FIX-2602) spec approved | [`specs/epics/FIX-2600/`](https://github.com/fixpoint-labs/flow-state-dev/tree/main/specs/epics/FIX-2600), merged Nov 7 | +| [FIX-2618](https://linear.app/fixpoint-labs/issue/FIX-2618) · **feature kits** | An app installs a feature and reads it back without an adapter: views, reads by scope, ids on notices, kits | **in flight** · 10/13 | [`specs/epics/FIX-2618/`](https://github.com/fixpoint-labs/flow-state-dev/tree/main/specs/epics/FIX-2618), merged Nov 9 | +| [FIX-2683](https://linear.app/fixpoint-labs/issue/FIX-2683) · **kit reads in the apps** | Teammates and Shift Manager read through kit views, and their hand-written read models are deleted | *filed, not started* · no children | No epic spec | +| [FIX-2696](https://linear.app/fixpoint-labs/issue/FIX-2696) · **docs revamp** | The user docs rebuilt around apps, kits and a short book of concepts; also carries clean SDK's docs leftovers ([FIX-2739](https://linear.app/fixpoint-labs/issue/FIX-2739)) | **in flight** · 3/9 | [`specs/epics/FIX-2696/`](https://github.com/fixpoint-labs/flow-state-dev/tree/main/specs/epics/FIX-2696), merged Nov 12 | + +4 done · 5 in flight · 3 filed, not started. Every state above is re-derived from Linear and the +child implementation PRs each refresh. + +**Four states disagree with their surface.** FIX-1503's direction merged on Sep 22, but Linear +still reads *In Spec Review* eight weeks later and its one child is in Backlog: counted in flight +because Linear says *started*, with nothing under it begun. FIX-2036 and FIX-2171 read *Backlog* +while five of their children are done, so work is landing under epics no lifecycle is running. +FIX-2447's wrap note counts 34 children done; Linear lists 32 Done and 1 Canceled under it, and +the table carries Linear's count. + +```mermaid +flowchart LR + A["FIX-1127 · declared surface"] + B["FIX-1157 · durable storage"] + C["FIX-1503 · verified identity"] -.->|"the host mount its cutover changes"| D["FIX-1637 · keeping flows alive"] + E["Public Launch · hard gates"] -.->|"the queue-host session fence, pointed to"| D + F["FIX-2036 · one owner per fact"] + G["FIX-2171 · durable agents"] + H["FIX-2316 · mechanism sweep"] + I["FIX-2447 · clean SDK"] -->|"three docs leftovers, FIX-2739"| M["FIX-2696 · docs revamp"] + J["FIX-2600 · vocabulary"] + K["FIX-2618 · feature kits"] -->|"the views and kits it reads through"| L["FIX-2683 · kit reads in the apps"] + classDef done stroke-width:2px + classDef proposed stroke-dasharray:4 3 + class A,B,H,I done +``` + +Four wrapped epics now, three of them standing alone. Clean SDK handed the docs revamp the three +pieces that could only land with the user docs: the quick-start check, the old `stores` lines, and +folding its release check into CI ([Plan](PLAN.md) → seams). Kit reads in the apps cannot start +until feature kits ships what it reads through. The oldest seam is unchanged: the keeping-alive +docs describe how a host is mounted, and verified identity changes exactly that +([Rules](BUSINESS-RULES.md) → PR-1). + +## What this project is not + +- **Not a reduction of the model.** Block kinds, state scopes, capabilities, skills, tools, `ui` + and thought-fabric stay; the review that opened this project retracted those cuts after reading + the code ([Decisions](DECISIONS.md) → *decided once*). +- **Not new capability.** A missing feature found here is filed where features live. +- **Not a login product.** The host verifies people; FSD mints and checks a token. diff --git a/spec/_projects/framework-simplification-and-cleanup/absorbed/linear-content.md b/spec/_projects/framework-simplification-and-cleanup/absorbed/linear-content.md new file mode 100644 index 0000000000..b892f8255e --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/absorbed/linear-content.md @@ -0,0 +1,59 @@ + + +# Linear project `content`, as read + +**Read** 2026-09-29 from the Linear project +[Framework simplification & cleanup](https://linear.app/fixpoint-labs/project/framework-simplification-and-cleanup-9b341cda1f92) +· field `updatedAt` **2026-08-22T17:53:19.922Z** · **2201 characters** + +Everything between the two rules below is the project's `content` field exactly as the API +returned it, before the project-spec was first mirrored over it. What was folded into the +four documents and what was left behind is recorded in the first-build commit and the PR. + +The project's separate one-line `description` field is not overwritten by the mirror. It +read, verbatim: + +> Editorial + structural simplification of @flow-state-dev driven by the first-principles review and validation passes (docs/internal/review*). + +--- + +Editorial + structural simplification of `@flow-state-dev`, scoped from the first-principles review and validation passes. The framework's identity is reframed as **production-grade with progressive disclosure** — power preserved, intro experience tightened. + +## Source documents + +Two sets of reports under `docs/internal/`: + +* `review/00-team-synthesis.md` — original six-reviewer findings +* `review/01-newcomer-dx.md` … `06-cross-cutting-simplification.md` — per-angle deep dives +* `review-validation/00-validation-synthesis.md` — recalibrated action plan after maintainer pushback +* `review-validation/01-state-scopes-validated.md` … `06-identity-and-progressive-disclosure.md` — per-pushback validations + +The validation synthesis supersedes the original synthesis on every contested point. Read it first. + +## Scope + +19 issues across three tiers: + +* **Tier 1 — Cleanup** (1 issue, 1 PR): pure deletes and edits, no API impact. +* **Tier 2 — Editorial** (9 issues): docs reorganization, intro/quick-start/sidebar rewrites, identity statement, project→org sweep. The bulk of the user-visible payoff. Parallelizable. +* **Tier 3 — Refactors** (9 issues): focused refactors that preserve public APIs. Includes the type-level firewall on `BlockDefinition.run`, clientData privacy fix, trace channel separation, and internal library substitutions. + +## Sequencing notes + +* Tier 1 ships first; small. +* Tier 2 items run in parallel. +* T3.1 (handler discipline) lands before or alongside T3.4 (trace channel). +* T3.2 (`runFlow`) lands early in Tier 3 so subsequent work has a sanctioned programmatic entry point. +* T3.4 wants a design doc before opening the PR — biggest item, multi-package impact. + +## Out of scope (deliberately) + +* Collapsing the four block kinds. +* Collapsing the four state scopes. +* Removing capabilities, skills, tools, ui, or thought-fabric. +* Cutting the sequencer DSL public surface beyond `validate()` and `background()`. +* "Expose all + hidden list" clientData default (rejected — private-by-default is the chosen direction). + +The validation team retracted these from the original review after going to the code. See `review-validation/00-validation-synthesis.md` for the evidence. + +--- diff --git a/spec/_projects/framework-simplification-and-cleanup/figures/arc.svg b/spec/_projects/framework-simplification-and-cleanup/figures/arc.svg new file mode 100644 index 0000000000..70022f166c --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/figures/arc.svg @@ -0,0 +1,138 @@ + + + + + + EPIC + AUG 10 + AUG 30 + SEP 19 + OCT 9 + OCT 29 + NOV 18 + + + + + + declared surface + FIX-1127 · 3/3 + + one day · Aug 12 · wrapped + + + + durable storage + FIX-1157 · 6/7 + + Aug 13 · re-scoped Aug 20 · wrapped Aug 28 + + + + verified identity + FIX-1503 · 0/1 + + direction approved Sep 22 · its one child not started + + + + keeping flows alive + FIX-1637 · 4/8 + + Sep 29 · 4 done · closure spec approved + + + + one owner per fact + FIX-2036 · 3/10 + + filed Oct 15 · Backlog · 3 children done Oct 20 + + + + durable agents + FIX-2171 · 2/15 + + filed Oct 24 · Backlog · 2 children done + + + + mechanism sweep + FIX-2316 · 5/5 + + filed Oct 29 · ran Oct 30–31 · wrapped + + + + clean SDK + FIX-2447 · 32/33 + + + filed Nov 1 · direction Nov 5 · wrapped Nov 15 · 1 canceled + + + + vocabulary + FIX-2600 · 4/5 + + + filed Nov 6 · direction Nov 7 · closure spec approved + + + + feature kits + FIX-2618 · 10/13 + + + filed Nov 8 · direction Nov 9 · 10 done + + + + kit reads in the apps + FIX-2683 · 0/0 + + filed Nov 11 · Backlog · waits on feature kits + + + + docs revamp + FIX-2696 · 3/9 + + + filed Nov 12 · direction Nov 12 · carries FIX-2739 + + + + + NOW · NOV 15 + + diff --git a/spec/_projects/framework-simplification-and-cleanup/figures/territory.svg b/spec/_projects/framework-simplification-and-cleanup/figures/territory.svg new file mode 100644 index 0000000000..0fd3af6cca --- /dev/null +++ b/spec/_projects/framework-simplification-and-cleanup/figures/territory.svg @@ -0,0 +1,63 @@ + + + + + + THIS PROJECT · WHAT FSD SAYS IS WHAT IT DOES + declared = real + a doc, type, option or default is honoured, or refused out loud · FIX-1127 · the open bugs + one of each + two primitives for one job: symmetric where safe, the difference stated once · FIX-1157 + honest defaults + a reachable host verifies its caller; the open posture is a named escape · FIX-1503 + one published path + keeping a flow alive, taught once, with no new product noun · FIX-1637 + + + + + NEVER HERE + collapsing block kinds or state scopes + removing capabilities, skills, tools, + ui or thought-fabric + login, an OAuth UI, a password store + a heartbeat product noun + new capability of any kind + the review retracted the first two + + + + + Does it make an existing statement true, or remove a second of something? Yes → above. It adds a capability → another project. + + + + + TOUCHED HERE, OWNED ELSEWHERE + Public Launch · hard gates + session delivery on a queue host: documented, not fixed + Workforce · channels and boards + taught as consumption patterns, not changed + Orchestration · dispatch and schedules + Core Blocks · the block kinds + +