Skip to content

docs(blog): explain Maka's append-only runtime - #4565

Merged
likun666661 merged 1 commit into
mainfrom
docs/blog-log-is-the-runtime
Sep 2, 2026
Merged

docs(blog): explain Maka's append-only runtime#4565
likun666661 merged 1 commit into
mainfrom
docs/blog-log-is-the-runtime

Conversation

@likun666661

Copy link
Copy Markdown
Member

Summary

  • introduce docs/blogs/ for long-form design explanations and link it from the documentation authority map
  • add a Chinese blog that connects distributed database log-first design to Maka Runtime Event Log
  • explain compaction as a source-bound projection and Tool Result pruning as archive-backed context offload

Verification

  • git diff --check
  • npm run check:asf-headers
  • confirmed the documentation index link resolves to the new article
  • full tests and typecheck not run because this is a Markdown-only change; Biome does not process Markdown in this repository

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex reviewed the current Maka architecture and implementation, drafted the article, and prepared the documentation index and PR.

Checklist

  • Tests cover the change and fail without it
  • Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

@github-actions github-actions Bot added the effort/M Under 500 readable lines label Sep 2, 2026
@likun666661
likun666661 merged commit f738d41 into main Sep 2, 2026
2 checks passed
@likun666661
likun666661 deleted the docs/blog-log-is-the-runtime branch September 2, 2026 14:17

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

This is a strong explanation of the source-of-truth / projection boundary. Before publishing it as architecture documentation, could we tighten four claims that currently blur the implemented contract or overstate the analogy?

  1. Current archive storage vs. the target design (lines 234–236). Tool Result archives are currently persisted through the ArtifactStore-backed archive authority. A dedicated SQLite ContextOffloadStore is the proposed direction in #4071, not the current implementation. Please either describe the current authority neutrally or explicitly label the dedicated store as planned.

  2. Paging is model-response pagination, not physical range I/O (lines 238–240). ArchiveRead currently hydrates and verifies the complete capped object, then applies offset/limit to the response. The swap/demand-paging analogy is useful, but it should state that this is not storage-level paging or bounded range reads.

  3. The placeholder is not, by itself, a bearer capability (line 246). The archive reference is an integrity-bound, Session-scoped locator. Possession of the ref does not authorize a read: the archive authority must verify that the invoking Session owns the artifact. Calling it a capability can suggest the wrong security model.

  4. A checkpoint cannot necessarily be regenerated identically from the log (lines 208 and 218). The source log can produce a new valid checkpoint, but an LLM-generated summary may not be byte-identical to the one a later model call already observed. Exact provider-history recovery requires retaining the durable projection, or falling back to raw history; “regenerate from log” should be qualified accordingly.

These changes would preserve the article's main argument while separating authoritative history, provider-visible projections, and the future #4071 storage topology more precisely.

likun666661 added a commit that referenced this pull request Sep 2, 2026
Reverts #4565 and #4567.

Generated-by: OpenAI Codex

Co-authored-by: likun <kunli@alva.xyz>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants