feat: add neutral architecture overview beat

This commit is contained in:
lda
2026-07-13 10:24:42 +07:00 Verified
parent 870902a69b
commit aec2651ae6
12 changed files with 37 additions and 14 deletions
+1 -1
View File
@@ -162,7 +162,7 @@ visual hierarchy, chat mode, evidence mode, and fallback route.
- Title: `http://127.0.0.1:5173/present#scene/thesis/title`
- Positioning: `http://127.0.0.1:5173/present#scene/positioning/landscape`
- Architecture root: `http://127.0.0.1:5173/present#scene/architecture/client`
- Architecture root: `http://127.0.0.1:5173/present#scene/architecture/overview`
- Runtime providers:
`http://127.0.0.1:5173/present#scene/architecture/runtime/focus/runtime-providers`
- NodeUse:
@@ -92,13 +92,13 @@ Keep Scene 5 conceptual. Scene 9 applies this vocabulary to the prepared example
### Scene 6: Zoom through the implemented architecture
**Route:** `architecture/client`, `architecture/api`, `architecture/runtime`, then `architecture/node-use`
**Route:** `architecture/overview`, `architecture/client`, `architecture/api`, `architecture/runtime`, then `architecture/node-use`<br>
**Time:** 3:55-4:50
**Evidence:** Supported
Say:
> Human operators and external agents enter through the same public lifecycle surface. WorkflowApi owns lifecycle operations; JSON-RPC adapts requests without owning domain behavior. WorkflowServer composes records, provider-neutral capabilities, WorkflowApi, and the execution kernel; provider behavior remains outside the core. A NodeUse resolves bindings, invokes its NodeDef handler, reduces output into state, appends a trace frame, and routes the outcome.
> First, the implemented architecture spine and its ownership boundaries. Humans and agents share one public lifecycle surface. WorkflowApi owns lifecycle operations; JSON-RPC only adapts transport. WorkflowServer composes records, capabilities, API, and kernel; providers remain outside the core. NodeUse invokes a NodeDef handler, reduces state, records trace, and routes the declared outcome.
The NodeUse sequence is documented in the thesis runtime diagram and narrative ([lines 706-750](../thesis/system-design-implementation.md#workflow-core-model)).
@@ -27,6 +27,7 @@ can be shown after selecting replay with the runbook's session-storage switch.
| `lifecycle/artifact` | Artifact is an immutable workflow definition. | Lifecycle stage: Artifact | State transition strip | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/artifact` |
| `lifecycle/deployment` | Deployment binds an artifact version to concrete sources and runtime context. | Lifecycle stage: Deployment | Binding relationship | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/deployment` |
| `lifecycle/run` | Run records one execution, including status, diagnostics, output, trace, and an explicit stopped or interrupted state. | Lifecycle stage: Run | Evidence record chain | hidden | replay-only; Thesis Workflow Lifecycle | `lifecycle/run` |
| `architecture/overview` | The implemented system separates its public surface, lifecycle records, provider boundary, and execution kernel. | Neutral architecture spine | System architecture figure | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/overview` |
| `architecture/client` | Human and agent clients use the same public lifecycle operations. | Architecture client node | System architecture figure | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/client` |
| `architecture/api` | JSON-RPC handles transport concerns and delegates to WorkflowApi rather than owning domain behavior. | Architecture API node | Client operations | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/api` |
| `architecture/runtime` | Server composition supplies stores, provider projections, and the runtime while the core remains independent of MCP and Python behavior. | Runtime/providers focus | Architecture overview | hidden | replay-only; Thesis System Architecture; `docs/project_map.md`; `docs/source_architecture.md` | `architecture/runtime` |
+1 -1
View File
@@ -4,7 +4,7 @@
Open each URL in a browser at 100% zoom, 1280x720 viewport:
1. **Scene 6 root**: `http://127.0.0.1:5173/present#scene/architecture/client`
1. **Scene 6 root**: `http://127.0.0.1:5173/present#scene/architecture/overview`
2. **Scene 6 runtime**: `http://127.0.0.1:5173/present#scene/architecture/runtime/focus/runtime-providers`
3. **Scene 6 providers**: `http://127.0.0.1:5173/present#scene/architecture/runtime/focus/runtime-providers/configured-providers`
4. **Console**: `http://127.0.0.1:5173/console`
@@ -12,6 +12,7 @@
{"sceneId":"lifecycle","beatId":"artifact","route":"lifecycle/artifact","fileStem":"05-lifecycle-artifact"},
{"sceneId":"lifecycle","beatId":"deployment","route":"lifecycle/deployment","fileStem":"05-lifecycle-deployment"},
{"sceneId":"lifecycle","beatId":"run","route":"lifecycle/run","fileStem":"05-lifecycle-run"},
{"sceneId":"architecture","beatId":"overview","route":"architecture/overview","fileStem":"06-architecture-overview"},
{"sceneId":"architecture","beatId":"client","route":"architecture/client","fileStem":"06-architecture-client"},
{"sceneId":"architecture","beatId":"api","route":"architecture/api","fileStem":"06-architecture-api"},
{"sceneId":"architecture","beatId":"runtime","route":"architecture/runtime","fileStem":"06-architecture-runtime"},
@@ -75,6 +75,7 @@ afterEach(() => {
describe("PresentationRoute", () => {
const directHashRoutes = [
{ hash: "#scene/thesis/title", heading: "Design and Implementation of lda.chat", hasDemoChrome: false },
{ hash: "#scene/architecture/overview", heading: "Architecture Zoom", hasDemoChrome: false },
{ hash: "#scene/architecture/client", heading: "Architecture Zoom", hasDemoChrome: false },
{ hash: "#scene/authoring/diagnose", heading: "Author, Validate, Repair", hasDemoChrome: false },
{
@@ -148,6 +148,7 @@ const beatContracts = {
"thesis/substrate": { mode: "split", primarySurface: "opening-decomposition", supportSurface: "none" },
"problem/direct-actions": { mode: "split", primarySurface: "tool-loop-transcript", supportSurface: "workflow-blueprint" },
"problem/missing-contracts": { mode: "split", primarySurface: "workflow-blueprint", supportSurface: "tool-loop-transcript" },
"architecture/overview": { mode: "focal", primarySurface: "interactive-architecture", supportSurface: "none" },
"architecture/client": { mode: "zoom", primarySurface: "interactive-architecture", supportSurface: "none" },
"architecture/api": { mode: "zoom", primarySurface: "interactive-architecture", supportSurface: "none" },
"architecture/runtime": { mode: "zoom", primarySurface: "interactive-architecture", supportSurface: "none" },
@@ -368,7 +368,7 @@
.architecture-scene .interactive-figure:has(.figure-node[data-active="true"])
.figure-node:not([data-active="true"]) {
opacity: 0.48;
opacity: 0.76;
}
.architecture-scene .figure-node[data-active="true"] {
@@ -15,7 +15,7 @@ describe("PresenterRoute", () => {
expect(screen.getByRole("main", { name: /lda.chat presenter notes/i })).toBeInTheDocument();
expect(screen.getByText(/This project began with the goal/i)).toBeInTheDocument();
expect(screen.getByText("the system underneath the chat").tagName).toBe("STRONG");
expect(screen.getByRole("navigation", { name: /presenter note navigation/i })).toHaveTextContent("1 / 42");
expect(screen.getByRole("navigation", { name: /presenter note navigation/i })).toHaveTextContent("1 / 43");
expect(screen.getByRole("link", { name: "Next →" })).toHaveAttribute("href", "#scene/thesis/substrate");
expect(screen.getByRole("link", { name: /open audience slide/i })).toHaveAttribute("href", "/present#scene/thesis/title");
expect(screen.queryByText(/live target/i)).not.toBeInTheDocument();
@@ -154,34 +154,41 @@ export const presenterNotes = [
["Thesis Workflow Lifecycle"],
{ qnaBranchIds: ["lifecycle-states", "run-persistence"] },
),
beatNote(
"architecture",
"overview",
7,
"First, the **implemented architecture spine** and its ownership boundaries.",
["Thesis System Architecture", "docs/project_map.md"],
),
beatNote(
"architecture",
"client",
13,
"Human operators and external agents enter through **the same public lifecycle surface**.",
10,
"Humans and agents share **one public lifecycle surface**.",
["Thesis System Architecture", "docs/project_map.md"],
),
beatNote(
"architecture",
"api",
13,
"**WorkflowApi owns lifecycle operations**; JSON-RPC adapts requests without owning domain behavior.",
11,
"WorkflowApi owns lifecycle operations; **JSON-RPC only adapts transport**.",
["Thesis System Architecture", "docs/source_architecture.md"],
{ qnaBranchIds: ["not-just-cli"] },
),
beatNote(
"architecture",
"runtime",
14,
"**WorkflowServer composes records, provider-neutral capabilities, WorkflowApi, and the execution kernel**; provider behavior remains outside the core.",
13,
"WorkflowServer composes **records, capabilities, API, and kernel**; providers remain outside the core.",
["Thesis System Architecture", "docs/source_architecture.md"],
{ qnaBranchIds: ["provider-security"] },
),
beatNote(
"architecture",
"node-use",
15,
"A NodeUse resolves bindings, **invokes its NodeDef handler**, reduces output into state, appends a trace frame, and routes the outcome.",
14,
"NodeUse **invokes a NodeDef handler**, reduces state, records trace, and routes the declared outcome.",
["Thesis Workflow Core Model"],
),
beatNote(
@@ -71,6 +71,17 @@ const renderArchitecture = (overrides: Partial<React.ComponentProps<typeof Archi
afterEach(() => cleanup());
describe("ArchitectureScene", () => {
it("keeps the overview beat neutral so the entire spine remains readable", () => {
renderArchitecture({
beat: { ...mockBeat, id: "overview" },
focusPath: [],
activeNodeId: null,
});
expect(screen.getByTestId("architecture-scene")).toHaveAttribute("data-architecture-beat", "overview");
expect(document.querySelector('.figure-node[data-active="true"]')).toBeNull();
});
it("renders the architecture spine and expands the capability boundary", () => {
const onFocusPathChange = vi.fn();
renderArchitecture({ focusPath: [], onFocusPathChange });
@@ -132,6 +132,7 @@ export const mainScenes = defineScenes([
evidencePointer: "Thesis System Architecture; docs/project_map.md; docs/source_architecture.md",
view: "architecture",
beats: [
sceneBeat("overview", "Architecture spine", "The implemented system separates its public surface, lifecycle records, provider boundary, and execution kernel.", { figure: { catalogId: "system-architecture", focusPath: [], activeNodeId: null } }),
sceneBeat("client", "Client operations", "Human and agent clients use the same public lifecycle surface.", { figure: { catalogId: "system-architecture", focusPath: [], activeNodeId: "client-operations" } }),
sceneBeat("api", "Transport and API", "JSON-RPC reaches WorkflowApi without owning domain behavior.", { figure: { catalogId: "system-architecture", focusPath: ["application-lifecycle"], activeNodeId: "workflow-api-boundary" } }),
sceneBeat("runtime", "Runtime and providers", "The runtime resolves provider-neutral capabilities and stores lifecycle records.", { figure: { catalogId: "system-architecture", focusPath: ["runtime-providers"], activeNodeId: "configured-providers" } }),