Repository navigation
feat(members): append-only crew ledger with pluggable contributors - #9907
chenmingwei23 wants to merge 1 commit into
Conversation
4ac928d to
4294906
Compare
4294906 to
c3aaa31
Compare
UX Review (Fable 5, fork) — ⏭️ skippedRevision |
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify every manifest-mutating lifecycle path bumps the grant generation — the switch from a 30s TTL to generation-keyed permission caching removes the self-healing backstop, so a missed bump strands a stale grant for the process lifetime. [DESIGN-REVIEWED] 4757a57 |
c3aaa31 to
9e438b1
Compare
First Principles Review (Fable 5, fork) — 🔴 BLOCKPremise-level review of First-Principles-Verdict: BLOCK The whole contribution protocol ships with zero in-tree consumers — its two real consumers (the hosting adapter and the drawer card) are, by the description's own words, withdrawn and deferred. Not justified as shipped
Inventory (10 items) — 3 justifiedIntent: let an installed app read a member's event log, append namespaced events, and publish a projection the drawer will render, through one wire contract with the gateway as sole writer. ADDITION.
Plus new Blockers
[FIRST-PRINCIPLES-REVIEWED] 4757a57 |
Opus 5 Review (fork) — 🔴 changes requested (blocking)Reviewed A read failure on a unit's projection file marks it loaded-and-empty, and the next publish overwrites the file, silently destroying every other app's rows for that member. BLOCKING — src/kiro_crew/eventlog/contrib.py:415 BLOCKING — src/kiro_crew/apps/manager.py:1993 BLOCKING — docs/feature-map/README.md:113 FINDING — src/kiro_crew/apps/teardown.py:363 — FINDING — src/kiro_crew/eventlog/contrib.py:546 — FINDING — src/kiro_crew/dashboard/handlers/eventlog.py:363 — FINDING — src/kiro_crew/dashboard/token_auth.py:1455 — the surviving comment |
9e438b1 to
afc6570
Compare
GPT 5.6 Review (fork) — 🔴 changes requested (blocking)Reviewed 2 of 4 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands. BLOCKING -- docs/feature-map/README.md:113 -- Misstates the event-log writer model (origin: validation) BLOCKING -- src/kiro_crew/dashboard/handlers/eventlog.py:231 -- Bound retained event types BLOCKING -- src/kiro_crew/apps/teardown.py:390 -- Projection deletion precedes the disable commit BLOCKING -- src/kiro_crew/apps/teardown.py:702 -- Uninstall returns before contribution cleanup [BLOCK-MERGE] 4757a57 Adjudication (Opus 5) — is blocking on each finding proportionate?F1 — anchored to F2 — anchored to [ADJUDICATION] 4757a57 total=2 uphold=2 downgrade=0 [ADJUDICATION-FENCED] 4757a57 fenced=2 flagged=0 |
Board attribution for
|
Round on
|
Round disposition — head
|
|
/ai-review override gpt 2a718f1: Every blocking finding is a granted-app or crash-race path that fails the reachability/recoverability bar. F4/F1/F5 trigger only from an operator-installed app that declared contributions (may_publish gated) or a concurrent MCP writer -- an actor who already runs in-gateway and can exhaust memory or reorder its own emits directly, so the path grants no new capability. F2/F3/F6 need a crash in a sub-millisecond window or a disk failure plus restart and the lost state is re-derivable or the partial import deletable -- recoverable, not high-impact. None is a demonstrable reachable trigger with an unrecoverable consequence. |
|
AI-review override not recorded: keep the reason to 500 characters or fewer. |
|
/ai-review override gpt 2a718f1: All six triggers fail the bar. F4/F1/F5 fire only from an operator-installed granted app (may_publish) or a concurrent MCP writer -- an actor already running in-gateway that can exhaust memory or reorder its own emits directly, so the path adds no capability. F2/F3/F6 need a sub-ms crash window or disk-failure-plus-restart, and the state is re-derivable or the import deletable -- recoverable. None is reachable-plus-unrecoverable. |
Human judgment recorded@chenmingwei23 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: GPT 5.6. Re-run the lane's latest workflow run for |
Ownership handover and where this stands -- head
|
|
/ai-review override all 8a4cfcb: Test 1, already-compromised. The unfenced members//log.jsonl needs local write inside the gateway data home, which already grants config.json (store and owner declarations) and the session transcripts, both strictly stronger than appending a roster row; the one finding with a real attack, may_append accepting a reserved namespace, was fixed on this head and is pinned by test_an_app_named_for_a_reserved_namespace_cannot_forge_builtin_events. The eventlog vs crew_log duplication is a scope call, not an attack. |
|
AI-review override not recorded: keep the reason to 500 characters or fewer. |
|
/ai-review override all 8a4cfcb: Test 1, already-compromised: writing members//log.jsonl needs local write in the gateway data home, which already grants config.json (store and owner declarations) and the session transcripts, both stronger. The one finding with a real attack, may_append accepting a reserved namespace, is fixed on this head and pinned by test_an_app_named_for_a_reserved_namespace_cannot_forge_builtin_events. |
|
AI-review override not recorded: |
Round on
|
Round on
|
Disposition for
|
Round 9 disposition -- head
|
Board state for
|
|
Consolidation: the contribution-protocol half of this draft now lives in PR #12645 PR #12645 (same author) adds the same new modules at the same paths as this branch: Things #12645 has that this branch lacks:
Things only this branch has:
Rebasing this branch is not a good path. It is 673 commits behind and conflicts in 30 files. The ledger half landed in newer form through PR #12020 and PR #12746, and the importer through PR #12009. Resolving the conflicts in this branch's favour would regress main:
Suggested order:
From a full open-PR audit against origin/main c66f95b (2026-09-25); findings were checked by independent reviewers reading the code. Reply here if this is wrong. |
|
Windows: a member slug may be a DOS device name, which then becomes a filename stem in the new projection store (P3, advisory)
That pattern correctly rejects On Windows editions that enforce the legacy device namespace, a create against such a name resolves to the device rather than a file and fails, so that member's contributed card never becomes durable. Scope, stated honestly. Reachability is narrow: it needs a member whose slug is one of those words and a granted contributing app. The consequence is one member's non-durable projection — no data loss, no corruption, no credential exposure. And it did not reproduce on the host this audit ran on (Windows Server 2025, build 26100, Suggested fix. Route the stem through the same identity fold the member log already applies, or reuse the existing Suggested test. A parametrized case over the reserved basenames asserting the projection path's stem is folded, so a Raised by an automated Windows-compatibility audit of the open PR queue. All existing comments on this PR were checked; none names this mechanism. Flagged on a draft because the fix is small and cheaper to apply before the surrounding design settles. |
The contribution protocol that lets an installed app read a member's history, append its own namespaced events and publish a whole-value projection the drawer renders from a declarative schema. The gateway stays the only writer and enforces ownership, depth, size and retention at the boundary. Rebased onto main's member event-log subsystem (kirodotdev#12020 and its successors), which is authoritative: this change re-ports only the genuinely-new contribution layer onto main's current APIs rather than re-introducing a parallel event-log/projection implementation. New: eventlog/{contrib,grants, projection}.py, dashboard/eventlog_ws.py, dashboard/handlers/eventlog.py, the `contributions` manifest declaration (folded into the signed payload), the `/api/eventlog/{kind}/{id}/*` routes and the eventlog_subscribe WS frames, an `events_after` catch-up read on the member log service, teardown_contributions, and the app-token eventlog path grant. Contributed projection rows ride the `/api/members` roster block alongside `roster` (per kirodotdev#13754's narrowing) with their own seqs/schemas.
|
Closing this PR. The First Principles review blocked the change on the grounds that the contribution protocol ships with zero in-tree consumers, and the ruling was to comply by subtraction rather than by override. Performing that subtraction — removing the protocol layer ( The protocol will ship later together with its first consumer (#12645), which is the consumer whose absence this review flagged. Landing the two together answers the First Principles concern directly rather than shipping a public contract ahead of any caller. |
Problem / Motivation
Goal: Let an installed app read a crew member's history, append its own namespaced events, and publish a whole-value projection the member drawer renders — through one wire contract, with the gateway staying the only writer.
Nothing outside the gateway process can contribute state about a crew member today. Any plugin or app that has something to say about a crew has to be written into the gateway itself, so a third-party integration cannot record a fact against a member or put a view on the member's card without a core change.
Why it matters
Any app or adapter, in any language, can read a member's history, record its own facts, and put a view on the member's card through one declarative contract — while the gateway stays the only writer and enforces ownership, size, depth, retention and quota at the boundary. This turns "contribute to a crew member" from a gateway change into an app capability.
Not a goal
/api/membersroster payload shape: the list stays narrowed to the roster view; a contributed row rides that block alongsiderosterrather than restoring the full projection set.What changed (motivation → approach → change)
Approach: main's member event-log subsystem is authoritative. This change re-ports only the genuinely-new contribution layer onto main's current service, log, projection and manifest APIs, rather than reintroducing a parallel implementation. The alternative — landing the branch's own event-log/service/projection rewrite — was rejected because it would regress the subsystem main has since evolved.
Built:
eventlog/contrib.py,eventlog/grants.py,docs/system-specs/modules/contribution-protocol.md): a manifest-declaredcontributionsgrant checked on every call; namespaced appends bounded by size (64 KiB), nesting depth (32 levels) and a per-unit daily budget; whole-value projection publish with higher-seq-wins, bounded by size, depth and a per-app retention cap; teardown withdraws views and keeps events.dashboard/handlers/eventlog.py,dashboard/eventlog_ws.py,dashboard/ws.py,dashboard/ws_event_scope.py,dashboard/websocket_hub.py): the catch-upGET /api/eventlog/{kind}/{id}/events, the append, projection and schemaPOSTroutes, plus theeventlog_subscribeWS delta channel with the contiguity rule. App-token path grant for the eventlog prefix, keyed on thecontributionsdeclaration (dashboard/token_auth.py).events_afteroldest-first catch-up read on the member event-log service,MAX_VALUE_DEPTHin the event-log vocabulary,teardown_contributionson app teardown, and thecontributionsmanifest field folded into the signed payload./api/membersroster block alongsiderosterwith their own seqs and schemas, so a client needs no second code path.docs/request-for-change/rfc-crew-native-append-only.mdstates the model: storage follows the subject, visibility follows grants, the tree is a view.contributionsfield (the repo's own round-trip completeness guard covers it).Backwards compatibility
Compatible: every added field is optional and additive.
contributionsdefaults to an empty declaration (an app that declares none can do nothing here); the manifest signed-payload only includescontributionswhen declared, so manifests signed before this field existed produce the identical payload. No existing field is rejected, renamed or removed;MAX_VALUE_DEPTHandevents_afterare additive to the event-log types and service.Tests
test/test_contribution_protocol.py— manifest declaration, grants, the external projection store, catch-up read, teardown, budget/caps, and contributed rows riding the roster block with their own seq/schema.test/test_eventlog_ws_frames.py,test/test_eventlog_ws_failclosed.py— the subscribe/unsubscribe frames, refusal codes, and fail-closed publish (a redaction fault drops the frame and closes the subscribers).test/contrib_protocol_demo.py— a reference contributor client over the protocol.test/test_app_bridges.py— the builtin manifest-snapshot completeness guard now covers thecontributionsfield.Manual verification
N/A — unit coverage sufficient. The protocol's read/append/publish/subscribe paths, grant checks, teardown, caps and the
/api/membersmerge are all exercised by the suites above against main's current service.Related Issues
Implements the contribution protocol described in
docs/system-specs/modules/contribution-protocol.md.Checklist