Skip to content

Official site wave-2: architecture overview + doctrine highlights pages (EN + zh) #9

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
loning merged 1 commit into from
Jun 10, 2026
Merged

Official site wave-2: architecture overview + doctrine highlights pages (EN + zh) #9

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions site/architecture.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Architecture | fkst</title>
<meta
name="description"
content="Architecture overview for fkst: company tiers, reliable delivery, and the three-repo package ecosystem."
>
<link rel="stylesheet" href="style.css">
</head>
<body>
<header class="site-header">
<a class="brand" href="./" aria-label="fkst home">fkst</a>
<nav class="top-nav" aria-label="Primary">
<a href="./">Home</a>
<span aria-current="page">Architecture</span>
<a href="doctrine.html">Doctrine</a>
<a href="https://github.com/ChronoAIProject/fkst-substrate">fkst-substrate</a>
<a href="https://github.com/ChronoAIProject/fkst-packages">fkst-packages</a>
<a href="https://github.com/ChronoAIProject/fkst-website">fkst-website</a>
</nav>
<div class="language-switch" aria-label="Language">
<span aria-current="page">EN</span>
<a href="zh/architecture.html">中文</a>
</div>
</header>

<main>
<section class="page-header" aria-labelledby="page-title">
<p class="eyebrow">Architecture overview</p>
<h1 id="page-title">A company-shaped runtime over durable events.</h1>
<p class="page-intro">
fkst keeps the engine, shared packages, and website-domain behavior in
separate repositories while the runtime unions package roots into one
explicit department graph.
</p>
</section>

<div class="page-content">
<section class="content-section" aria-labelledby="company-model">
<h2 id="company-model">Company model</h2>
<div>
<p>
Work is modeled as Company, Department, and Person. A company owns
the durable graph, departments declare concrete responsibilities,
and persons are spawned workers that execute bounded tasks.
</p>
<ul>
<li>Sources raise events from outside facts such as GitHub issues or timers.</li>
<li>Fanout gives multiple departments the same fact without runtime interception.</li>
<li>Routing selects the next department, spawn creates work, and RAISED records the resulting events.</li>
</ul>
</div>
</section>

<section class="content-section" aria-labelledby="delivery-model">
<h2 id="delivery-model">Reliable delivery</h2>
<div>
<p>
Delivery is redb-backed and treats retries as normal operation:
events are delivered at least once until acknowledged, leases and
fencing keep workers from racing stale ownership, and DLQ records
preserve failures for inspection.
</p>
<p>
Large content does not ride inside reliable payloads. Payloads
carry a source_ref pointer plus small control fields, and
consumers re-fetch the authoritative content when they need it.
</p>
</div>
</section>

<section class="content-section" aria-labelledby="repo-model">
<h2 id="repo-model">Repository ecosystem</h2>
<div>
<p>
The ecosystem is split into three public repositories. The
fkst-substrate repo owns the engine and package contract,
fkst-packages owns reusable package patterns, and fkst-website
adds only website-domain Lua behavior.
</p>
<p>
Packages can be flat or composed. A composed package references
dependencies through declared composition, and the engine receives
one graph by unioning the pinned package roots supplied at runtime.
</p>
</div>
</section>
</div>
</main>

<footer class="site-footer">
<p><a href="./">Back to home</a></p>
</footer>
</body>
</html>
92 changes: 92 additions & 0 deletions site/doctrine.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Doctrine | fkst</title>
<meta
name="description"
content="Selected fkst doctrine highlights: marker-as-fact, codex-judgment gates, host write posture, and one current system shape."
>
<link rel="stylesheet" href="style.css">
</head>
<body>
<header class="site-header">
<a class="brand" href="./" aria-label="fkst home">fkst</a>
<nav class="top-nav" aria-label="Primary">
<a href="./">Home</a>
<a href="architecture.html">Architecture</a>
<span aria-current="page">Doctrine</span>
<a href="https://github.com/ChronoAIProject/fkst-substrate">fkst-substrate</a>
<a href="https://github.com/ChronoAIProject/fkst-packages">fkst-packages</a>
<a href="https://github.com/ChronoAIProject/fkst-website">fkst-website</a>
</nav>
<div class="language-switch" aria-label="Language">
<span aria-current="page">EN</span>
<a href="zh/doctrine.html">中文</a>
</div>
</header>

<main>
<section class="page-header" aria-labelledby="page-title">
<p class="eyebrow">Doctrine highlights</p>
<h1 id="page-title">A small set of rules keeps autonomy legible.</h1>
<p class="page-intro">
fkst favors durable facts, explicit gates, and current-state design.
These highlights are selected doctrine, not a complete contract.
</p>
</section>

<div class="page-content">
<section class="content-section" aria-labelledby="markers">
<h2 id="markers">Markers are facts</h2>
<div>
<p>
GitHub is eventually consistent, so fkst writes marker records as
facts and uses version-CAS style claims around them. The marker is
not decorative metadata; it is the observable state a later worker
can read, compare, and advance.
</p>
</div>
</section>

<section class="content-section" aria-labelledby="gates">
<h2 id="gates">Gates judge pipelines</h2>
<div>
<p>
Gates are codex-judgment pipelines over the work product and
evidence. They are not per-event human labels sprinkled through
the queue. The review is explicit, repeatable, and tied to the
proposal or delivery stage being judged.
</p>
<p>
Write posture is also explicit. The website package has one host
environment fact for publishing: FKST_SITE_WRITE=1 enables real
writes, and missing publish configuration fails closed.
</p>
</div>
</section>

<section class="content-section" aria-labelledby="current-shape">
<h2 id="current-shape">One current shape</h2>
<div>
<p>
fkst does not keep backward-compatibility modes, deprecated
shims, or speculative branches in the system. When the contract
changes, the current shape changes with it.
</p>
<p>
New patterns must serve a proven present problem. The bias is to
keep the runtime and packages small enough that every visible
mechanism earns its place.
</p>
</div>
</section>
</div>
</main>

<footer class="site-footer">
<p><a href="./">Back to home</a></p>
</footer>
</body>
</html>
2 changes: 2 additions & 0 deletions site/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@
<header class="site-header">
<a class="brand" href="./" aria-label="fkst home">fkst</a>
<nav class="top-nav" aria-label="Primary">
<a href="architecture.html">Architecture</a>
<a href="doctrine.html">Doctrine</a>
<a href="https://github.com/ChronoAIProject/fkst-substrate">fkst-substrate</a>
<a href="https://github.com/ChronoAIProject/fkst-packages">fkst-packages</a>
<a href="https://github.com/ChronoAIProject/fkst-website">fkst-website</a>
Expand Down
63 changes: 63 additions & 0 deletions site/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,8 @@ a:focus-visible {
.site-header,
.hero,
.features,
.page-header,
.page-content,
.site-footer {
margin-inline: auto;
max-width: 1120px;
Expand Down Expand Up @@ -91,13 +93,18 @@ a:focus-visible {
}

.top-nav a,
.top-nav span,
.language-switch a,
.language-switch span {
color: var(--muted);
font-size: 0.94rem;
font-weight: 650;
}

.top-nav span {
color: var(--text);
}

.language-switch {
align-items: center;
display: flex;
Expand Down Expand Up @@ -185,6 +192,58 @@ h1 {
padding-block: 18px 72px;
}

.page-header {
padding-block: clamp(54px, 9vw, 102px) 34px;
}

.page-header h1 {
font-size: clamp(2.7rem, 8vw, 5.8rem);
}

.page-intro {
color: var(--muted);
font-size: clamp(1.05rem, 2vw, 1.25rem);
max-width: 760px;
}

.page-content {
display: grid;
gap: 18px;
padding-block: 16px 72px;
}

.content-section {
border-top: 1px solid var(--line);
display: grid;
gap: 18px;
grid-template-columns: minmax(0, 0.9fr) minmax(0, 1.35fr);
padding-top: 28px;
}

.content-section h2 {
font-size: clamp(1.45rem, 3vw, 2.4rem);
margin-bottom: 0;
}

.content-section p {
color: var(--muted);
margin-bottom: 0;
}

.content-section p + p {
margin-top: 12px;
}

.content-section ul {
color: var(--muted);
margin: 0;
padding-left: 1.2rem;
}

.content-section li + li {
margin-top: 10px;
}

.section-heading {
border-top: 1px solid var(--line);
padding-top: 34px;
Expand Down Expand Up @@ -255,6 +314,10 @@ h2 {
grid-template-columns: 1fr;
}

.content-section {
grid-template-columns: 1fr;
}

.feature-card {
min-height: 0;
}
Expand Down
94 changes: 94 additions & 0 deletions site/zh/architecture.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
<!doctype html>
<html lang="zh-Hans">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>架构 | fkst</title>
<meta
name="description"
content="fkst 架构概览：公司三档模型、可靠投递，以及三仓 package 生态。"
>
<link rel="stylesheet" href="../style.css">
</head>
<body>
<header class="site-header">
<a class="brand" href="../" aria-label="fkst home">fkst</a>
<nav class="top-nav" aria-label="Primary">
<a href="./">首页</a>
<span aria-current="page">架构</span>
<a href="doctrine.html">信条</a>
<a href="https://github.com/ChronoAIProject/fkst-substrate">fkst-substrate</a>
<a href="https://github.com/ChronoAIProject/fkst-packages">fkst-packages</a>
<a href="https://github.com/ChronoAIProject/fkst-website">fkst-website</a>
</nav>
<div class="language-switch" aria-label="Language">
<a href="../architecture.html">EN</a>
<span aria-current="page">中文</span>
</div>
</header>

<main>
<section class="page-header" aria-labelledby="page-title">
<p class="eyebrow">架构概览</p>
<h1 id="page-title">以公司形态运行在持久事件之上。</h1>
<p class="page-intro">
fkst 将 engine、共享 package 与 website 域行为拆在不同仓库中；
运行时把多个 package root union 成一张显式 department graph。
</p>
</section>

<div class="page-content">
<section class="content-section" aria-labelledby="company-model">
<h2 id="company-model">公司模型</h2>
<div>
<p>
工作被建模为 Company、Department、Person 三档。Company 持有
持久 graph，department 声明具体职责，person 是被 spawn 出来
执行有边界任务的 worker。
</p>
<ul>
<li>source 从 GitHub issue、timer 等外部事实 raise event。</li>
<li>fanout 让多个 department 消费同一个事实，而不是做运行时拦截。</li>
<li>route 选择下一站，spawn 创建工作，RAISED 记录产生的新 event。</li>
</ul>
</div>
</section>

<section class="content-section" aria-labelledby="delivery-model">
<h2 id="delivery-model">可靠投递</h2>
<div>
<p>
投递由 redb 支撑，并把 retry 视为正常运行：event 至少投递一次
直到 ack，lease 与 fencing 避免 stale ownership 竞争，DLQ
保留失败事实以便检查。
</p>
<p>
大体量内容不进入可靠投递 payload。payload 只带 source_ref
指针和小控制字段，consumer 在需要时回源读取权威内容。
</p>
</div>
</section>

<section class="content-section" aria-labelledby="repo-model">
<h2 id="repo-model">三仓生态</h2>
<div>
<p>
生态拆成三个公开仓库。fkst-substrate 负责 engine 与 package
contract，fkst-packages 负责可复用 package 模式，fkst-website
只添加 website 域 Lua 行为。
</p>
<p>
package 可以是 flat 或 composed。composed package 通过声明组合
引用依赖；engine 在运行时接收多个已 pin 的 package root，并
union 成一张 graph。
</p>
</div>
</section>
</div>
</main>

<footer class="site-footer">
<p><a href="./">返回首页</a></p>
</footer>
</body>
</html>
Loading
Loading