Define Hyperkernel's trusted architecture and project positioning#6
Conversation
Render
Destroyed
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b428093674
ℹ️ 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".
| ### Projections build read models | ||
|
|
||
| The current prototype does not have a production database schema or migration set. Self-hosted instances are therefore suitable for development and architectural evaluation, not durable production data. Backup, restore, and upgrade guarantees will be documented when the first persistent application flow is introduced. | ||
| Applications read data through projections. When an event is appended, every projection that declares a dependency on that event is advanced from its checkpoint. |
There was a problem hiding this comment.
For extension projections, saying every dependent projection advances “when an event is appended” obscures the transaction boundary and suggests that all projection work belongs in the append path. The canonical contract instead requires extension projections to run in isolation after the event commits and permits them to remain stale on failure; document the synchronous kernel and post-commit extension cases separately so implementers do not let an extension failure roll back the canonical log.
AGENTS.md reference: AGENTS.md:L91-L91
Useful? React with 👍 / 👎.
| - By default, extension projections run in isolation after event commit. Their failure may make their own read model stale or unavailable, but it must not corrupt or roll back the canonical event log. | ||
| - Only its projector or controlled rebuild machinery may write its derived tables. | ||
| - Projection handlers must be deterministic. They may use the current event, their own state derived from earlier ordered events, and versioned projection configuration. They must not read the clock, generate randomness, call the network, invoke tools, or depend on other ambient mutable state. | ||
| - Apply events in stable log order. Each affected projection advances from an explicit checkpoint. |
There was a problem hiding this comment.
When an extension projection applies a non-idempotent event, merely advancing from an explicit checkpoint does not define the required crash boundary: a crash after the derived write but before the checkpoint causes the event to be applied twice, while advancing the checkpoint first can permanently skip it. Require each extension projection's derived writes and checkpoint advancement to commit atomically so checkpointed retry preserves incremental-versus-clean-replay equivalence.
AGENTS.md reference: AGENTS.md:L50-L51
Useful? React with 👍 / 👎.
| Email, payments, webhooks, agent tool calls, and other effects outside the database are not projections. | ||
|
|
||
| ### Patch Discipline | ||
| Use a durable outbox or another explicit delivery boundary with at-least-once delivery. Supply idempotency keys or deduplicate when the receiver supports them. If a crash leaves the remote outcome unknown, record that ambiguity and reconcile it before an unsafe retry. |
There was a problem hiding this comment.
When a committed event requests an external effect, durability and at-least-once delivery alone leave an unsafe crash window unless the delivery intent is written atomically with the originating event: writing it afterward can lose the effect, while writing it beforehand can dispatch an effect for a command that never commits. State that the outbox entry or equivalent handoff participates in the authoritative transaction so the documented failure and recovery contract is complete.
AGENTS.md reference: AGENTS.md:L135-L135
Useful? React with 👍 / 👎.
| | Layer | Examples | Change standard | | ||
| | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | ||
| | Kernel | command processing, authorization, event storage, ordering, concurrency, projection runtime, checkpoints, rebuilds, replay, audit, and public contracts | Stable contracts, compatibility and recovery tests, and approval by an experienced human maintainer | | ||
| | Extensions | domain applications, projection definitions and read models, workflows, integrations, agent tools, and SDK packages | Faster iteration through constrained public kernel contracts, with tests and review proportional to risk | |
There was a problem hiding this comment.
Listing “SDK packages” under Extensions lets a contributor classify changes to the public command, event, or projection SDK as faster-moving extension work, even though those contracts determine whether callers can bypass the kernel and must retain compatibility. Distinguish extension packages built through the SDK from the public SDK contract itself, which the canonical classification places in the Kernel quality gate.
AGENTS.md reference: AGENTS.md:L17-L18
Useful? React with 👍 / 👎.
| ### Commands record intent | ||
|
|
||
| ## Verification | ||
| A command is an immutable record of what an identified actor asked the system to do. Humans, applications, automations, and AI agents all use the same command boundary. |
There was a problem hiding this comment.
This section now formally makes commands the foundational request contract, but CONTEXT.md still identifies itself as the current domain language and states at lines 32–33 that commands have not been formally introduced. Contributors following that document can therefore retain the conflicting action terminology or treat commands as undefined; update the domain-language document as part of this contract change.
AGENTS.md reference: AGENTS.md:L194-L195
Useful? React with 👍 / 👎.
1 participant
Summary
Why
Hyperkernel's objective has evolved from a generic modular business platform into a small, human-reviewed kernel that protects authoritative history and lets less critical applications, workflows, interfaces, and integrations evolve faster. The public documentation and contributor guidance need to express the same trust boundary and vocabulary.
Impact
This is a documentation and package-metadata change. It does not change runtime behavior. Contributors gain a canonical architecture, explicit invariants, and a risk-based quality gate for future implementation.
Validation
npm run lintgit diff --cached --check