diff --git a/.mstar/knowledge/README.md b/.mstar/knowledge/README.md index 491bf5ac3..35c4a5732 100644 --- a/.mstar/knowledge/README.md +++ b/.mstar/knowledge/README.md @@ -18,9 +18,9 @@ Engineering reference for the Nexus OSS harness **knowledge** tree. | Document | Role | | --- | --- | | [crate-selection-best-practices.md](crate-selection-best-practices.md) | Rust workspace dependency conventions | -| [schemas-external-consumer-boundary.md](../specs/schemas-external-consumer-boundary.md) | **Moved to specs** (2026-08-17) — wire vs local-only contract types | -| [world-kb-runtime-architecture.md](../specs/world-kb-runtime-architecture.md) | **Moved to specs** (2026-08-17) — World KB implementation SSOT | -| [architecture-patterns/actor-bearer-boundary-composition.md](architecture-patterns/actor-bearer-boundary-composition.md) | Actor bearer boundary composition — stored admission, owner-scoped KE, exact session keys, shared memory pipeline, atomic ToM carrier writes (distilled from the shipped v1.184 Actor vertical; SSOT: [specs/actor-product-model.md](../specs/actor-product-model.md)) | +| [schemas-external-consumer-boundary.md](../specs/architecture/schemas-external-consumer-boundary.md) | **Moved to specs** (2026-08-17) — wire vs local-only contract types | +| [world-kb-runtime-architecture.md](../specs/architecture/world-kb-runtime-architecture.md) | **Moved to specs** (2026-08-17) — World KB implementation SSOT | +| [architecture-patterns/actor-bearer-boundary-composition.md](architecture-patterns/actor-bearer-boundary-composition.md) | Actor bearer boundary composition — stored admission, owner-scoped KE, exact session keys, shared memory pipeline, atomic ToM carrier writes (distilled from the shipped v1.184 Actor vertical; SSOT: [specs/architecture/actor-product-model.md](../specs/architecture/actor-product-model.md)) | | [architecture-patterns/canvas-surface-implementation-pattern.md](architecture-patterns/canvas-surface-implementation-pattern.md) | Canvas surface implementation pattern — six-layer coupled contract + projection data-completeness + spatial edges + fixture-projection + viewport guard + **layer 11 discoverability** (V1.67–V1.76 distilled; V1.108–V1.111 updates; compound V1.77/V1.109/V1.111) | | [architecture-patterns/spoke-adapter-conversion-seam.md](architecture-patterns/spoke-adapter-conversion-seam.md) | SPOKE adapter conversion-seam: product domain type ↔ spoke wire type; sole extension point for body schema evolution | | [architecture-patterns/action-registry-command-palette.md](architecture-patterns/action-registry-command-palette.md) | Action registry + command palette — module store + `useSyncExternalStore`, render-time `available?()`, `useHotkey` conflict-avoidance, WAI-ARIA combobox (V1.111 P0 distilled; compound V1.111) | @@ -342,14 +342,14 @@ Engineering reference for the Nexus OSS harness **knowledge** tree. | Document | Description | | --- | --- | -| [architecture-patterns/actor-maintenance-lifecycle-capture.md](architecture-patterns/actor-maintenance-lifecycle-capture.md) | Actor maintenance lifecycle + run capture — per-resource revision CAS (expected_revision, named conflict codes), internal lifecycle_epoch as a session fence (re-read under the exclusive fence), per-Character activity fence with busy-refusal (`character_busy`) held across effects, drain-authoritative capture from the `HostFacade::exec` stream, atomic cancel latch + bounded outcome memory, receipt-keyed immutable dedup + FK-backed provenance, bounded digest accumulation with checked arithmetic (distilled from the landed v1.185 Actor maintenance vertical; SSOT: [specs/actor-product-model.md](../specs/actor-product-model.md) §11) | +| [architecture-patterns/actor-maintenance-lifecycle-capture.md](architecture-patterns/actor-maintenance-lifecycle-capture.md) | Actor maintenance lifecycle + run capture — per-resource revision CAS (expected_revision, named conflict codes), internal lifecycle_epoch as a session fence (re-read under the exclusive fence), per-Character activity fence with busy-refusal (`character_busy`) held across effects, drain-authoritative capture from the `HostFacade::exec` stream, atomic cancel latch + bounded outcome memory, receipt-keyed immutable dedup + FK-backed provenance, bounded digest accumulation with checked arithmetic (distilled from the landed v1.185 Actor maintenance vertical; SSOT: [specs/architecture/actor-product-model.md](../specs/architecture/actor-product-model.md) §11) | | [engineering-conventions/canonical-invalid-input-422.md](engineering-conventions/canonical-invalid-input-422.md) | Canonical `invalid_input` → HTTP 422 convention — errors.rs is the mapping SSOT; the legacy `InvalidInput { field, reason }` variant is the same code but 400 (constructor decides status); JSON-Schema `maxLength` is codepoints while byte caps are runtime-enforced (summary 65,536 bytes); manual raw-query parsing where Axum extractors bypass the error envelope; spec-prose drift reconciliation (§11.1/§11.5/§11.6 three 400→422 alignments — check spec status tables against errors.rs before coding) | ### v1.187 additions | Document | Description | | --- | --- | -| [architecture-patterns/design-pair-token-compiler.md](architecture-patterns/design-pair-token-compiler.md) | Design-pair token compiler — one deterministic projection from `DESIGN.md`/`DESIGN.dark.md` to the three checked-in derived artifacts (`tokens.css`, package `theme.css`, generated brand snapshot); path-only projection registry, fail-closed null/empty/parity/duplicate-key/cycle rules, `generate` + byte-compare `check`, and the Studio Vite plugin that transforms the same CSS in memory (memoized compile, DESIGN files registered as watch inputs, full CSS-module invalidation, document-request re-read without a reload loop, no HMR source writes) (v1.187 P0 distilled; compound v1.187; normative contract: [specs/design-studio.md](../specs/design-studio.md) §3.5) | +| [architecture-patterns/design-pair-token-compiler.md](architecture-patterns/design-pair-token-compiler.md) | Design-pair token compiler — one deterministic projection from `DESIGN.md`/`DESIGN.dark.md` to the three checked-in derived artifacts (`tokens.css`, package `theme.css`, generated brand snapshot); path-only projection registry, fail-closed null/empty/parity/duplicate-key/cycle rules, `generate` + byte-compare `check`, and the Studio Vite plugin that transforms the same CSS in memory (memoized compile, DESIGN files registered as watch inputs, full CSS-module invalidation, document-request re-read without a reload loop, no HMR source writes) (v1.187 P0 distilled; compound v1.187; normative contract: [specs/surfaces/design-studio.md](../specs/surfaces/design-studio.md) §3.5) | | [architecture-patterns/iframe-pair-view-theme-isolation.md](architecture-patterns/iframe-pair-view-theme-isolation.md) | Same-origin iframe pair view with forced frame-local theme — two documents through the same Studio entrypoint plus an allowlisted `studio-embed=light\|dark` parameter; pre-render theme application; forced ThemeProvider bypassing storage/media listeners; a validated ready handshake (`origin` + `contentWindow` + theme/path) tied to the mounted lazy leaf; remount-by-key reset/retry; 640px local-scroll frames, 1024px two-column threshold (v1.187 P2 distilled; compound v1.187; spec §5.3) | | [architecture-patterns/studio-catalog-mount-then-focus.md](architecture-patterns/studio-catalog-mount-then-focus.md) | Studio catalog + mount-then-focus navigation contract — metadata-only `GalleryEntry` catalog with frozen ids, filterable section index with the full keyboard/no-results/Clear path, and the route→mount→focus protocol: bounded cancellable animation-frame retry that focuses the resolved heading (not the wrapper section) below measured sticky chrome; compare mode updates frame hashes instead of searching the parent document (v1.187 P2 distilled; compound v1.187; spec §5.4) | | [conventions/bounded-local-scroll-containment.md](conventions/bounded-local-scroll-containment.md) | Bounded local scrolling as the responsive containment pattern — keep `scrollWidth === clientWidth` at 1440/1280/390 and contain wide content in local scroll regions (`min-w-0` on grid/flex containers, `.studio-fixture-boundary`, keep-web table overflow wrappers, stacking rails, wrapping chrome/badges); never hide document overflow or delete/scale content (v1.187 P1+P2 distilled; compound v1.187) | diff --git a/.mstar/knowledge/api-design/governance-audience-strictness-runtime-guard.md b/.mstar/knowledge/api-design/governance-audience-strictness-runtime-guard.md index 6b3640513..e551e84a2 100644 --- a/.mstar/knowledge/api-design/governance-audience-strictness-runtime-guard.md +++ b/.mstar/knowledge/api-design/governance-audience-strictness-runtime-guard.md @@ -1,6 +1,6 @@ # Governance-Audience Strictness Needs a Runtime Guard -**Source:** v1.199 medium-residual convergence (`R4-audience-oneOf`, plan `2026-09-28-medium-residual-convergence`). SSOT for the audience contract: [holder-governance.md](../../specs/holder-governance.md). +**Source:** v1.199 medium-residual convergence (`R4-audience-oneOf`, plan `2026-09-28-medium-residual-convergence`). SSOT for the audience contract: [holder-governance.md](../../specs/architecture/holder-governance.md). ## Failure shape diff --git a/.mstar/knowledge/architecture-patterns/actor-bearer-boundary-composition.md b/.mstar/knowledge/architecture-patterns/actor-bearer-boundary-composition.md index c66cd71a5..713a2fa86 100644 --- a/.mstar/knowledge/architecture-patterns/actor-bearer-boundary-composition.md +++ b/.mstar/knowledge/architecture-patterns/actor-bearer-boundary-composition.md @@ -31,7 +31,7 @@ related_components: A Character crosses identity, World membership, knowledge, execution, memory, and mental-state storage. Isolation is sound only when every layer derives scope from stored rows and passes an admitted capability forward. Rechecking only the route payload, revision, or provider session id leaves cross-Actor seams. -Normative product semantics live in [Actor Product Model](../../specs/actor-product-model.md). This document captures the reusable implementation pattern validated by the shipped v1.184 Actor vertical ([Actor Product Model §10](../../specs/actor-product-model.md)); the v1.184 iteration package is a local process artifact and is not tracked at HEAD. +Normative product semantics live in [Actor Product Model](../../specs/architecture/actor-product-model.md). This document captures the reusable implementation pattern validated by the shipped v1.184 Actor vertical ([Actor Product Model §10](../../specs/architecture/actor-product-model.md)); the v1.184 iteration package is a local process artifact and is not tracked at HEAD. ## Guidance @@ -87,8 +87,8 @@ Apply this pattern when adding an Actor kind, widening World/binding visibility, Durable spec/source authority for each shipped slice (the v1.184 package files behind these remain historical provenance only): -- Actor identity and binding — [Actor Product Model §2/§4.2](../../specs/actor-product-model.md) -- Actor knowledge ownership and view — [Actor Product Model §5](../../specs/actor-product-model.md) -- Actor execution and session isolation — [Actor Product Model §6](../../specs/actor-product-model.md), [agent-host.md](../../specs/agent-host.md) -- Character SOUL and Memory — [Actor Product Model §4.1](../../specs/actor-product-model.md), [creator-memory-soul-lifecycle.md](../../specs/creator-memory-soul-lifecycle.md) -- Character ToM L1/L2 — [Actor Product Model §4.1](../../specs/actor-product-model.md), [spoke-adapter-architecture.md](../../specs/spoke-adapter-architecture.md) +- Actor identity and binding — [Actor Product Model §2/§4.2](../../specs/architecture/actor-product-model.md) +- Actor knowledge ownership and view — [Actor Product Model §5](../../specs/architecture/actor-product-model.md) +- Actor execution and session isolation — [Actor Product Model §6](../../specs/architecture/actor-product-model.md), [agent-host.md](../../specs/agents/agent-host.md) +- Character SOUL and Memory — [Actor Product Model §4.1](../../specs/architecture/actor-product-model.md), [creator-memory-soul-lifecycle.md](../../specs/creator/creator-memory-soul-lifecycle.md) +- Character ToM L1/L2 — [Actor Product Model §4.1](../../specs/architecture/actor-product-model.md), [spoke-adapter-architecture.md](../../specs/architecture/spoke-adapter-architecture.md) diff --git a/.mstar/knowledge/architecture-patterns/actor-maintenance-lifecycle-capture.md b/.mstar/knowledge/architecture-patterns/actor-maintenance-lifecycle-capture.md index 2cedb1269..214ca865a 100644 --- a/.mstar/knowledge/architecture-patterns/actor-maintenance-lifecycle-capture.md +++ b/.mstar/knowledge/architecture-patterns/actor-maintenance-lifecycle-capture.md @@ -32,7 +32,7 @@ related_components: The v1.185 developer loop added material mutation and reversible freeze to the shipped Actor vertical: identity edit, archive/restore, WorldSheet maintenance, bounded KE content maintenance, and an opted-in run-to-memory capture. Three well-known concurrency mechanisms are individually insufficient here: SQLite row CAS does not cover Host sessions or file effects, a provider session can outlive a DB transaction, and a server-owned stream ends on the Host's schedule, not the request's. The pattern combines **per-resource revision CAS**, an **internal lifecycle epoch**, a **per-Character activity fence**, and a **drain-authoritative capture** with a receipt-keyed immutable dedup. -Normative product semantics: [Actor Product Model §11](../../specs/actor-product-model.md). The sibling composition doc covers the shipped v1.184 admission/bearer boundaries: [actor-bearer-boundary-composition.md](actor-bearer-boundary-composition.md). +Normative product semantics: [Actor Product Model §11](../../specs/architecture/actor-product-model.md). The sibling composition doc covers the shipped v1.184 admission/bearer boundaries: [actor-bearer-boundary-composition.md](actor-bearer-boundary-composition.md). Rejected option (kept as explicit non-goal): archive cancels all sessions, persists conversation/job history, and reconstructs capture from broadcast or SSE. Cancellation cannot atomically roll back provider or file effects, broadcasts are lossy, and persistent history is out of scope. Busy is refused, never forced. @@ -123,4 +123,4 @@ Each mechanism covers what the others cannot. Row CAS protects the SQLite truth; - Drain, digest, persist — `crates/nexus-daemon-runtime/src/actor_run_capture.rs` (`drain_and_finalize_character_operation`, `try_persist_capture`, `DrainAccumulator`, `build_capture_digest`). - Receipt dedup, provenance — `crates/nexus-local-db/src/character_pending_review.rs` (`capture_character_run`, `capture_character_run_in_tx`, `receipt_matches_input`), migration `crates/nexus-local-db/migrations/20260906000003_character_run_capture.sql`. - Stale-session rejection and session admission order — `crates/nexus-daemon-runtime/src/api/handlers/agent_host.rs` (`prepare_prompt`, retired-session paths). -- Published slice — the v1.185 iteration package is a local process artifact (not tracked at HEAD); the durable authorities are [§11](../../specs/actor-product-model.md) plus the sources above. +- Published slice — the v1.185 iteration package is a local process artifact (not tracked at HEAD); the durable authorities are [§11](../../specs/architecture/actor-product-model.md) plus the sources above. diff --git a/.mstar/knowledge/architecture-patterns/connect-host-opt-in-feature-gate.md b/.mstar/knowledge/architecture-patterns/connect-host-opt-in-feature-gate.md index 5b5fabdf6..f87f9c4b4 100644 --- a/.mstar/knowledge/architecture-patterns/connect-host-opt-in-feature-gate.md +++ b/.mstar/knowledge/architecture-patterns/connect-host-opt-in-feature-gate.md @@ -90,5 +90,5 @@ V1.148 P3 adopted `spoke-connect` (libp2p + noise + yamux + Ed25519 signed-hello ## Examples - V1.148 P3 `crates/nexus-spoke-adapter/src/manifest.rs` (shared builder), `apps/nexus42/src/commands/connect/{mod,identity,allowlist,interop}.rs` (Connect Host + interop), `crates/nexus-home-layout/src/device_id.rs` (host_id SSOT). -- Spec: `.mstar/specs/spoke-adapter-architecture.md` §10 (Connect Host N-C0 normative surface). +- Spec: `.mstar/specs/architecture/spoke-adapter-architecture.md` §10 (Connect Host N-C0 normative surface). - The N-C series shipped end-to-end: **N-C1 (V1.153)** — write-op exchange; **N-C2 (V1.154)**; **N-C3 (V1.155)**. Capability-token production (issuance CLI + `config.json` enforcement + PeerScope intersection) shipped in **V1.155 P1**. diff --git a/.mstar/knowledge/architecture-patterns/contracts-gap-on-shipped-backend.md b/.mstar/knowledge/architecture-patterns/contracts-gap-on-shipped-backend.md index 2e351ce4c..885c431f9 100644 --- a/.mstar/knowledge/architecture-patterns/contracts-gap-on-shipped-backend.md +++ b/.mstar/knowledge/architecture-patterns/contracts-gap-on-shipped-backend.md @@ -50,6 +50,6 @@ When you discover (or are asked to consume) a shipped Local API handler whose re ## See Also -- [schemas-external-consumer-boundary.md](../../specs/schemas-external-consumer-boundary.md) — wire vs local-only contract types (external consumer side). +- [schemas-external-consumer-boundary.md](../../specs/architecture/schemas-external-consumer-boundary.md) — wire vs local-only contract types (external consumer side). - [crate-selection-best-practices.md](../crate-selection-best-practices.md) — Rust workspace dependency conventions. - [`AGENTS.md`](../../../AGENTS.md) — the single-truth-source-for-DTOs invariant (`crates/nexus-daemon-runtime/AGENTS.md`, which restated it, was deleted with the crate in v1.193 P2). diff --git a/.mstar/knowledge/architecture-patterns/daemon-api-remote-bind-gate.md b/.mstar/knowledge/architecture-patterns/daemon-api-remote-bind-gate.md index 199c1ad70..8bb3f95a4 100644 --- a/.mstar/knowledge/architecture-patterns/daemon-api-remote-bind-gate.md +++ b/.mstar/knowledge/architecture-patterns/daemon-api-remote-bind-gate.md @@ -85,5 +85,5 @@ Use this pattern whenever a local-first service adds an opt-in remote listener. - Implementation: `crates/nexus-daemon-runtime/src/boot.rs` - Auth middleware: `crates/nexus-daemon-runtime/src/api/auth_middleware.rs` -- Spec: `.mstar/specs/daemon-runtime.md` -- Surface conventions: `.mstar/specs/daemon-api-surface-conventions.md` +- Spec: `.mstar/specs/archived/daemon-runtime.md` +- Surface conventions: `.mstar/specs/runtime/daemon-api-surface-conventions.md` diff --git a/.mstar/knowledge/architecture-patterns/daemon-ready-gate-pattern.md b/.mstar/knowledge/architecture-patterns/daemon-ready-gate-pattern.md index 1b7bad058..46666bbf1 100644 --- a/.mstar/knowledge/architecture-patterns/daemon-ready-gate-pattern.md +++ b/.mstar/knowledge/architecture-patterns/daemon-ready-gate-pattern.md @@ -86,7 +86,7 @@ V1.110 optimized the cold-start path. Previously `start_with_budget` ran the ful V1.96 () hit a P0 blocker: the setup wizard Step 2 hung indefinitely in "Starting daemon…" on a clean `~/.nexus42/` first launch. RCA revealed **three** consumer-side root causes (pre-V1.118, the daemon also crashed within milliseconds when `WorkspaceState::initialize()` found no `active_creator_id`; the wizard just never learned about it). The fixes distill into four durable rules that apply to **any** observer of a process lifecycle event stream, not just the daemon-ready gate. -> **V1.118 supersession (daemon no-Profile boot):** After V1.118 P0 ships, clean home reaches T0 health without `active_creator_id`; the gate opens on `running` and Profile selection is post-gate business flow. Crash-on-no-creator RCA below is **pre-V1.118** only. See [daemon-runtime.md §17](../../specs/daemon-runtime.md) + [desktop-shell.md §13.11](../../specs/desktop-shell.md). +> **V1.118 supersession (daemon no-Profile boot):** After V1.118 P0 ships, clean home reaches T0 health without `active_creator_id`; the gate opens on `running` and Profile selection is post-gate business flow. Crash-on-no-creator RCA below is **pre-V1.118** only. See [daemon-runtime.md §17](../../specs/archived/daemon-runtime.md) + [desktop-shell.md §13.11](../../specs/surfaces/desktop-shell.md). ### Rule 5: probe current state on mount, BEFORE subscribing diff --git a/.mstar/knowledge/architecture-patterns/design-pair-token-compiler.md b/.mstar/knowledge/architecture-patterns/design-pair-token-compiler.md index 8a1ef1413..823db0d6f 100644 --- a/.mstar/knowledge/architecture-patterns/design-pair-token-compiler.md +++ b/.mstar/knowledge/architecture-patterns/design-pair-token-compiler.md @@ -28,7 +28,7 @@ tags: Before v1.187, `tooling/design-tokens` shipped a hand-maintained `tokens.css` plus a `check-tokens.mjs` gate that searched strings in handwritten CSS and preset files. That gate could only find literals it was told to search: a DESIGN edit that changed a value without a matching handwritten update either shipped stale CSS or was invisible to the check entirely. The design-language overhaul (full palette, type stack, radius, motion and elevation change in one revision) made the gap unacceptable — every changed token had to flow from the DESIGN pair with no second transcription. -The replacement is a single build-time compiler, `tooling/design-tokens/scripts/project-tokens.mjs`, that owns the entire projection from the repo-root DESIGN pair to every derived artifact. The normative contract is [.mstar/specs/design-studio.md](../../specs/design-studio.md) §3.5. +The replacement is a single build-time compiler, `tooling/design-tokens/scripts/project-tokens.mjs`, that owns the entire projection from the repo-root DESIGN pair to every derived artifact. The normative contract is [.mstar/specs/surfaces/design-studio.md](../../specs/surfaces/design-studio.md) §3.5. ## Guidance diff --git a/.mstar/knowledge/architecture-patterns/electron-desktop-trust-boundary.md b/.mstar/knowledge/architecture-patterns/electron-desktop-trust-boundary.md index ebd37babb..54bc99ef8 100644 --- a/.mstar/knowledge/architecture-patterns/electron-desktop-trust-boundary.md +++ b/.mstar/knowledge/architecture-patterns/electron-desktop-trust-boundary.md @@ -83,8 +83,8 @@ The live-generation source is a **required** option, validated before registrati - The connection store (`src/connection-store.ts`) keeps `credential` as safeStorage ciphertext in `userData/connection-config.enc` (dir 0700, file 0600, atomic temp+rename). `get()` returns a **public projection with no key**; only `getAuth()` (main-side) returns the active credential for network injection. - `attachDesktopNetworkHooks` strips renderer-supplied `X-API-Key` (case-insensitively) and injects the stored key only for fetch/XHR whose URL's **exact origin** equals the pinned endpoint and whose path starts with `/v1/daemon/`; redirect targets leaving the origin get nothing; inactive/keyless config injects nothing. - Encryption unavailable → explicit `secure_storage_unavailable`, never a plaintext fallback; a failed encryption is non-destructive (encrypt before atomic write). An endpoint change cannot retain the previous endpoint's credential. -- **Clear must be durable.** `delete()` writes a non-secret tombstone (`connection-config.cleared`) after the store file is confirmed gone, and `open()` checks the tombstone before the one-time legacy import. Without it, "clear never reimports" holds only for the current call: the next launch re-imports the untouched legacy key. (Deviation D-18 in `.mstar/specs/desktop-shell.md`: no persisted-secret readback, no plaintext-write fallback, and a deleted credential must not reappear.) -- The one-time legacy import reads the old macOS keychain entry (`/usr/bin/security find-generic-password`; no shell; the secret is never logged or returned) **and** the old app-data JSON, then migrates in the ordered v1.194 P1 sequence: validate → encrypt → successful encrypted persist (atomic, decrypt-checked) → **delete both legacy sources** → publish. Nothing is deleted after a parse/URL/encrypt/persist failure, and the plaintext originals stay readable until the encrypted bytes are readable. A cleanup refusal is explicit but **non-fatal**: it is reported as the sanitized structured `legacy_credential_cleanup_failed`, observable as `ConnectionStore.legacyCleanupFailure`, leaves the readable encrypted store and any remaining legacy source intact, and the next successful open retries the same idempotent cleanup (keychain item-not-found and file `ENOENT` count as already clean). The import path is installed only together with its paired cleanup capability, so a migration cannot silently leave the plaintext originals behind. Proof is headless at the store/host seams — the exact keychain argv, the ordering and the failure mapping are pinned without touching the real keychain — so no live keychain, `safeStorage` or GUI qualification is implied. (`apps/desktop-electron/src/connection-store.ts`, `src/main.ts`; contract in `.mstar/specs/desktop-shell.md` §5.) +- **Clear must be durable.** `delete()` writes a non-secret tombstone (`connection-config.cleared`) after the store file is confirmed gone, and `open()` checks the tombstone before the one-time legacy import. Without it, "clear never reimports" holds only for the current call: the next launch re-imports the untouched legacy key. (Deviation D-18 in `.mstar/specs/surfaces/desktop-shell.md`: no persisted-secret readback, no plaintext-write fallback, and a deleted credential must not reappear.) +- The one-time legacy import reads the old macOS keychain entry (`/usr/bin/security find-generic-password`; no shell; the secret is never logged or returned) **and** the old app-data JSON, then migrates in the ordered v1.194 P1 sequence: validate → encrypt → successful encrypted persist (atomic, decrypt-checked) → **delete both legacy sources** → publish. Nothing is deleted after a parse/URL/encrypt/persist failure, and the plaintext originals stay readable until the encrypted bytes are readable. A cleanup refusal is explicit but **non-fatal**: it is reported as the sanitized structured `legacy_credential_cleanup_failed`, observable as `ConnectionStore.legacyCleanupFailure`, leaves the readable encrypted store and any remaining legacy source intact, and the next successful open retries the same idempotent cleanup (keychain item-not-found and file `ENOENT` count as already clean). The import path is installed only together with its paired cleanup capability, so a migration cannot silently leave the plaintext originals behind. Proof is headless at the store/host seams — the exact keychain argv, the ordering and the failure mapping are pinned without touching the real keychain — so no live keychain, `safeStorage` or GUI qualification is implied. (`apps/desktop-electron/src/connection-store.ts`, `src/main.ts`; contract in `.mstar/specs/surfaces/desktop-shell.md` §5.) ### 8. Non-secret runtime metadata is validated and fail-closed diff --git a/.mstar/knowledge/architecture-patterns/iframe-pair-view-theme-isolation.md b/.mstar/knowledge/architecture-patterns/iframe-pair-view-theme-isolation.md index 212313b67..2b456a7dc 100644 --- a/.mstar/knowledge/architecture-patterns/iframe-pair-view-theme-isolation.md +++ b/.mstar/knowledge/architecture-patterns/iframe-pair-view-theme-isolation.md @@ -20,7 +20,7 @@ tags: # Same-origin iframe pair view with forced frame-local theme -**Track**: Knowledge (distilled from the v1.187 Studio pair view; normative detail in [.mstar/specs/design-studio.md](../../specs/design-studio.md) §5.3). +**Track**: Knowledge (distilled from the v1.187 Studio pair view; normative detail in [.mstar/specs/surfaces/design-studio.md](../../specs/surfaces/design-studio.md) §5.3). ## Context diff --git a/.mstar/knowledge/architecture-patterns/local-environment-scan-safety-boundary.md b/.mstar/knowledge/architecture-patterns/local-environment-scan-safety-boundary.md index bf61f78d5..399cd751b 100644 --- a/.mstar/knowledge/architecture-patterns/local-environment-scan-safety-boundary.md +++ b/.mstar/knowledge/architecture-patterns/local-environment-scan-safety-boundary.md @@ -25,7 +25,7 @@ The challenge: **the daemon is executing subprocesses (` --version`) on ## Guidance (the pattern) -The `scan_local_installations` helper enforces **five normative constraints** (codified in `specs/desktop-shell.md` §14.3). All five are required; any one missing opens an attack surface. +The `scan_local_installations` helper enforces **five normative constraints** (codified in `specs/surfaces/desktop-shell.md` §14.3). All five are required; any one missing opens an attack surface. | # | Constraint | Reason | |---|------------|--------| diff --git a/.mstar/knowledge/architecture-patterns/native-cli-provider-adapter-pattern.md b/.mstar/knowledge/architecture-patterns/native-cli-provider-adapter-pattern.md index 8585ec686..b1b7a6178 100644 --- a/.mstar/knowledge/architecture-patterns/native-cli-provider-adapter-pattern.md +++ b/.mstar/knowledge/architecture-patterns/native-cli-provider-adapter-pattern.md @@ -62,9 +62,9 @@ these boundaries when changing the adapter, boot path or public catalog: exit proof does not justify a process-tree/restart no-leak claim or a blind PID kill. A sealed deny-all profile is model-tool denial, not an OS sandbox. -Durable contracts: [agent-host](../../specs/agent-host.md) §§5–8, -[workspace OCC/recovery](../../specs/concurrency.md) §9 and -[run settlement/replay](../../specs/daemon-runtime.md) §20. +Durable contracts: [agent-host](../../specs/agents/agent-host.md) §§5–8, +[workspace OCC/recovery](../../specs/runtime/concurrency.md) §9 and +[run settlement/replay](../../specs/archived/daemon-runtime.md) §20. Derived from verified V1.188 P0–P4 runtime, recovery and review evidence; the public first-run/Quick Start/live-model composition was explicitly deferred. diff --git a/.mstar/knowledge/architecture-patterns/spoke-adapter-port-orchestration-adoption.md b/.mstar/knowledge/architecture-patterns/spoke-adapter-port-orchestration-adoption.md index 45b6f6ee5..d14279a6a 100644 --- a/.mstar/knowledge/architecture-patterns/spoke-adapter-port-orchestration-adoption.md +++ b/.mstar/knowledge/architecture-patterns/spoke-adapter-port-orchestration-adoption.md @@ -131,7 +131,7 @@ A common mistake (made and corrected during V1.141 P1 T2): collapse both mismatc ## Production boundary (shipped V1.142; updated V1.146) -> **Update (V1.142):** The production `BaselinePorts` implementation (`NexusAdapter`, V1.146 rename) was originally landed in `nexus-local-db/src/spoke_adapter/`, **not** "downstream in nexus-knowledge" as the V1.141 doc speculated. `nexus-knowledge` is a domain-types-and-traits crate with no SQLite dependency — it cannot be the production port home. V1.145 P1b rehomed the adapter to `nexus-spoke-adapter/src/adapter/` (spec §7.4 / §8 dep-graph reversal). See spec [`spoke-adapter-architecture.md`](../../specs/spoke-adapter-architecture.md) §7.4 for the production-vs-stub matrix and dependency rationale. +> **Update (V1.142):** The production `BaselinePorts` implementation (`NexusAdapter`, V1.146 rename) was originally landed in `nexus-local-db/src/spoke_adapter/`, **not** "downstream in nexus-knowledge" as the V1.141 doc speculated. `nexus-knowledge` is a domain-types-and-traits crate with no SQLite dependency — it cannot be the production port home. V1.145 P1b rehomed the adapter to `nexus-spoke-adapter/src/adapter/` (spec §7.4 / §8 dep-graph reversal). See spec [`spoke-adapter-architecture.md`](../../specs/architecture/spoke-adapter-architecture.md) §7.4 for the production-vs-stub matrix and dependency rationale. V1.142 shipped the production adapter in `nexus-local-db` implementing all 6 baseline port families against existing SQLite storage (V1.145 P1b rehome to `nexus-spoke-adapter`): diff --git a/.mstar/knowledge/architecture-patterns/spoke-dialect-default-on-engine.md b/.mstar/knowledge/architecture-patterns/spoke-dialect-default-on-engine.md index 09e04458b..050cf0cd7 100644 --- a/.mstar/knowledge/architecture-patterns/spoke-dialect-default-on-engine.md +++ b/.mstar/knowledge/architecture-patterns/spoke-dialect-default-on-engine.md @@ -60,7 +60,7 @@ Multi-byte (CJK) keys + `whole_word` match: advancing `offset = start + 1` split - V1.149 P0 `crates/nexus-spoke-adapter/src/adapter/activation.rs` (default-on engine, truth-table logic, `regex` crate match, char-boundary whole_word, neutral-only golden). - V1.149 P1 `expand_relation_hops` + `NexusAdapter::list_hop_edges_for_world` (graph hops via storage list, pre_visited dedup). -- Spec: `.mstar/specs/spoke-adapter-architecture.md` §7.4 Lore activation engine (normative contract). +- Spec: `.mstar/specs/architecture/spoke-adapter-architecture.md` §7.4 Lore activation engine (normative contract). - Spoke handbook: `spoke/.mstar/specs/domain-profile-lore-activation.md` (the dialect — consumer-only). --- @@ -96,5 +96,5 @@ Slot filling is gated by the creator-workflow `stage` (`intake`/`research`/`prod - V1.150 P0 `crates/nexus-moment-context-assembly/src/slots.rs` (slot routing + emit order; gated behind `activation_enabled`). - V1.150 P1 `crates/nexus-moment-context-assembly/src/directive.rs` + `crates/nexus-local-db/src/moment_directive.rs` (Moment Directive + `DirectiveStore` trait + `NoDirectiveStore` default + compile-time `query_as!`). - V1.150 P2 `crates/nexus-moment-context-assembly/src/generation.rs` (`apply_stage_gate` §4 matrix; `Unspecified` zero-cost pass-through). -- Spec: `.mstar/specs/spoke-adapter-architecture.md` §7.4 (V1.150 slot + Directive matrix promoted by P2 sweep). +- Spec: `.mstar/specs/architecture/spoke-adapter-architecture.md` §7.4 (V1.150 slot + Directive matrix promoted by P2 sweep). - Iteration guide: `mca-section-audit.md` (MCA section-heading evidence). diff --git a/.mstar/knowledge/architecture-patterns/spoke-op-gate-at-adapter-boundary.md b/.mstar/knowledge/architecture-patterns/spoke-op-gate-at-adapter-boundary.md index 1e9d2c73c..de295c7f3 100644 --- a/.mstar/knowledge/architecture-patterns/spoke-op-gate-at-adapter-boundary.md +++ b/.mstar/knowledge/architecture-patterns/spoke-op-gate-at-adapter-boundary.md @@ -18,8 +18,8 @@ consolidation_review: spoke-adapter-port-orchestration-adoption.md (Surface B) + V1.164 P2 added the `mind_states` table. The first implementation (a10d5e4e) put `spoke_operations::validate_mind_state` **inside `nexus-local-db`** (new direct dep) — "the validator gates the write path, so it lives with the writer." That violated the normative layering, which is easy to miss because it is stated in **three places, none of which is the crate itself**: -- `.mstar/specs/entity-scope-model.md` — nexus-spoke-adapter is "**the sole crate that directly depends on spoke-operations**" -- `.mstar/specs/spoke-adapter-architecture.md` — nexus-local-db = "**Pure storage** ... no spoke types or dep on spoke-adapter" +- `.mstar/specs/architecture/entity-scope-model.md` — nexus-spoke-adapter is "**the sole crate that directly depends on spoke-operations**" +- `.mstar/specs/architecture/spoke-adapter-architecture.md` — nexus-local-db = "**Pure storage** ... no spoke types or dep on spoke-adapter" - `crates/nexus-local-db/AGENTS.md` — records V1.146 **removing** exactly this dep once before ## Guidance diff --git a/.mstar/knowledge/architecture-patterns/studio-catalog-mount-then-focus.md b/.mstar/knowledge/architecture-patterns/studio-catalog-mount-then-focus.md index 9cbaa5edf..99db29c52 100644 --- a/.mstar/knowledge/architecture-patterns/studio-catalog-mount-then-focus.md +++ b/.mstar/knowledge/architecture-patterns/studio-catalog-mount-then-focus.md @@ -20,7 +20,7 @@ tags: # Studio catalog + mount-then-focus navigation contract -**Track**: Knowledge (distilled from the v1.187 Studio workspace; normative detail in [.mstar/specs/design-studio.md](../../specs/design-studio.md) §5.4). +**Track**: Knowledge (distilled from the v1.187 Studio workspace; normative detail in [.mstar/specs/surfaces/design-studio.md](../../specs/surfaces/design-studio.md) §5.4). ## Context diff --git a/.mstar/knowledge/architecture-patterns/third-party-codegen-adoption.md b/.mstar/knowledge/architecture-patterns/third-party-codegen-adoption.md index 2cf344ac0..b6ba0f8b1 100644 --- a/.mstar/knowledge/architecture-patterns/third-party-codegen-adoption.md +++ b/.mstar/knowledge/architecture-patterns/third-party-codegen-adoption.md @@ -89,7 +89,7 @@ Typify derives `Display` and `FromStr` on string enums. Hand-written duplicate i Typify maps `format: date-time` to `chrono::DateTime<…>`. Serde's default serialization for `DateTime` can differ from the bespoke generator's `String` RFC3339 fields — affecting canonical hash fixtures in cloud-sync specs. -**Residual (closed 2026-08-08):** `R-V1138P1-001` — spec golden hashes updated after the new serialization was verified wire-correct (no behavioral regression); see [`../../specs/canonical-hash.md`](../../specs/canonical-hash.md). +**Residual (closed 2026-08-08):** `R-V1138P1-001` — spec golden hashes updated after the new serialization was verified wire-correct (no behavioral regression); see [`../../specs/contracts/canonical-hash.md`](../../specs/contracts/canonical-hash.md). ### 4. Consumer adaptation is mechanical but cross-crate @@ -124,7 +124,7 @@ Typify inlines a distinct struct copy for every schema that references a shared | [`schemas/AGENTS.md`](../../../schemas/AGENTS.md) | Schema authoring + codegen flow | | [`contracts-gap-on-shipped-backend.md`](contracts-gap-on-shipped-backend.md) | Closing schema gaps on shipped handlers (orthogonal but same contracts boundary) | | Residuals `R-V1138P0-*` | Closed 2026-08-08 (V1.155 P2 residual sweep) | -| Residual `R-V1138P1-001` | Canonical-hash spec golden sync — closed 2026-08-08; spec at [`../../specs/canonical-hash.md`](../../specs/canonical-hash.md) | +| Residual `R-V1138P1-001` | Canonical-hash spec golden sync — closed 2026-08-08; spec at [`../../specs/contracts/canonical-hash.md`](../../specs/contracts/canonical-hash.md) | ## Evidence diff --git a/.mstar/knowledge/architecture-patterns/typed-authority-carriers-and-fences.md b/.mstar/knowledge/architecture-patterns/typed-authority-carriers-and-fences.md index a29f5ed93..8f8118db6 100644 --- a/.mstar/knowledge/architecture-patterns/typed-authority-carriers-and-fences.md +++ b/.mstar/knowledge/architecture-patterns/typed-authority-carriers-and-fences.md @@ -177,4 +177,4 @@ Generated wire request/response DTOs remain the transport contract; `AdmittedAct - Single-owner reservation — `crates/nexus-core/src/execution/lifecycle.rs` (`OWNERS`, `OwnerReservation`, `claim`/`install`/`Drop`, `release_owner_slot` with `Arc::ptr_eq`). - Established-owner slot — `crates/nexus-core/src/host.rs` (`open_host` admission, failure-clears-slot, confirmed-close release); duplicate-open refusal covered by `crates/nexus-core/tests/host_actor_lifecycle.rs`. - Single session-index owner — `crates/nexus-core/src/actor_sessions.rs` (`ActorSessionRegistry` delegating activity admission to the P2 lease rather than keeping a second fence table). -- Durable semantics this implements — [specs/actor-product-model.md](../../specs/actor-product-model.md) §11. +- Durable semantics this implements — [specs/architecture/actor-product-model.md](../../specs/architecture/actor-product-model.md) §11. diff --git a/.mstar/knowledge/architecture-patterns/user-layer-entrance-split.md b/.mstar/knowledge/architecture-patterns/user-layer-entrance-split.md index 4a6c8af8e..8080841bd 100644 --- a/.mstar/knowledge/architecture-patterns/user-layer-entrance-split.md +++ b/.mstar/knowledge/architecture-patterns/user-layer-entrance-split.md @@ -79,4 +79,4 @@ See §3 table for the four enforcement-path failures and fixes. Structural ancho - Settings host pattern: [settings-modal-primary-host.md](settings-modal-primary-host.md) - `setup_completed` asymmetry: [asymmetric-setup-completed-context.md](asymmetric-setup-completed-context.md) - Shell IA: [workspace-parent-shell-ia.md](workspace-parent-shell-ia.md) -- Specs: `.mstar/specs/web-ui.md`, `.mstar/specs/desktop-shell.md`; iteration spec `.mstar/iterations/v1.170/specs/v1.170-entrance-locks.md` EL-1..EL-8 + AR-15..AR-22 +- Specs: `.mstar/specs/surfaces/web-ui.md`, `.mstar/specs/surfaces/desktop-shell.md`; iteration spec `.mstar/iterations/v1.170/specs/v1.170-entrance-locks.md` EL-1..EL-8 + AR-15..AR-22 diff --git a/.mstar/knowledge/conventions/bounded-local-scroll-containment.md b/.mstar/knowledge/conventions/bounded-local-scroll-containment.md index e8bbd732c..5a1b55287 100644 --- a/.mstar/knowledge/conventions/bounded-local-scroll-containment.md +++ b/.mstar/knowledge/conventions/bounded-local-scroll-containment.md @@ -20,7 +20,7 @@ tags: # Bounded local scrolling as the responsive containment pattern -**Track**: Knowledge (distilled from the v1.187 Studio workspace acceptance; rule stated in [DESIGN.md](../../../DESIGN.md) §Spacing & Layout and [.mstar/specs/design-studio.md](../../specs/design-studio.md) §6). +**Track**: Knowledge (distilled from the v1.187 Studio workspace acceptance; rule stated in [DESIGN.md](../../../DESIGN.md) §Spacing & Layout and [.mstar/specs/surfaces/design-studio.md](../../specs/surfaces/design-studio.md) §6). ## Context diff --git a/.mstar/knowledge/crate-selection-best-practices.md b/.mstar/knowledge/crate-selection-best-practices.md index 98940f459..5c884e22c 100644 --- a/.mstar/knowledge/crate-selection-best-practices.md +++ b/.mstar/knowledge/crate-selection-best-practices.md @@ -19,7 +19,7 @@ This document does **not** override: - `AGENTS.md` — release discipline, codegen rules, reachability rules. - `v1-spec/` (ADRs / codegen strategy / wire schemas) — wire and protocol decisions (e.g. `agent-client-protocol` SDK pin) remain owned there. -- Architecture SSOTs — **`specs/local-cloud-crate-architecture.md`** (crate graph & local/cloud lines), `orchestration-engine.md`, `daemon-runtime.md`, [`creator-schedule-and-core-context.md`](../specs/creator-schedule-and-core-context.md), [`acp-client-tech-spec.md`](../specs/acp-client-tech-spec.md), [`schemas-external-consumer-boundary.md`](../specs/schemas-external-consumer-boundary.md). +- Architecture SSOTs — **`specs/archived/local-cloud-crate-architecture.md`** (crate graph & local/cloud lines), `orchestration-engine.md`, `daemon-runtime.md`, [`creator-schedule-and-core-context.md`](../specs/orchestration/creator-schedule-and-core-context.md), [`acp-client-tech-spec.md`](../specs/agents/acp-client-tech-spec.md), [`schemas-external-consumer-boundary.md`](../specs/architecture/schemas-external-consumer-boundary.md). **Conflict order**: `AGENTS.md` > `v1-spec` / ADR > architecture SSOTs > this document > other knowledge. @@ -72,7 +72,7 @@ Changing a decision in §2 follows the flow in §4. Do not silently swap crates, | 2.4 | **Platform user auth / JWT** | `jsonwebtoken` only | `oauth2` v5.x (deferred — not rejected) | TD-10 deferral (retired device-flow exploration) | | 2.5 | **Challenge arithmetic evaluator** | Hand-rolled shunting-yard (current implementation under `crates/nexus42/src/challenge/`) | `meval`; `evalexpr` | §3.5 below (DoS guard TODOs tracked here) | | 2.6 | **File watcher** (deferred) | Recommended stack when implemented: `notify` 8 + `notify-debouncer-full` + async mpsc | Raw `RecommendedWatcher` only | `crates/nexus42d/src/workspace/mod.rs` (deferral note) | -| 2.7 | **Cron / scheduler** (V1.5 — implemented) | **V1.5 WS-D implemented** a hand-rolled clock poller in `crates/nexus-orchestration/src/scheduler/` using `cron` + `chrono-tz`. The four constraints from §3.7 are satisfied. See [`creator-schedule-and-core-context.md`](../specs/creator-schedule-and-core-context.md) for the full design. | `tokio-cron-scheduler` 0.15.x (rejected); hand-rolled `cron` + `chrono-tz` + `sleep_until` (**selected & shipped**) | [`creator-schedule-and-core-context.md`](../specs/creator-schedule-and-core-context.md) | +| 2.7 | **Cron / scheduler** (V1.5 — implemented) | **V1.5 WS-D implemented** a hand-rolled clock poller in `crates/nexus-orchestration/src/scheduler/` using `cron` + `chrono-tz`. The four constraints from §3.7 are satisfied. See [`creator-schedule-and-core-context.md`](../specs/orchestration/creator-schedule-and-core-context.md) for the full design. | `tokio-cron-scheduler` 0.15.x (rejected); hand-rolled `cron` + `chrono-tz` + `sleep_until` (**selected & shipped**) | [`creator-schedule-and-core-context.md`](../specs/orchestration/creator-schedule-and-core-context.md) | | 2.8 | **Layered config** (future) | `figment` + `secrecy` for redaction (when needed) | `config-rs`; hand-rolled | — (not yet scheduled) | | 2.9 | **Snapshot testing** (dev) | Recommended: `insta` + redactions for new CLI/HTTP integration tests | Hand-rolled golden files | — (optional; per-test-author discretion) | @@ -231,7 +231,7 @@ sqlx = { version = "0.8", default-features = false, features = [ ### 3.7 Cron / scheduler — V1.4 defers; V1.5 decides -**Decision**: V1.4 does **not** select a scheduler crate. `orchestration-engine.md` defers wall-clock cron to V1.5+; [`creator-schedule-and-core-context.md`](../specs/creator-schedule-and-core-context.md) (WS7) delivers only the data model + state machine. +**Decision**: V1.4 does **not** select a scheduler crate. `orchestration-engine.md` defers wall-clock cron to V1.5+; [`creator-schedule-and-core-context.md`](../specs/orchestration/creator-schedule-and-core-context.md) (WS7) delivers only the data model + state machine. **Constraints any future implementation must satisfy** (binding on V1.5 design): @@ -313,8 +313,8 @@ Before editing any of the above in a way that changes crate selection, update ** ## 6. References -- Orchestration engine SSOT: [`orchestration-engine.md`](../specs/orchestration-engine.md) -- Schedule / core context SSOT: [`creator-schedule-and-core-context.md`](../specs/creator-schedule-and-core-context.md) +- Orchestration engine SSOT: [`orchestration-engine.md`](../specs/orchestration/orchestration-engine.md) +- Schedule / core context SSOT: [`creator-schedule-and-core-context.md`](../specs/orchestration/creator-schedule-and-core-context.md) - Repository-wide rules: [`AGENTS.md`](AGENTS.md) — §"Documentation & plans", dependency / release discipline. --- diff --git a/.mstar/knowledge/engineering-conventions/canonical-invalid-input-422.md b/.mstar/knowledge/engineering-conventions/canonical-invalid-input-422.md index aa92b19da..a5502a3c0 100644 --- a/.mstar/knowledge/engineering-conventions/canonical-invalid-input-422.md +++ b/.mstar/knowledge/engineering-conventions/canonical-invalid-input-422.md @@ -105,4 +105,4 @@ Clients branch on the stable code, but tests, SDKs, and ops dashboards frequentl - Creator/legacy sessions reject HTTP 422 `invalid_input` before Host execution. ``` -Durable authority: [Actor Product Model §11.1/§11.5/§11.6](../../specs/actor-product-model.md); mapping: `crates/nexus-daemon-runtime/src/api/errors.rs`. Related: [conventions/cli-surface-honesty-discipline](../conventions/cli-surface-honesty-discipline.md) (render the actual `error_code()`, never OR-match status strings), [api-design/field-level-error-envelope-for-generated-dtos.md](../api-design/field-level-error-envelope-for-generated-dtos.md) (closed `details` vocabulary, member-aware validation). +Durable authority: [Actor Product Model §11.1/§11.5/§11.6](../../specs/architecture/actor-product-model.md); mapping: `crates/nexus-daemon-runtime/src/api/errors.rs`. Related: [conventions/cli-surface-honesty-discipline](../conventions/cli-surface-honesty-discipline.md) (render the actual `error_code()`, never OR-match status strings), [api-design/field-level-error-envelope-for-generated-dtos.md](../api-design/field-level-error-envelope-for-generated-dtos.md) (closed `details` vocabulary, member-aware validation). diff --git a/.mstar/knowledge/engineering/compute-module-sdk-authoring-pattern.md b/.mstar/knowledge/engineering/compute-module-sdk-authoring-pattern.md index 9cc61501b..dcc2c253c 100644 --- a/.mstar/knowledge/engineering/compute-module-sdk-authoring-pattern.md +++ b/.mstar/knowledge/engineering/compute-module-sdk-authoring-pattern.md @@ -11,7 +11,7 @@ tags: [wasm-sdk, compute-module, abi, drift-guard, manifest, nexus-entry, golden # Compute Module SDK Authoring Pattern -How the official WASM module SDK (`nexus-module-sdk` + `nexus-module-manifest` + `nexus-module-test`, V1.170 P0) is designed so third-party module authors write zero ABI code and the SDK drifts neither from the wire nor from the host. The normative ABI contract lives in `.mstar/specs/compute-module-abi.md` — this doc captures the **authoring pattern**, not the wire spec. +How the official WASM module SDK (`nexus-module-sdk` + `nexus-module-manifest` + `nexus-module-test`, V1.170 P0) is designed so third-party module authors write zero ABI code and the SDK drifts neither from the wire nor from the host. The normative ABI contract lives in `.mstar/specs/compute/compute-module-abi.md` — this doc captures the **authoring pattern**, not the wire spec. ## Context @@ -142,7 +142,7 @@ pub struct WorldRef { ## References -- Normative ABI: `.mstar/specs/compute-module-abi.md` (ABI §6.3 sentinels, §7 manifest contract, §9.1 versioning) +- Normative ABI: `.mstar/specs/compute/compute-module-abi.md` (ABI §6.3 sentinels, §7 manifest contract, §9.1 versioning) - Manifest-hash gotcha: [../best-practices/embedded-pinned-wasm-sha256-alignment.md](../best-practices/embedded-pinned-wasm-sha256-alignment.md) - Consumption side (daemon route + Runs): [../architecture-patterns/compute-pillar-invoke-and-runs-history.md](../architecture-patterns/compute-pillar-invoke-and-runs-history.md) - Crate topology: [standalone-crate-monorepo-topology.md](standalone-crate-monorepo-topology.md) diff --git a/.mstar/knowledge/engineering/spoke-lockstep-upgrade-procedure.md b/.mstar/knowledge/engineering/spoke-lockstep-upgrade-procedure.md index bf3be398a..b6bdfb943 100644 --- a/.mstar/knowledge/engineering/spoke-lockstep-upgrade-procedure.md +++ b/.mstar/knowledge/engineering/spoke-lockstep-upgrade-procedure.md @@ -43,7 +43,7 @@ spoke releases bundle Rust crates + npm packages + schemas + a drift gate that C - re-run the whole graph-pin probe matrix afterwards: the default/domain graph must stay libp2p-free, the feature-on graph must resolve exactly one libp2p version, and no probe asserts a version *value* ([graph-pin-honesty-discipline.md](../conventions/graph-pin-honesty-discipline.md)). Because `libp2p` is a transitive requirement of `spoke-connect` rather than a freely chosen dependency, treat a mismatch as an upstream compatibility fact, not a local preference. 8. **Feature-graph evidence set**: default graph libp2p-free (`cargo tree -p nexus42 -i libp2p` → absent), single libp2p version feature-on, single `regress` version both graphs. -9. **Record the trail** in the `Cargo.toml` pin comment block (per-iteration section, upstream change summary, and the reason for every lockstep companion pin — including the shared-type argument for `libp2p`) and align `.mstar/specs/spoke-adapter-architecture.md` §1.1/§5.2 pins in the same commit. +9. **Record the trail** in the `Cargo.toml` pin comment block (per-iteration section, upstream change summary, and the reason for every lockstep companion pin — including the shared-type argument for `libp2p`) and align `.mstar/specs/architecture/spoke-adapter-architecture.md` §1.1/§5.2 pins in the same commit. 10. **Keep the parity proof cheap and permanent**: the adapter's own parity test (`cargo test -p nexus-spoke-adapter --test spoke_parity`) plus the two `cargo check` shapes are the round's behavioural evidence; a dependency-only round changes no product surface, so it must not grow product tests to look substantial. ## Why This Matters diff --git a/.mstar/knowledge/engineering/sqlx-migration-checksum-immutability.md b/.mstar/knowledge/engineering/sqlx-migration-checksum-immutability.md index 2faceea18..8540c28a9 100644 --- a/.mstar/knowledge/engineering/sqlx-migration-checksum-immutability.md +++ b/.mstar/knowledge/engineering/sqlx-migration-checksum-immutability.md @@ -21,7 +21,7 @@ status: active ## Why This Matters -The apparent fix is always tempting because editing comments looks behavior-free — SQL is untouched, so tests pass. The hazard is data, not code: checksums are computed over file bytes. In v1.178, the drop-migration header said "V1.159 T3" while sibling specs said "V1.59 T3"; archaeology proved V1.59 was correct, but the only safe channel was a provenance note in `.mstar/specs/local-db-schema.md` §4.2 plus tracking the header value as known-immutable (AR-106). An unexplained constraint would eventually be "cleaned up" by a well-meaning editor. +The apparent fix is always tempting because editing comments looks behavior-free — SQL is untouched, so tests pass. The hazard is data, not code: checksums are computed over file bytes. In v1.178, the drop-migration header said "V1.159 T3" while sibling specs said "V1.59 T3"; archaeology proved V1.59 was correct, but the only safe channel was a provenance note in `.mstar/specs/runtime/local-db-schema.md` §4.2 plus tracking the header value as known-immutable (AR-106). An unexplained constraint would eventually be "cleaned up" by a well-meaning editor. ## When to Apply diff --git a/.mstar/knowledge/engineering/standalone-crate-monorepo-topology.md b/.mstar/knowledge/engineering/standalone-crate-monorepo-topology.md index 595a3122a..9f6306053 100644 --- a/.mstar/knowledge/engineering/standalone-crate-monorepo-topology.md +++ b/.mstar/knowledge/engineering/standalone-crate-monorepo-topology.md @@ -104,6 +104,6 @@ exclude = ["modules/nexus-module-manifest"] ## References -- Normative ABI: `.mstar/specs/compute-module-abi.md` +- Normative ABI: `.mstar/specs/compute/compute-module-abi.md` - Iteration spec: `.mstar/iterations/v1.170/specs/v1.170-computable-dx-locks.md` AR-1 - Workspace dependency hygiene (members only): [../crate-selection-best-practices.md](../crate-selection-best-practices.md) diff --git a/.mstar/knowledge/workflow-patterns/evidence-before-retirement.md b/.mstar/knowledge/workflow-patterns/evidence-before-retirement.md index 43dd8ba9f..fe8e744b2 100644 --- a/.mstar/knowledge/workflow-patterns/evidence-before-retirement.md +++ b/.mstar/knowledge/workflow-patterns/evidence-before-retirement.md @@ -135,6 +135,6 @@ Never close a PR merely because a feature worktree deleted files — verified ma ## Evidence - Product-side retirement — deleted `apps/desktop/**` (21 tracked paths), `scripts/fetch-sidecar.sh`, `scripts/dev-backend-manifest.mjs` sidecar helpers; `.github/workflows/desktop-release.yml` removed and the Tauri `desktop-build` job stripped in `.github/workflows/desktop-build.yml` / `ci.yml`; lockfile 17 → 16 workspace projects with `sharp` preserved. -- Retained/adjudicated families — `apps/nexus42` default features, daemon boot path, embedded SPA serving, and the dormant CLI rows listed in `.mstar/specs/rust-core-service-boundary.md` §7.4. -- Policy texts — `.github/dependabot.yml` (all remaining directories verified at HEAD), `.oxlintrc.json` (dead override removed), `.mstar/specs/desktop-shell.md` header, `.mstar/specs/README.md` rows. +- Retained/adjudicated families — `apps/nexus42` default features, daemon boot path, embedded SPA serving, and the dormant CLI rows listed in `.mstar/specs/architecture/rust-core-service-boundary.md` §7.4. +- Policy texts — `.github/dependabot.yml` (all remaining directories verified at HEAD), `.oxlintrc.json` (dead override removed), `.mstar/specs/surfaces/desktop-shell.md` header, `.mstar/specs/README.md` rows. - Companion docs — [resolved-residual-verification.md](../architecture-patterns/resolved-residual-verification.md) (verify residual claims against current `main`), [surface-rename-hygiene-checklist.md](../conventions/surface-rename-hygiene-checklist.md) (sweep shape for cross-language renames), [capability-parity-receipt.md](capability-parity-receipt.md) (the acceptance-evidence counterpart for this cutover). diff --git a/.mstar/specs/AGENTS.md b/.mstar/specs/AGENTS.md index d91e7b376..b8681260e 100644 --- a/.mstar/specs/AGENTS.md +++ b/.mstar/specs/AGENTS.md @@ -8,10 +8,14 @@ Parent rules: [`../knowledge/AGENTS.md`](../knowledge/AGENTS.md). Repo root: [`. ## Layout invariant -- **Default: flat** — one spec file per kebab-case basename at `specs/` root; no version suffix in filenames. -- **`novel-writing/` subtree** — all `work_profile: novel` Feature line specs and Draft overlays (index: [novel-writing/README.md](novel-writing/README.md)). -- **No other subdirectories** unless an ADR authorizes bulk link migration. -- **Exploration and draft overlays** live here with explicit header status — not under `knowledge/` root. +- **Domain subdirectories** — each spec lives in the domain dir that owns it: `architecture/`, `runtime/`, `compute/`, `cli/`, `orchestration/`, `agents/`, `creator/`, `surfaces/`, `contracts/`. One spec file per kebab-case basename; no version suffix in filenames. +- **`novel-writing/` subtree** — all `work_profile: novel` Feature line specs and Draft overlays (index: [novel-writing/README.md](novel-writing/README.md)); unchanged by the 2026-09-29 reorganization. +- **`archived/`** — retired, deprecated, and historical records only (retired host records, historical rationale supplements, legacy acceptance records, redirect stubs). Archived records are cited for history; they are never implement authority and do not grow new normative sections. +- **Root** keeps only [README.md](README.md) (index) and this file (rules). +- **New specs** land in the matching domain dir; a spec that fits no dir goes to the closest one and the README index flags it. Retired or deprecated records move to `archived/`. +- **Moves require the full link-migration sweep**: every spec-to-spec relative link, `knowledge/**` spec-links, root `AGENTS.md`/`DESIGN.md`/`CONCEPTS.md`/`STRATEGY.md`, `docs/**`, and per-directory `AGENTS.md` files are retargeted in the same change; the README two-way index/disk diff and a 100% relative-link check must pass before commit. +- **Exploration and draft overlays** live in their domain dir with explicit header status — not under `knowledge/` root. +- *Authorization:* the maintainer authorized replacing the former flat-layout invariant with this domain-subdirectory taxonomy on **2026-09-29** (executed as one bulk `git mv` + scripted link rewrite). --- diff --git a/.mstar/specs/README.md b/.mstar/specs/README.md index a524c004b..7b1190c9b 100644 --- a/.mstar/specs/README.md +++ b/.mstar/specs/README.md @@ -22,7 +22,7 @@ Product lines → shipped journeys (Work, FL-E, agent tools, …) Exploration → future engine/product lines without implement authority ``` -**Why flat files:** each layer exposes a few long-lived **Master** documents agents can cite by stable basename. Iteration velocity is handled by **Draft overlays**, not by renaming or sharding directories. +**Why domain directories:** specs are grouped by the domain that owns them, so each domain dir holds a few long-lived **Master** documents agents can cite by stable basename; retired and historical records live under [archived/](archived/) away from live authority. Iteration velocity is handled by **Draft overlays**, not by renaming or sharding files. **Why not one mega-spec:** CLI command detail, orchestration grammar, and ACP hosting evolve on different cadences; Feature line specs record shipped product contracts without bloating Masters. @@ -49,109 +49,140 @@ See [AGENTS.md](AGENTS.md) for create/extend/merge rules. ## Layout -Spec files live **flat** in this directory except **`novel-writing/`** — the novel `work_profile` subtree (relocated 2026-06-17). See [novel-writing/README.md](novel-writing/README.md) for the domain index. +Specs are organized into **domain subdirectories** (reorganized 2026-09-29 from the former flat layout — maintainer-authorized bulk `git mv` with a full link migration). The `specs/` root keeps only this README and [AGENTS.md](AGENTS.md). + +| Directory | Scope | +| --- | --- | +| [architecture/](architecture/) | Entity scope, runtime/crate boundaries, spoke adapters, actor/holder governance, schemas layout | +| [runtime/](runtime/) | DB schema, concurrency, outbox, reference knowledge + store, embeddings, chapter-content and Daemon API conventions | +| [compute/](compute/) | Compute module ABI, WASM host | +| [cli/](cli/) | CLI product surface (`cli-spec`) | +| [orchestration/](orchestration/) | Orchestration engine, schedules/core context, preset routing, LLM extract | +| [agents/](agents/) | ACP client + capabilities, agent host, tool bridge, capability registry, registry integration | +| [creator/](creator/) | Creator product lines: work model, workflow, profiles, challenge solver, memory/SOUL lifecycle | +| [surfaces/](surfaces/) | Web UI, canvas strategy, design studio, desktop shell | +| [contracts/](contracts/) | Cross-cutting contracts: canonical hash, world delta, findings lifecycle | +| [novel-writing/](novel-writing/) | `work_profile: novel` subtree (unchanged; index: [novel-writing/README.md](novel-writing/README.md)) | +| [archived/](archived/) | Retired/deprecated/historical records only — cited for history, never implement authority | + +| Index / rules | Purpose | +| --- | --- | +| [README.md](README.md) | Root domain index and authority matrix | +| [AGENTS.md](AGENTS.md) | Spec classes, lifecycle, and maintenance rules | --- ## Master index (by domain) -*Statuses reflect document headers as of last README maintenance; authoritative per-file header wins on conflict.* +*Statuses reflect document headers as of last README maintenance; authoritative per-file header wins on conflict. `— (not declared)` means the header declares no document class; this index does not assign one.* -### Architecture and boundaries +### Architecture | Document | Class | Status | | --- | --- | --- | -| [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md) | Master | Active — V1.64 amendment: local Web UI workspace member + embedded asset edge | -| [entity-scope-model.md](entity-scope-model.md) | Master | Normative — V1.40 Shipped §5.1.1; V1.51 Shipped §5.5.6; **V1.62 Shipped** §5.5.9 (computable-flag + structured validation). **V1.158**: §1.4 V1.123 three-layer overlay + V1.156 3×2 matrix completion amendment promoted to Normative (World×Moment + Work×Brief closed; frontend-only, `wire_contracts_changed: false`). **V1.159**: §5.1.1 era taxonomy amendment (`era_type` + §5.6 `custom`/`custom_label: "parent_era"` nesting carrier — additive, `wire_contracts_changed: false`). **V1.162**: §6.6 fork-creation write boundary + lineage projection contract amendment (PD-01 local-vs-platform reconciliation; carrier approach B locked — branch-level `is_fork`/`parent_branch_id`/`forked_from_event_id`/`label?` fro… -| [local-runtime-boundary.md](local-runtime-boundary.md) | Master | Normative | -| [rust-core-service-boundary.md](rust-core-service-boundary.md) | Master | Accepted target — locked 2026-09-13; **M1 subset exercised** (v1.189 PR #306, merge `71e01cf9`); **v1.193 overlay delivered (P2 complete 2026-09-21)** — the whole `nexus42 daemon` group, hidden `daemon-run`, `web-embed` and the `DaemonClient` CLI leaves are deleted and retained leaves call core/cloud/Connect directly, so no shipped Master still describes an implementable daemon topology; v1.192 delivered the Electron desktop cutover (Tauri retired). Unexercised destinations are the remaining RFT-05–07 families (§7.5; RFT-08–11 delivered in v1.193 P2/v1.192, with RFT-10 signing still a Non-Goal) — do not describe them as delivered. Electron GUI qualification, Gatekeeper trust and installed-deployment rows stay unverified | -| [schemas-directory-layout.md](schemas-directory-layout.md) | Master | Normative — current Daemon API contracts live under `schemas/daemon-api/`; generated authorities: Rust `generated::daemon_api` + TypeScript `generated/daemon-api` (reconciled through V1.183). V1.139 architect §5.2: `domain/key-block.schema.json` deleted (spoke `knowledge-entry.schema.json` is the KB type source) | -| [local-api-surface-conventions.md](local-api-surface-conventions.md) | Redirect stub | **V1.90 redirect stub** — renamed to [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md); retained for historical links from iteration compasses/plans | -| [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) | Master | Normative — V1.77 amendment (§11 findings PATCH as non-OCC resource PATCH); cross-resource Daemon API response/query conventions for `schemas/daemon-api/` + `nexus-daemon-runtime` handlers; **v1.198 §13 implemented on the iteration branch (PR pending):** archived is terminal; default omission precedes the 500-row cap; `include_archived` opts in. | -| [outbox-consolidation.md](outbox-consolidation.md) | Master | Normative — V1.59 P-last promote (single-writer contract + schema ownership); **V1.177 revision** (daemon `outbox` table dropped at V1.163 — §2.3/§6 closed history) | -| [reference-knowledge.md](reference-knowledge.md) | Master | Normative — V1.58 P-last promote (reference body refreshable scan pipeline) | -| [spoke-adapter-architecture.md](spoke-adapter-architecture.md) | Master | **Normative (v0.19 — V1.155 P1 capability-token production + tenant isolation: `nexus42 connect token issue` CLI (issuer.key Ed25519 create-once 0600, `claims.iss` MUST equal issuer-derived peer id), operator config `~/.nexus42/connect/config.json` (`trusted_issuers` / `require_capability_token` / `capability_token_provider{enabled, issuer_key_path}`, deny-unknown-fields, absent ⇒ pre-V1.155 defaults, malformed ⇒ fail-closed boot error, require-without-issuers ⇒ boot error); enforcement spoke-side fail-closed (`evaluate_invoke_token_gate` ⇒ `auth_failed` before the nexus handler, zero side effects) + nexus `PeerScope` intersection — token can never widen allowlist scope; all opt-in, … **v1.191 P1 holder amendment shipped** — [holder-governance.md](holder-governance.md) owns the holder/wire cutover; the pins are the pinned upstream lockstep release (version SSOT: the manifests; D17); **v1.198 Rule vocabulary implemented on the iteration branch (PR pending):** `archived` is terminal/read-only; `RuleQueryPort` retains raw reference resolution and the active-only World-scoped check. | -| [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) | Master | Active — current external daemon contracts use the Daemon API namespace; V1.64 originally established the bundled Web UI as an external API consumer (moved from knowledge root 2026-08-17) | -| [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md) | Master | Normative — World KB implementation SSOT (crate responsibilities, loops, taxonomy; V1.139 SPOKE alignment); moved from knowledge root 2026-08-17 | -| [embedding-readiness.md](embedding-readiness.md) | Master | Normative — V1.181 P0 (RN-OGA-3 readiness-contract form): platform-provided embeddings, OSS ships no execution; `EmbeddingIdentity` tuple + fail-closed derived-index protocol + explicit lexical fallback; governs `crates/nexus-embedding/` | -| [actor-product-model.md](actor-product-model.md) | Draft overlay | **Draft (2026-09-04 product lock; honesty amended 2026-09-06)** — **v1.184 shipped** Character bearer, bindings, three KE owner scopes, KnowledgeView, one-host execution, SOUL/Memory, ToM L1/L2 (PR #240); **v1.185 shipped** (§11 developer maintenance: identity edit, reversible archive/restore, WorldSheet binding maintenance, KE content maintenance, run-connected `--remember`; PR #241). §11 is the shipped contract, not a planning-only proposal; Schemas remain executable wire SSOT; **v1.191 holder amendment shipped on the `feat/v1.191-p1-spoke-0-13-adoption` plan branch (integration/PR delivery PM-owned)** — [holder-governance.md](holder-governance.md) | -| [holder-governance.md](holder-governance.md) | Draft overlay | **Shipped (v1.191 P1)** — implemented and exercised on the v1.191 plan branch (`feat/v1.191-p1-spoke-0-13-adoption`) and **merged to `main`** in the v1.191 iteration PR (`ee23ec47c`, #325); sole technical contract for Creator/Character holders, native disclosure, management vs ActorView admission, offline creator_only cutover, session invalidation, import identity safety, production extraction and Connect grants. The registry (`crates/nexus-local-db/src/holders.rs`, `knowledge_holders`) is shipped current state. The SPOKE pins are the pinned upstream lockstep release (version SSOT: the manifests; D17 records the adoption decision) | - -### Runtime and persistence +| [entity-scope-model.md](architecture/entity-scope-model.md) | Master | Normative — entity scope hierarchy, uniqueness, and domain ownership; V1.40 narrative taxonomy, V1.50 World KB promotion, V1.51 LLM pathway, and V1.62 computable validation. §1.4 owns the normative three-layer projection and V1.156 matrix completion; V1.159 era taxonomy and §6.6 fork lineage remain additive. Current KB validation owner: `nexus-knowledge`; service-family authority: `nexus-core`; former daemon ownership/branch-input wiring is historical. | +| [local-runtime-boundary.md](architecture/local-runtime-boundary.md) | Master | Normative for retained wire/ACP boundaries; daemon host-process sections are historical (retired in v1.193 P2) | +| [rust-core-service-boundary.md](architecture/rust-core-service-boundary.md) | Master | Accepted target — locked 2026-09-13; **M1 subset exercised** (v1.189 PR #306, merge `71e01cf9`); **v1.193 overlay delivered (P2 complete 2026-09-21)** — retained CLI leaves call core/cloud/Connect directly; browser/Electron use the standalone TS service, and the integrated daemon/embedded SPA are deleted. **RFT-05–07 route families implemented and exercised through the TS service + core (§7.5)**; product acceptance/QA and Run Studio completeness remain outstanding. v1.192 delivered Electron and unsigned packaging; GUI, Gatekeeper, installed-deployment, and first-run qualification remain separate, unverified obligations. §2 inventories `nexus-core`, `nexus-core-node`, `nexus-preset`, `nexus-provider-conformance`, `nexus-provider-ports`, and `nexus-storage-guard`. | +| [spoke-adapter-architecture.md](architecture/spoke-adapter-architecture.md) | Master | **Normative (v0.19 — V1.155 P1 capability-token production + tenant isolation: `nexus42 connect token issue` CLI (issuer.key Ed25519 create-once 0600, `claims.iss` MUST equal issuer-derived peer id), operator config `~/.nexus42/connect/config.json` (`trusted_issuers` / `require_capability_token` / `capability_token_provider{enabled, issuer_key_path}`, deny-unknown-fields, absent ⇒ pre-V1.155 defaults, malformed ⇒ fail-closed boot error, require-without-issuers ⇒ boot error); enforcement spoke-side fail-closed (`evaluate_invoke_token_gate` ⇒ `auth_failed` before the nexus handler, zero side effects) + nexus `PeerScope` intersection — token can never widen allowlist scope; all opt-in, … **v1.191 P1 holder amendment shipped** — [holder-governance.md](architecture/holder-governance.md) owns the holder/wire cutover; the pins are the pinned upstream lockstep release (version SSOT: the manifests; D17); **v1.198 Rule vocabulary implemented on the iteration branch (PR pending):** `archived` is terminal/read-only; `RuleQueryPort` retains raw reference resolution and the active-only World-scoped check. | +| [actor-product-model.md](architecture/actor-product-model.md) | Draft overlay | **Draft (2026-09-04 product lock; honesty amended 2026-09-06)** — **v1.184 shipped** Character bearer, bindings, three KE owner scopes, KnowledgeView, one-host execution, SOUL/Memory, ToM L1/L2 (PR #240); **v1.185 shipped** (§11 developer maintenance: identity edit, reversible archive/restore, WorldSheet binding maintenance, KE content maintenance, run-connected `--remember`; PR #241). §11 is the shipped contract, not a planning-only proposal; Schemas remain executable wire SSOT; **v1.191 holder amendment shipped on the `feat/v1.191-p1-spoke-0-13-adoption` plan branch (integration/PR delivery PM-owned)** — [holder-governance.md](architecture/holder-governance.md) | +| [holder-governance.md](architecture/holder-governance.md) | Draft overlay | **Shipped (v1.191 P1)** — implemented and exercised on the v1.191 plan branch (`feat/v1.191-p1-spoke-0-13-adoption`) and **merged to `main`** in the v1.191 iteration PR (`ee23ec47c`, #325); sole technical contract for Creator/Character holders, native disclosure, management vs ActorView admission, offline creator_only cutover, session invalidation, import identity safety, production extraction and Connect grants. The registry (`crates/nexus-local-db/src/holders.rs`, `knowledge_holders`) is shipped current state. The SPOKE pins are the pinned upstream lockstep release (version SSOT: the manifests; D17 records the adoption decision) | +| [schemas-directory-layout.md](architecture/schemas-directory-layout.md) | Master | Normative — current Daemon API contracts live under `schemas/daemon-api/`; generated authorities: Rust `generated::daemon_api` + TypeScript `generated/daemon-api` (reconciled through V1.183). V1.139 architect §5.2: `domain/key-block.schema.json` deleted (spoke `knowledge-entry.schema.json` is the KB type source) | +| [schemas-external-consumer-boundary.md](architecture/schemas-external-consumer-boundary.md) | Companion | Active — current external daemon contracts use the Daemon API namespace; V1.64 originally established the bundled Web UI as an external API consumer (moved from knowledge root 2026-08-17) | +| [world-kb-runtime-architecture.md](architecture/world-kb-runtime-architecture.md) | Master | Normative — World KB implementation SSOT: `nexus-core` service-family authorization/orchestration, `nexus-knowledge` KB domain/validation, `nexus-narrative` narrative aggregates, and `nexus-local-db` persistence. Former daemon HTTP adapters and transitional pack bridge are historical; current pack authority is `CoreService::import_world_pack`. | + +### Runtime | Document | Class | Status | | --- | --- | --- | -| [daemon-runtime.md](daemon-runtime.md) | Master | **Retired host record (v1.193 P2)** — the integrated daemon host is deleted: the `nexus-daemon-runtime` crate, the whole `nexus42 daemon` group, hidden `daemon-run` and the `web-embed` embedded-SPA bytes are gone, with no replacement service launcher. Current owners of the retained contracts: the standalone TS service serves `/v1/daemon/*` for browser/Electron, Electron owns the desktop and its service lifecycle, and `nexus-runtime` is the independent Connect host (§4.6). Sections are the historical record unless they name a retained wire, Connect or checkpoint contract. Historical amendments: V1.65 Prepare (bundled local Web UI serving + chapter-content route family); **V1.66** §12 Tauri sidecar mode; **V1.86** §13 Daemon API trust boundary; **V1.90** §14 remote bind gate + surface rename Local API → **Daemon API** with `/v1/daemon/` prefix; **V1.92** §15–16 TLS transport + remote client; **V1.118** §17 no-Profile boot + lazy `state.db` open; **V1.153** §4.6 headless `nexus-runtime` profile; **V1.180–V1.182** §19 checkpoint inspection + boot re-drive semantics (reconciled through V1.183); **V1.186 Shipped** §20 truthful terminals/waits + bounded run recovery (§20.1–§20.2 V1.188 readiness/replay); **v1.192** §12 Tauri desktop host retired (Electron) | -| [local-db-schema.md](local-db-schema.md) | Master | Normative — V1.40 Shipped §4.1.2 (KB validation + narrative_worlds + kb_extract_jobs artifact locator); **v1.191 P1 holder amendment shipped** (holder registry, native governance columns, knowledge revisions, schema 23 → 24) — [holder-governance.md](holder-governance.md) §§2–6 | -| [concurrency.md](concurrency.md) | Master | **Normative — V1.51 Shipped (T-B P0/P1)** — advisory lock + heartbeat + OCC + zombie detection | -| [canvas-strategy-surface.md](canvas-strategy-surface.md) | Draft overlay | **Shipped β (V1.74)** — Strategy α (V1.70) + Strategy write-boundary (V1.71) + Outline+Timeline β (V1.72) + World KB β (V1.73) + World KB relationships β (V1.74) shipped; **V1.122/V1.123 Draft overlays** (Timeline peer surface = default World entry; three-layer Brief/Narrative/Moment + Work Timeline) + **V1.156** 3×2 matrix completion + **V1.159** era taxonomy + **V1.162** fork authoring chrome, and **V1.163** event-level cross-surface binding — each additive and frontend-only (`wire_contracts_changed: false`); see the promotion blockquote chain in the doc | -| [reference-store-layout.md](reference-store-layout.md) | Master | Normative | -| [chapter-content-local-api.md](chapter-content-local-api.md) | Feature line | Shipped — V1.65 chapter surface (`/v1/daemon/works/{work_id}/chapters/*`); V1.75 retired whole-document outline PUT in favor of the canvas patch route; cited by daemon-api-surface-conventions §6.2/§7 | +| [local-db-schema.md](runtime/local-db-schema.md) | Master | Normative — V1.40 Shipped §4.1.2 (KB validation + narrative_worlds + kb_extract_jobs artifact locator); **v1.191 P1 holder amendment shipped** (holder registry, native governance columns, knowledge revisions, schema 23 → 24) — [holder-governance.md](architecture/holder-governance.md) §§2–6 | +| [concurrency.md](runtime/concurrency.md) | Master | Normative — V1.51 advisory lock/heartbeat/OCC; V1.56 workspace sessions; V1.188 recoverable target-content commit (§9) | +| [outbox-consolidation.md](runtime/outbox-consolidation.md) | Master | Normative — V1.59 P-last promote (single-writer contract + schema ownership); **V1.177 revision** (daemon `outbox` table dropped at V1.163 — §2.3/§6 closed history) | +| [reference-knowledge.md](runtime/reference-knowledge.md) | Master | Normative — V1.58 P-last promote (reference body refreshable scan pipeline); current scheduler: `nexus-core` execution schedules; capability: `nexus-orchestration` builtins, with core registration/context wiring. V1.58 daemon boot composition is historical. | +| [reference-store-layout.md](runtime/reference-store-layout.md) | Master | Active — normative V1.26 design for local reference registry + body storage | +| [embedding-readiness.md](runtime/embedding-readiness.md) | Master | Normative — V1.181 P0 (RN-OGA-3 readiness-contract form): platform-provided embeddings, OSS ships no execution; `EmbeddingIdentity` tuple + fail-closed derived-index protocol + explicit lexical fallback; governs `crates/nexus-embedding/` | +| [chapter-content-local-api.md](runtime/chapter-content-local-api.md) | Feature line | Shipped — V1.65 chapter surface (`/v1/daemon/works/{work_id}/chapters/*`); V1.75 retired whole-document outline PUT in favor of the canvas patch route. Implementation owners: `nexus-core` content/outline services + `nexus-core-node`; route family served by `apps/nexus-service`. | +| [daemon-api-surface-conventions.md](runtime/daemon-api-surface-conventions.md) | Master | Normative — V1.77 amendment (§11 findings PATCH as non-OCC resource PATCH); retained Daemon API response/query conventions for `schemas/daemon-api/`, now served by `apps/nexus-service` over core (host boundary: [rust-core-service-boundary.md](architecture/rust-core-service-boundary.md)); `nexus-daemon-runtime` handler references are historical. **v1.198 §13 implemented on the iteration branch (PR pending):** archived is terminal; default omission precedes the 500-row cap; `include_archived` opts in. | -### Compute and WASM +### Compute | Document | Class | Status | | --- | --- | --- | -| [compute-module-abi.md](compute-module-abi.md) | Master | **Normative — V1.62 Shipped (P2)** — V1 envelope ABI: exports, host imports, marshalling, manifest.json contract | -| [wasm-host.md](wasm-host.md) | Master | **Normative — V1.62 Shipped (P2)** — nexus-wasm-host crate: engine, sandbox, limits, watchdog, module loading, error taxonomy | +| [compute-module-abi.md](compute/compute-module-abi.md) | Master | **Normative — V1.62 Shipped (P2)** — V1 envelope ABI: exports, host imports, marshalling, manifest.json contract | +| [wasm-host.md](compute/wasm-host.md) | Master | **Normative — V1.62 Shipped (P2)** — nexus-wasm-host crate: engine, sandbox, limits, watchdog, module loading, error taxonomy | -### CLI product surface +### CLI | Document | Class | Status | | --- | --- | --- | -| [cli-spec.md](cli-spec.md) | Master | **Normative — V1.51 Shipped** — V1.40 §6.2G world binding + **V1.51** `kb adopt`/`rescan`/`pending --missing-only` (T-A P0/P1/P2); legacy V1.46 overlay fully merged; V1.52 §6.2G.1/§6.2G.2 overlays promoted (V1.158); **V1.175 P1** §6.2G.3–§6.2G.6 leaves **retargeted in v1.193 P2 to direct-core calls** (the thin daemon-HTTP transport is history); **V1.182 P1** §6.3B hidden `nexus42 ops inspect` (BL-04); **V1.193 P2 delivered (2026-09-21)** — the daemon group, `web-embed`, the `DaemonClient` leaves, `creator run`/`creator bootstrap`/runner entries, Model A `mcp serve`/`host-call` and the hidden top-level `sync` alias are deleted; the ordinary default is the direct-core `cli` cohort and `platform sync` is the canonical sync surface. Every daemon/runner instruction in the document is a historical record, not a setup step; **v1.198 implemented on the iteration branch (PR pending):** `creator world rule archive` and `rule list --include-archived`. | -| [cli-command-ia.md](cli-command-ia.md) | Master (Shipped V1.35) | Shipped (V1.35) | -| [creator-centric-entry-model.md](creator-centric-entry-model.md) | Master (Shipped V1.35) | Shipped (V1.35) | +| [cli-spec.md](cli/cli-spec.md) | Master | **Normative — V1.51 Shipped** — V1.40 §6.2G world binding + **V1.51** `kb adopt`/`rescan`/`pending --missing-only` (T-A P0/P1/P2); legacy V1.46 overlay fully merged; V1.52 §6.2G.1/§6.2G.2 overlays promoted (V1.158); **V1.175 P1** §6.2G.3–§6.2G.6 leaves **retargeted in v1.193 P2 to direct-core calls** (the thin daemon-HTTP transport is history); **V1.182 P1** §6.3B hidden `nexus42 ops inspect` (BL-04); **V1.193 P2 delivered (2026-09-21)** — the daemon group, `web-embed`, the `DaemonClient` leaves, `creator run`/`creator bootstrap`/runner entries, Model A `mcp serve`/`host-call` and the hidden top-level `sync` alias are deleted; the ordinary default is the direct-core `cli` cohort and `platform sync` is the canonical sync surface. Every daemon/runner instruction in the document is a historical record, not a setup step; **v1.198 implemented on the iteration branch (PR pending):** `creator world rule archive` and `rule list --include-archived`. | -**Read order:** CLI Master (§6–§7) → shipped IA supplement → shipped entry-model supplement. +**Read order:** CLI Master (§6–§7, including the delivered v1.193 P2 overlay) → historical V1.35 IA and entry-model supplements for rationale only. + +### Orchestration + +| Document | Class | Status | +| --- | --- | --- | +| [orchestration-engine.md](orchestration/orchestration-engine.md) | Master | Shipped (V1.4–V1.188) — preset loader, Host-mediated prompts, capability registry, recoverable workspace execution, and settle-once cancellation; V1.62 compute, V1.179 P2 bounded joins, and V1.186–V1.188 §15 execution completeness/reliability. Retained owners: `nexus-orchestration` + `nexus-preset`; daemon hosting and CLI runner entrances are historical after v1.193 P2. | +| [creator-schedule-and-core-context.md](orchestration/creator-schedule-and-core-context.md) | Master | Shipped (V1.4 WS7 → V1.34 agent-host + schedule wiring); canonical SSOT for ongoing schedule work | +| [preset-conditional-routing.md](orchestration/preset-conditional-routing.md) | Feature line | **Shipped (V1.42 P2)** — DF-56 `llm_judge` GO/NOGO minimal slice; V1.52/V1.56 overlays promoted (V1.158); **V1.179 P2** DR-06 bounded joins (§3.3.3, Normative) | +| [llm-extract.md](orchestration/llm-extract.md) | Master | **Normative — V1.51 Shipped (T-A P0)** — `nexus.llm.extract` capability, `LlmExtractTask`, `kb_extract_jobs` payload extension, and review-time extraction shipped; production preset-kind `llm_extract` routing remains unshipped/deferred | -### Orchestration and presets +### Agents | Document | Class | Status | | --- | --- | --- | -| [orchestration-engine.md](orchestration-engine.md) | Master | Shipped; **V1.62 Shipped** §5.2 narrative.compute + §8.4 combat-engine; **V1.179 P2 Shipped** §7.5 DR-06 bounded joins (`timeout_ms`/`on_timeout`); **V1.186 product lock (Prepare, not shipped)** §15 execution completeness | -| [creator-schedule-and-core-context.md](creator-schedule-and-core-context.md) | Master | Shipped (V1.4 WS7 → V1.34 agent-host + schedule wiring); canonical SSOT for ongoing schedule work | -| [preset-conditional-routing.md](preset-conditional-routing.md) | Feature line | **Shipped (V1.42 P2)** — DF-56 `llm_judge` GO/NOGO minimal slice; V1.52/V1.56 overlays promoted (V1.158); **V1.179 P2** DR-06 bounded joins (§3.3.3, Normative) | -| [llm-extract.md](llm-extract.md) | Master | **Normative — V1.51 Shipped (T-A P0)** — `nexus.llm.extract` capability + `LlmExtractTask` + `kb_extract_jobs` LLM payload extension (closes R-V150KBED-01) | +| [acp-client-tech-spec.md](agents/acp-client-tech-spec.md) | Master | **Shipped** — official `agent-client-protocol = "=2.2.0"` stable-v1 behind Nexus-owned DTOs; core-owned `HostManager` + admitted provider catalog, with native-core or TS ACP provider composition. Daemon route-facing manager/per-creator worker composition is historical. | +| [acp-capability-set.md](agents/acp-capability-set.md) | Master | Normative — logical capability catalog; current local HTTP host is `apps/nexus-service` under Electron lifecycle. Core `host_tool_registry()` owns host-tool dispatch; orchestration `CapabilityRegistry` is separate. | +| [agent-host.md](agents/agent-host.md) | Master | Normative — shipped through V1.188: Host-mediated orchestration, configured ACP/native registration, dsh SDK runtime/streaming cutover, and verified provider readiness | +| [agent-nexus-tool-bridge.md](agents/agent-nexus-tool-bridge.md) | Master | Normative — retained core tool-execution contract via `nexus-core` `host_tool_registry()`; **30 static IDs (28 `nexus.*` + 2 `fs/*`)**. Daemon `HostToolExecutor`, worker HTTP topology, and the six-tool roster are historical. | +| [capability-registry.md](agents/capability-registry.md) | Master | Normative / Shipped — promoted V1.57 P-last; retained runtime dispatch authority is `nexus-core` `host_tool_registry()` with **30 static IDs (28 `nexus.*` + 2 `fs/*`)**, plus admitted peer/user capabilities. Daemon wrappers and earlier rosters are historical. | +| [registry-integration.md](agents/registry-integration.md) | Master | Normative for identified shipped behavior — `nexus-acp-host` registry/client/cache, `HostManager` provider/session admission, and `packages/nexus-provider-acp` TS callbacks/subprocesses; Electron owns service lifecycle. Daemon supervision is historical; ACP discovery is distinct from `nexus.*` dispatch. | -### Creator product lines +### Creator | Document | Class | Status | | --- | --- | --- | -| [work-experience-model.md](work-experience-model.md) | Feature line | Shipped (V1.33) | -| [creator-workflow.md](creator-workflow.md) | Feature line | Shipped (V1.34; V1.39 DF-53 auto-chain + daemon continuity; **V1.40 Shipped** — DF-63 W5 `novel-review-master sync_world_kb` extract binding; V1.79 SOUL visualization contract) | -| **[novel-writing/](novel-writing/README.md)** | Feature subtree | **`work_profile: novel`** — see [novel-writing/README.md](novel-writing/README.md) for per-file index (workflow-profile, quality-loop, author-experience, overlays, …) | -| [essay-profile.md](essay-profile.md) | Feature line | Draft (V1.52) — `work_profile: essay` first non-novel profile | -| [web-ui.md](web-ui.md) | Feature line | **Shipped (V1.65)** — local Web UI product contract (`apps/web` React/Vite SPA, daemon-served, desktop-ready); Control Room + Setup (V1.64) + Content-Authoring UI stage (V1.65 §13) + Desktop Shell stage (V1.66 §14, Shipped) + Surface Convergence & De-risk stage (V1.67 §15, Shipped) + V1.69 Design System Maturation & Canvas Draft + **V1.70 Canvas Strategy Implement (α) stage (V1.70 §16, Shipped)** + CI/desktop-build optimization (parallel ops track); stages through V1.78; **V1.94/V1.98/V1.118/V1.125/V1.122 Draft amendments** (§29–§30 IA, Design Studio, creation peer groups, Three-pillar pivot + Timeline-first Canvas IA); **V1.147** Computable Run Studio; **V1.156 PD-4** §29.4 Harness pillar-entry rename; **V1.157** React 19; **V1.170 P1** Entrance-first setup (AR-17). | -| [design-studio.md](design-studio.md) | Feature line | Normative target contract (v1.187) — read-only contributor gallery and proving ground; frozen IA; filterable index + pair view; DESIGN v0.5 token values locked; implementation and visual acceptance are separate; not implement-GO; not author-facing product UI | -| [desktop-shell.md](desktop-shell.md) | Master | **Electron is the shipped desktop host (v1.192)** — cutover accepted, unsigned app+DMG delivered for both macOS architectures, Tauri composition retired; in-place product/host contract preserves setup/no-profile boot, guarded native actions, local-state recovery, HTTP client and three-option quit and defines secure preload/utility ownership. Dual-architecture GUI qualification remains unverified. | -| [creator-run-preset-entry.md](creator-run-preset-entry.md) | Master | **Shipped (V1.45 — 2026-06-13; P-last promotion Draft → Shipped 2026-06-14)** — `creator run ` generic entry; wave 0 for V1.45 CLI IA | -| [creator-challenge-solver.md](creator-challenge-solver.md) | Master | Normative | -| [creator-memory-soul-lifecycle.md](creator-memory-soul-lifecycle.md) | Draft overlay | Draft (V1.82 amendment) — per-(creator, world) narrative lifecycle | -| [reading-chrome-profile-checklist.md](reading-chrome-profile-checklist.md) | Feature line | Shipped (V1.91) — historical acceptance checklist for profile reading chrome; behavioral bar stands, named visual values superseded by later DESIGN revisions (active authority: DESIGN pair `components.reading-chrome-*`) | -| [web-ui-design-requirements.md](web-ui-design-requirements.md) | Companion | Input brief (V1.64/V1.65) for repo-root `DESIGN.md` — product/design intent; sole SSOT since `apps/web/DESIGN*.md` retired (V1.98) | - -### ACP and agent integration +| [work-experience-model.md](creator/work-experience-model.md) | Feature line | Shipped (V1.33) — retained Work container; persistence: `nexus-local-db`; operations: `nexus-core` + CLI `creator works`. Historical `creator run` journeys are not current dispatch entrances. | +| [creator-workflow.md](creator/creator-workflow.md) | Feature line | Shipped (V1.34; V1.39 auto-chain; V1.40 extract binding; V1.79 SOUL visualization) — stage/checkpoint fields and the SOUL read contract remain; automatic full-stage/chapter progression and restart resume were retired with the incomplete runner in v1.193 P2-T1. Stored fields do not promise live dispatch. | +| **[novel-writing/](novel-writing/README.md)** | — (subtree index) | **`work_profile: novel`** — per-file index for the workflow profile, quality loop, author experience, audit, multi-work lifecycle, pools, and sync companion. Folded overlays are historical; cross-profile findings authority is [findings-lifecycle.md](contracts/findings-lifecycle.md), and the sync companion is a shipped chapter-discovery/bundle library, not cloud upload integration. | +| [essay-profile.md](creator/essay-profile.md) | Feature line | Shipped (V1.63) — `work_profile: essay` production-ready scaffold, seven-state preset, quality rubric, completion detection, and optional KB extraction | +| [game-bible-profile.md](creator/game-bible-profile.md) | Feature line | Master (V1.56 P-last) — section-status auto-transition closure; V1.55 P2 shipped design-writing preset, quality rubric, section completion, and KB extraction | +| [script-profile.md](creator/script-profile.md) | Feature line | Master (V1.60 P-last promotion from Draft V1.60 P1) — `work_profile: script` artifact layout, stage/preset chain, quality rubric, KB taxonomy, and completion semantics | +| [creator-challenge-solver.md](creator/creator-challenge-solver.md) | Master | Frozen (normative for shipped CLI registration path) — solver orchestration: `apps/nexus42/src/challenge/`; registration caller: CLI Creator commands; `nexus-creator` owns aggregate/local identity, not the solver | +| [creator-memory-soul-lifecycle.md](creator/creator-memory-soul-lifecycle.md) | Draft overlay | Draft (V1.82 amendment) — per-(creator, world) narrative lifecycle | + +### Surfaces | Document | Class | Status | | --- | --- | --- | -| [acp-client-tech-spec.md](acp-client-tech-spec.md) | Master | **Shipped** — official `agent-client-protocol = "=2.1.0"` stable-v1 behind Nexus-owned DTOs; daemon-orchestrated ACP sessions in per-creator `nexus42 acp-worker` children; route-facing HostManager registers installed native CLI providers; reconciled through V1.183, SDK pin updated by the dependency sweep | -| [acp-capability-set.md](acp-capability-set.md) | Master | Normative | -| [agent-host.md](agent-host.md) | Master | Normative — current route, provider, worker, and ACP boundaries reconciled through V1.183; **V1.186 product lock (Prepare, not shipped)** — HostFacade production prompts; lazy session-scoped generic ACP; all prompt consumers off echo | -| [agent-nexus-tool-bridge.md](agent-nexus-tool-bridge.md) | Master | Master (V1.57 P-last promote — bridge Master promotion; shipped V1.34) | -| [capability-registry.md](capability-registry.md) | Master | Master (V1.57 P-last promote — bridge Master promotion + P0/P1/P3 spec changes folded in; runtime SSOT for `nexus.*` dispatch) | -| [registry-integration.md](registry-integration.md) | Master | Normative | +| [web-ui.md](surfaces/web-ui.md) | Feature line | **Shipped (V1.65)** — standalone `apps/web` React/Vite SPA + `apps/nexus-service` TS service under Electron lifecycle ownership (v1.193 P2 cutover; Tauri retired in v1.192). Historical stages: Control Room + Setup (V1.64) + Content-Authoring UI stage (V1.65 §13) + Desktop Shell stage (V1.66 §14, Shipped) + Surface Convergence & De-risk stage (V1.67 §15, Shipped) + V1.69 Design System Maturation & Canvas Draft + **V1.70 Canvas Strategy Implement (α) stage (V1.70 §16, Shipped)** + CI/desktop-build optimization (parallel ops track); stages through V1.78; **V1.94/V1.98/V1.118/V1.125/V1.122 Draft amendments** (§29–§30 IA, Design Studio, creation peer groups, Three-pillar pivot + Timeline-first Canvas IA); **V1.147** Computable Run Studio; **V1.156 PD-4** §29.4 Harness pillar-entry rename; **V1.157** React 19; **V1.170 P1** Entrance-first setup (AR-17). | +| [web-ui-design-requirements.md](surfaces/web-ui-design-requirements.md) | Companion | Input brief (V1.64/V1.65 Prepare Phase 2b) for repo-root `DESIGN.md` — product/design intent, not token authority; the root DESIGN pair is the sole SSOT since `apps/web/DESIGN*.md` retired (V1.98) | +| [canvas-strategy-surface.md](surfaces/canvas-strategy-surface.md) | Draft overlay | **Shipped β (V1.74)** — Strategy α (V1.70) + Strategy write-boundary (V1.71) + Outline+Timeline β (V1.72) + World KB β (V1.73) + World KB relationships β (V1.74) shipped; **V1.122/V1.123 Draft overlays** (Timeline peer surface = default World entry; three-layer Brief/Narrative/Moment + Work Timeline) + **V1.156** 3×2 matrix completion + **V1.159** era taxonomy + **V1.162** fork authoring chrome, and **V1.163** event-level cross-surface binding — each additive and frontend-only (`wire_contracts_changed: false`); see the promotion blockquote chain in the doc | +| [design-studio.md](surfaces/design-studio.md) | Feature line | Normative target contract (v1.187) — read-only contributor gallery and proving ground; frozen IA; filterable index + pair view; DESIGN v0.5 token values locked; implementation and visual acceptance are separate; not implement-GO; not author-facing product UI | +| [desktop-shell.md](surfaces/desktop-shell.md) | Master | **Electron is the shipped desktop host (v1.192)** — cutover accepted, unsigned app+DMG delivered for both macOS architectures, Tauri composition retired; in-place product/host contract preserves setup/no-profile boot, guarded native actions, local-state recovery, HTTP client and three-option quit and defines secure preload/utility ownership. Dual-architecture GUI qualification remains unverified. | -### Feature contracts and companions +### Contracts | Document | Class | Status | | --- | --- | --- | -| [canonical-hash.md](canonical-hash.md) | Companion | Normative (OSS notes; platform ADR-006 authoritative) | -| [world-delta-propose-apply.md](world-delta-propose-apply.md) | Feature line | Normative — V1.60 P-last promotion (world-delta propose/apply local parity) | -| [findings-lifecycle.md](findings-lifecycle.md) | Master | Normative — V1.77 Phase 2b promotion (cross-profile 6-state findings lifecycle + `target_executor` routing + UI remediation surface); produce side owned by quality-loop §2 | +| [canonical-hash.md](contracts/canonical-hash.md) | Companion | Normative (OSS notes; platform ADR-006 authoritative) | +| [world-delta-propose-apply.md](contracts/world-delta-propose-apply.md) | Feature line (promoted from Draft overlay V1.60 P0) | Master (V1.60 P-last promotion) — world-delta propose/apply local parity | +| [findings-lifecycle.md](contracts/findings-lifecycle.md) | Master | Normative — V1.77 Phase 2b promotion (cross-profile 6-state findings lifecycle + `target_executor` routing + UI remediation surface); produce side owned by quality-loop §2 | *Novel-writing sync module contract: [novel-writing/sync-contract.md](novel-writing/sync-contract.md).* +### Archived records (specs/archived/) + +| Document | Class | Status | +| --- | --- | --- | +| [daemon-runtime.md](archived/daemon-runtime.md) | Master | **Retired host record (v1.193 P2)** — the integrated daemon host is deleted: the `nexus-daemon-runtime` crate, the whole `nexus42 daemon` group, hidden `daemon-run` and the `web-embed` embedded-SPA bytes are gone, with no replacement service launcher. Current owners of the retained contracts: the standalone TS service serves `/v1/daemon/*` for browser/Electron, Electron owns the desktop and its service lifecycle, and `nexus-runtime` is the independent Connect host (§4.6). Sections are the historical record unless they name a retained wire, Connect or checkpoint contract. Historical amendments: V1.65 Prepare (bundled local Web UI serving + chapter-content route family); **V1.66** §12 Tauri sidecar mode; **V1.86** §13 Daemon API trust boundary; **V1.90** §14 remote bind gate + surface rename Local API → **Daemon API** with `/v1/daemon/` prefix; **V1.92** §15–16 TLS transport + remote client; **V1.118** §17 no-Profile boot + lazy `state.db` open; **V1.153** §4.6 headless `nexus-runtime` profile; **V1.180–V1.182** §19 checkpoint inspection + boot re-drive semantics (reconciled through V1.183); **V1.186 Shipped** §20 truthful terminals/waits + bounded run recovery (§20.1–§20.2 V1.188 readiness/replay); **v1.192** §12 Tauri desktop host retired (Electron) | +| [local-cloud-crate-architecture.md](archived/local-cloud-crate-architecture.md) | Master | **Historical crate-graph record (v1.193 P2)** — the integrated daemon host and `nexus-daemon-runtime` crate were deleted; current topology and the six newer crate boundaries are owned by [rust-core-service-boundary.md](architecture/rust-core-service-boundary.md) | +| [creator-run-preset-entry.md](archived/creator-run-preset-entry.md) | Master (historical V1.45 CLI IA; no current dispatch authority) | **Retired runner record (v1.193 P2-T1)** — originally Shipped V1.45; no replacement CLI preset-dispatch entrance. Current atomic Work operations are not a generic runner. | +| [cli-command-ia.md](archived/cli-command-ia.md) | Master (historical V1.35 lock; retained rationale supplement) | Shipped (V1.35) — historical IA rationale; current command authority is `cli-spec` §6.0B + its delivered v1.193 P2 overlay | +| [creator-centric-entry-model.md](archived/creator-centric-entry-model.md) | Master (historical V1.35 lock; retained entry-model supplement) | Shipped (V1.35) — historical onboarding/entry rationale; current entry authority is `cli-spec` §6.0B + its delivered v1.193 P2 overlay | +| [reading-chrome-profile-checklist.md](archived/reading-chrome-profile-checklist.md) | Legacy scope | Historical shipped acceptance record (V1.91) — behavioral bar stands; named visual values are superseded by the active DESIGN pair `components.reading-chrome-*` tokens | +| [local-api-surface-conventions.md](archived/local-api-surface-conventions.md) | Redirect stub | **V1.90 redirect stub** — renamed to [daemon-api-surface-conventions.md](runtime/daemon-api-surface-conventions.md); retained for historical links from iteration compasses/plans | + --- ## Normative hierarchy (conflict resolution) @@ -159,7 +190,7 @@ Spec files live **flat** in this directory except **`novel-writing/`** — the n When specs disagree, higher row wins: 1. Repo root **AGENTS.md** -2. Architecture Masters (crate graph, entity scope) +2. Current architecture authorities ([rust-core-service-boundary.md](architecture/rust-core-service-boundary.md), [entity-scope-model.md](architecture/entity-scope-model.md)); historical crate/host records do not override retained owners 3. **Draft overlay** over a conflicting legacy Master section until merge 4. Domain **Master** 5. Shipped supplement / retained overlay for rationale and acceptance details after Master merge @@ -172,23 +203,23 @@ When specs disagree, higher row wins: | Topic | Primary SSOT | Secondary | | --- | --- | --- | -| Top-level CLI groups | cli-spec §6.0B | cli-command-ia (Shipped V1.35 supplement) | -| First-run / local vs platform | cli-spec §7 | creator-centric-entry-model (Shipped V1.35 supplement) | -| Work / `creator run` | [creator-run-preset-entry.md](creator-run-preset-entry.md) (V1.45 Shipped) | work-experience-model, cli-spec §6.2 | +| Top-level CLI groups | cli-spec §6.0B + delivered v1.193 P2 overlay | cli-command-ia (historical V1.35 rationale only) | +| First-run / local vs platform | cli-spec §6.0B + delivered v1.193 P2 overlay, §7 | creator-centric-entry-model (historical V1.35 entry rationale only) | +| Work / retained atomic CLI operations | [work-experience-model.md](creator/work-experience-model.md), cli-spec §6.2H | creator-workflow §0; [creator-run-preset-entry.md](archived/creator-run-preset-entry.md) is the retired runner record, not dispatch authority | | Novel profile / `Works//` layout | [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) | work-experience-model, [novel-writing/sync-contract.md](novel-writing/sync-contract.md), cli-spec §12.1 | -| Creator workflow stages / chain | creator-workflow | work-experience-model, novel-writing/workflow-profile (produce) | +| Creator workflow stage/checkpoint fields | creator-workflow §0 | work-experience-model; automatic full-stage progression/restart continuation is retired, while orchestration-engine §15 owns retained run execution semantics | | Preset YAML / loader / validator | orchestration-engine | creator-schedule § YAML additions | | Schedule / core_context | creator-schedule-and-core-context | orchestration-engine sessions | | On-demand chapter audit (DF-69) | [novel-writing/manuscript-audit.md](novel-writing/manuscript-audit.md) | novel-writing/quality-loop §3, cli-spec §6.2 | -| Agent `nexus.*` tools | agent-nexus-tool-bridge | acp-capability-set, agent-host | -| ACP worker process | acp-client-tech-spec | daemon-runtime, local-runtime-boundary | -| KB naming (KCA-003) | entity-scope-model §5.4 + cli-command-ia §3.2 | cli-spec §6.2E–F | -| LLM extraction capability | [llm-extract.md](llm-extract.md) | entity-scope-model §5.5.6, world-kb-runtime-architecture §5.5, cli-spec §6.2G | -| Actor/Creator/Character identity, ActorWorldBinding, WorldSheet distinction, KnowledgeEntry owner scopes, Viewpoint | [actor-product-model.md](actor-product-model.md) | entity-scope-model (shipped KE taxonomy + scope hierarchy), world-kb-runtime-architecture, agent-host, acp-client-tech-spec | -| Compute module ABI (V1 envelope) | [compute-module-abi.md](compute-module-abi.md) | wasm-host, schemas-directory-layout §3.5, orchestration-engine §8.4, entity-scope-model §5.5.9, `schemas/daemon-api/compute/` | -| WASM compute host runtime | [wasm-host.md](wasm-host.md) | compute-module-abi, orchestration-engine §8.4, `crates/nexus-wasm-host/AGENTS.md` | -| Orchestration checkpoint resume / `ops inspect` | [daemon-runtime.md](daemon-runtime.md) §19 | cli-spec §6.3B (`nexus42 ops inspect`), preset-conditional-routing §3.3.3 | -| Rust core vs TS service vs CLI/runtime/desktop hosts | [rust-core-service-boundary.md](rust-core-service-boundary.md) (Accepted target; M1 subset exercised; **v1.193 overlay delivered**) | local-runtime-boundary, cli-spec, desktop-shell, agent-host, concurrency — shipped current policy for every retained family (the v1.193 P2 activation gate fired); `daemon-runtime` is the historical host record only, not an implementable authority | +| Agent `nexus.*` tools | [capability-registry.md](agents/capability-registry.md), agent-nexus-tool-bridge §0 | acp-capability-set (logical catalog), agent-host; dispatch owner is core `host_tool_registry()`, not ACP discovery | +| ACP provider/session lifecycle | acp-client-tech-spec shipped boundary, registry-integration | agent-host, rust-core-service-boundary, local-runtime-boundary (retained ACP boundaries only); daemon worker supervision is historical | +| KB naming (KCA-003) | entity-scope-model §5.4 + cli-spec §6.2E–F | cli-command-ia §3.2 (historical V1.35 rationale) | +| LLM extraction capability | [llm-extract.md](orchestration/llm-extract.md) | entity-scope-model §5.5.6, world-kb-runtime-architecture §5.5, cli-spec §6.2G | +| Actor/Creator/Character identity, ActorWorldBinding, WorldSheet distinction, KnowledgeEntry owner scopes, Viewpoint | [actor-product-model.md](architecture/actor-product-model.md) | entity-scope-model (shipped KE taxonomy + scope hierarchy), world-kb-runtime-architecture, agent-host, acp-client-tech-spec | +| Compute module ABI (V1 envelope) | [compute-module-abi.md](compute/compute-module-abi.md) | wasm-host, schemas-directory-layout §3.5, orchestration-engine §8.4, entity-scope-model §5.5.9, `schemas/daemon-api/compute/` | +| WASM compute host runtime | [wasm-host.md](compute/wasm-host.md) | compute-module-abi, orchestration-engine §8.4, `crates/nexus-wasm-host/AGENTS.md` | +| Orchestration checkpoint inspection / bounded recovery | cli-spec §6.3B (`nexus42 ops inspect`), [orchestration-engine.md](orchestration/orchestration-engine.md) §15 | preset-conditional-routing §3.3.3, concurrency §9; inspection is read-only, not a CLI resume entrance, and former daemon-boot re-drive is retired | +| Rust core vs TS service vs CLI/runtime/desktop hosts | [rust-core-service-boundary.md](architecture/rust-core-service-boundary.md) (Accepted target; M1 exercised; **v1.193 overlay delivered; RFT-05–07 route families implemented/exercised**) | local-runtime-boundary (retained wire/ACP scope), cli-spec, desktop-shell, web-ui, agent-host, concurrency — current retained owners; daemon-runtime and local-cloud-crate-architecture are historical host/topology records, not implementable owners. Route exercise does not close outstanding product/GUI/distribution/first-run qualification. | --- @@ -198,7 +229,7 @@ When specs disagree, higher row wins: | --- | --- | --- | | **Post-V1.35 CLI changes** | Update cli-spec §6–§7 first; update shipped supplements only when rationale, acceptance, or migration history changes | V1.36-V1.40 amendments folded into Master (no follow-up merge needed yet) | | **V1.53 ACP capability registry hygiene** | Promote or retain `capability-registry.md` after P0/P1 registry semantics land; skills-export compatibility spec retired and DF-50 Cancelled | **Done 2026-06-22** — promoted to Master at V1.57 P-last (see header + this index) | -| **Novel-writing sync module removed from code** | Archive novel-writing-sync-contract | Module still shipped (V1.36+); sync contract retained | +| **Novel-writing sync module removed from code** | Retire the sync companion only when its library contract is removed | Retained `nexus-orchestration::sync_module` discovery/bundle library (V1.36 Works layout); not an integrated cloud upload path | | **V1.40 shipped (DF-63 closed)** | Mark `entity-scope-model.md` §5.1.1 + `cli-spec.md` §6.2G + `creator-workflow.md` persist + `local-db-schema.md` §4.1.2 + `novel-writing/workflow-profile.md` §3.5.1 as Shipped V1.40 in their headers | **Done 2026-06-11** (see headers + this index) | **Retained splits (do not merge):** creator-schedule-and-core-context (schedule domain); ACP cluster (independent evolution cadence). @@ -224,13 +255,13 @@ Cite **`nexus-platform`** `v1-spec/` for cloud product, shared ADRs, and archite | --- | --- | | `daemon-api-workspace-write-architecture.md` | Stale — historical | | `local-fs-layout-creator-workspace.md` | Retired | -| `nexus42-single-binary-daemon-runtime-architecture.md` | [daemon-runtime.md](daemon-runtime.md) | -| `agent-host-architecture.md` | [agent-host.md](agent-host.md) §8 | -| `fl-d-conditional-routing-exploration-v1.35-prepare.md` | [preset-conditional-routing.md](preset-conditional-routing.md) | +| `nexus42-single-binary-daemon-runtime-architecture.md` | [daemon-runtime.md](archived/daemon-runtime.md) | +| `agent-host-architecture.md` | [agent-host.md](agents/agent-host.md) §8 | +| `fl-d-conditional-routing-exploration-v1.35-prepare.md` | [preset-conditional-routing.md](orchestration/preset-conditional-routing.md) | | `novel-findings-maturity.md` | [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §9 | -| `body-editor.md` | [canvas-strategy-surface.md](canvas-strategy-surface.md) (2026-06-26 — body-editor direction rejected) | -| `non-novel-profiles-roadmap.md` | [game-bible-profile.md](game-bible-profile.md) + [script-profile.md](script-profile.md) + [essay-profile.md](essay-profile.md) (all targets shipped) | -| `novel-writing/findings-lifecycle.md` (V1.49 overlay) | [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §2 — retired; current cross-profile Master: [findings-lifecycle.md](findings-lifecycle.md) | +| `body-editor.md` | [canvas-strategy-surface.md](surfaces/canvas-strategy-surface.md) (2026-06-26 — body-editor direction rejected) | +| `non-novel-profiles-roadmap.md` | [game-bible-profile.md](creator/game-bible-profile.md) + [script-profile.md](creator/script-profile.md) + [essay-profile.md](creator/essay-profile.md) (all targets shipped) | +| `novel-writing/findings-lifecycle.md` (V1.49 overlay) | [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §2 — retired; current cross-profile Master: [findings-lifecycle.md](contracts/findings-lifecycle.md) | | `narrative-indexes.md` | [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) §4.6 | **Former filename:** `local-platform-isolation-and-crate-architecture.md` → `local-cloud-crate-architecture.md` (2026-05-20). diff --git a/.mstar/specs/acp-capability-set.md b/.mstar/specs/agents/acp-capability-set.md similarity index 75% rename from .mstar/specs/acp-capability-set.md rename to .mstar/specs/agents/acp-capability-set.md index 7e1c61f19..0c168619a 100644 --- a/.mstar/specs/acp-capability-set.md +++ b/.mstar/specs/agents/acp-capability-set.md @@ -13,15 +13,15 @@ The same logical `nexus.*` IDs may appear in **platform REST** contracts for **n - **Nexus runtime** participates on the ACP wire only as ACP Client. - **User-side agent** is the ACP Agent. -- **daemon runtime / daemon** is a local helper / supervisor. It is not an ACP Agent, not an ACP Server, and must not be advertised via ACP Registry as an agent. +- **Local hosting** is not an ACP Agent/Server: Electron owns the local TS service lifecycle; `nexus-agent-host` owns provider/session policy; the Rust ACP adapter or `packages/nexus-provider-acp` owns the selected agent connection. These hosts must not be advertised via ACP Registry as agents. -Related docs: nexus-platform `v1-spec/architecture.md`, [`cli-spec.md`](./cli-spec.md). +Related docs: nexus-platform `v1-spec/architecture.md`, [`cli-spec.md`](../cli/cli-spec.md). -**Naming note**: CLI executable **`nexus42`**; local supervisor is the **daemon runtime** (single-binary mode via `nexus42 daemon start`, crate `nexus-daemon-runtime`). Product name **Nexus** (42ch / Creative Hub). **`nexus.*`** is the stable logical capability ID prefix; capability IDs need not match executable names. +**Naming note (current):** CLI executable **`nexus42`**; local HTTP service **`apps/nexus-service`** under **`apps/desktop-electron`** lifecycle ownership; headless Connect host **`nexus-runtime`**. The former **daemon runtime** / `nexus-daemon-runtime` / `nexus42 daemon start` naming is historical: that integrated host was deleted in v1.193 P2. Product name **Nexus** (42ch / Creative Hub). **`nexus.*`** remains the stable logical capability ID prefix; IDs need not match executable names. Composition anchors: [`apps/nexus-service/src/index.ts`](../../../apps/nexus-service/src/index.ts), [`crates/nexus-core-node/src/lifecycle.rs`](../../../crates/nexus-core-node/src/lifecycle.rs); details in [acp-client-tech-spec.md](acp-client-tech-spec.md). ## 0.5 Runtime registry and bridge pointers (V1.53; V1.57) -This spec is the logical catalog for `nexus.*` capabilities. Each entry lists the capability id and a one-line description. **It is not the runtime source of truth for dispatch.** The runtime SSOT is [`capability-registry.md`](capability-registry.md) (Master, V1.54 P-last). The mediated external-agent tool invocation path is now Master-spec [`agent-nexus-tool-bridge.md`](agent-nexus-tool-bridge.md) (promoted from Feature line in V1.57 P-last). +This spec is the logical catalog for `nexus.*` capabilities. Each entry lists the capability id and a one-line description. **It is not the runtime source of truth for dispatch.** The shipped registry contract is [`capability-registry.md`](capability-registry.md) (Master); code ownership is identified in §4 below. [`agent-nexus-tool-bridge.md`](agent-nexus-tool-bridge.md) (Master) defines the retained core admission/execution boundary and labels the former mediated external-agent/daemon transport as historical. --- @@ -43,6 +43,10 @@ This spec is the logical catalog for `nexus.*` capabilities. Each entry lists th ## 2. Topology +Current ACP clients are the CLI/Rust adapter and the service's admitted provider composition; registry discovery selects agent launch metadata, not a `nexus.*` tool handler. See [registry-integration.md](registry-integration.md) for the current owners. + +**Historical topology (integrated-daemon era; retired v1.193 P2):** + ```text [User] -> [nexus42 / daemon runtime] --ACP Client--> [Local/Remote ACP Agent] | @@ -93,13 +97,13 @@ The three profile-set IDs (`nexus.profile.minimal`, `nexus.profile.writer`, `nex ## 4. Capability roster (V1.60) -> **Roster governance:** This table is the single SSOT for every `nexus.*` capability ID. -> Each row maps to a runtime binding via the `host_tool_registry()` (daemon host tools) -> or the `CapabilityRegistry` (orchestration engine capabilities). Cross-references: -> [`agent-nexus-tool-bridge.md`](agent-nexus-tool-bridge.md) (Master — mediated external-agent tool path), -> [`capability-registry.md`](capability-registry.md) (Master — runtime dispatch contract). +> **Roster governance:** This table is the logical catalog and V1.60 delivery record, not the current executable allowlist. +> Host-tool binding and dispatch are owned by `nexus_core::execution::capabilities::host_tool_registry()` in [`crates/nexus-core/src/execution/capabilities.rs`](../../../crates/nexus-core/src/execution/capabilities.rs): `execute_tool` dispatches through it, and `admission_pipeline` uses the same `spine_resolves` authority. +> The [`nexus-orchestration` `CapabilityRegistry`](../../../crates/nexus-orchestration/src/capability/mod.rs) is a **separate** registry of orchestration `Capability` implementations, not the owner of the core's static host-tool table. Its admitted user capabilities can participate in the core dispatch spine after builtin and peer lookup. +> The retained core registry has **30 static host tools: 28 `nexus.*` + 2 `fs/*`**; [`retained_peer_contracts.rs`](../../../crates/nexus-core/tests/retained_peer_contracts.rs) pins that roster and excludes `nexus.profile.*` grouping metadata. The historical `nexus.reference.refresh` row below records its V1.58 P1 orchestration binding; a core host-tool binding also shipped in V1.58 P3 and is in today's registry. The retained ID `nexus.observability.daemon.health` does not restore the deleted daemon host. +> Cross-references: [`agent-nexus-tool-bridge.md`](agent-nexus-tool-bridge.md) (retained admission/execution boundary and historical agent transport), [`capability-registry.md`](capability-registry.md) (Master — current runtime dispatch contract). > -> **Status tags**: `shipped` (runtime handler bound), `scaffold-equivalent` (§3.3 metadata, not an action ID), `OUT` (explicitly non-implemented), `catalog-only` (logical contract; runtime binding deferred or in orchestration engine), `deferred-to-V2.0+` (platform-gated). +> **Status tags (V1.60 delivery snapshot)**: `shipped` (runtime handler bound at that stage), `scaffold-equivalent` (§3.3 metadata, not an action ID), `OUT` (explicitly non-implemented), `catalog-only` (logical contract; runtime binding deferred or in orchestration engine), `deferred-to-V2.0+` (platform-gated). Current binding authority is the code-backed registry above. | Capability ID | Description | Status | Shipped in | Registry row ref | | --- | --- | --- | --- | --- | @@ -223,4 +227,4 @@ If handshake succeeds but capability set is incomplete: > **Durable roadmap:** DR-25 (capability→ACP tool/resource schema map + manuscript read/write quotas + default timeouts). -- ~~Decide whether `world.delta.apply` is agent-side or runtime-side by default.~~ **Resolved V1.60 P0** — runtime-side; see [`world-delta-propose-apply.md`](world-delta-propose-apply.md) §3 (agent proposes, runtime applies under transaction + lost-update guard). +- ~~Decide whether `world.delta.apply` is agent-side or runtime-side by default.~~ **Resolved V1.60 P0** — runtime-side; see [`world-delta-propose-apply.md`](../contracts/world-delta-propose-apply.md) §3 (agent proposes, runtime applies under transaction + lost-update guard). diff --git a/.mstar/specs/acp-client-tech-spec.md b/.mstar/specs/agents/acp-client-tech-spec.md similarity index 91% rename from .mstar/specs/acp-client-tech-spec.md rename to .mstar/specs/agents/acp-client-tech-spec.md index 3c55bff45..fc89c5d7e 100644 --- a/.mstar/specs/acp-client-tech-spec.md +++ b/.mstar/specs/agents/acp-client-tech-spec.md @@ -1,17 +1,17 @@ # ACP Client Integration — Technical Specification -**Status:** Shipped. Current implementation uses official `agent-client-protocol = "=2.1.0"` (stable-v1 API via `schema::v1::*`; no unstable v2 features, no `agent-client-protocol-rmcp`) behind Nexus-owned DTOs; daemon-orchestrated ACP sessions are delegated to per-creator `nexus42 acp-worker` children, while the route-facing daemon `HostManager` currently registers installed native CLI providers. Sections 2–10 retain the original V1.0 design and migration record where not superseded by the current amendment below. +**Status:** Shipped. The Rust adapter uses official `agent-client-protocol = "=2.2.0"` (stable-v1 API via `schema::v1::*`; no unstable v2 features, no `agent-client-protocol-rmcp`) behind Nexus-owned DTOs. Current service composition uses the core-owned `HostManager` and `packages/nexus-provider-acp` callbacks, not a route-facing daemon manager plus per-creator `acp-worker` children. Sections 2–10 retain the original V1.0 design and migration record; they are historical wherever superseded by the shipped boundary below. **Document class**: Master **Source Plan**: `2025-04-05-acp-client` **Date**: 2026-04-06 -**Last reconciled**: 2026-09-04 — current SDK pin, client trait authority, provider wiring, and ACP worker boundary through V1.183. +**Last reconciled**: 2026-09-29 — exact Rust SDK pin and post-v1.193 service/provider composition. The shipped boundary is: - `crates/nexus-acp-host/Cargo.toml` pins - `agent-client-protocol = "=2.1.0"`; stable-v1 messages are imported from + `agent-client-protocol = "=2.2.0"`; stable-v1 messages are imported from `agent_client_protocol::schema::v1` (the flat `schema` re-export was removed upstream) and the adapter pins `ProtocolVersion::V1` explicitly. - Official SDK types are confined to `nexus-acp-host`; the public @@ -20,11 +20,11 @@ The shipped boundary is: - `nexus-agent-host::providers::acp` consumes `NexusAcpClient` / `AcpSdkAdapter`, but those provider-specific types do not cross the `HostFacade` boundary. -- The daemon runtime does not import SDK protocol types or execute ACP sessions - in process. Daemon orchestration delegates those sessions to a per-creator - `nexus42 acp-worker` child; the route-facing `HostManager` boot path currently - registers installed `codex-native`, `claude-native`, and `dsh-native` - adapters. +- [`HostManager`](../../../crates/nexus-agent-host/src/core/manager.rs) owns provider/session policy. `register_provider` accepts an adapter plus its launch recipe; ordinary `start` instead materializes the admitted catalog when no adapters were pre-registered. [`core/readiness.rs`](../../../crates/nexus-agent-host/src/core/readiness.rs) builds that catalog from configured providers and PATH discovery, not a fixed native-only registration list. +- [`nexus-core-node` boot](../../../crates/nexus-core-node/src/lifecycle.rs) starts one manager, wraps a supplied JS provider port in `AdmittingProviderPort` (otherwise uses `host.build_provider_port()`), and adopts that same manager into the core host authority. [`apps/nexus-service/src/index.ts`](../../../apps/nexus-service/src/index.ts) supplies `createAcpProvider()` except in domain-only mode; [`lifecycle.ts`](../../../apps/nexus-service/src/lifecycle.ts) passes it to `openCore`. +- The Rust `AcpProvider` stores an enabled ACP launch recipe and lazily owns a separate child for each Host session. The TS callback implementation in [`packages/nexus-provider-acp`](../../../packages/nexus-provider-acp/src/acp.ts) owns its ACP sessions and subprocesses through [`process-owner.ts`](../../../packages/nexus-provider-acp/src/process-owner.ts). Neither path requires the deleted daemon host. + +**Historical composition (through V1.183; retired v1.193 P2):** daemon orchestration delegated ACP sessions to per-creator `nexus42 acp-worker` children, while its route-facing `HostManager` registered native CLI adapters. This is no longer the service boot composition or a current SDK-linkage boundary. --- @@ -47,7 +47,7 @@ The shipped boundary is: ### 1.1 Current dependency and boundary -The shipped ACP SDK is **`agent-client-protocol` 2.1.0**, exact-pinned in +The shipped Rust ACP SDK is **`agent-client-protocol` 2.2.0**, exact-pinned in `crates/nexus-acp-host/Cargo.toml`. ACP crate major 2 does not put the wire on protocol v2 — the adapter stays on stable v1 and no longer pulls `rmcp` transitively (the default dependency graph is rmcp-free; see @@ -58,8 +58,8 @@ and implementation code; consumers use nexus contract DTOs through `crates/nexus-agent-host/src/providers/acp.rs` adapts that client boundary to the normalized `ProviderAdapter` lifecycle (initialize, session creation, -prompt/stream, cancel, shutdown). The daemon runtime does not directly link -the SDK. No fixed client-method count is normative: the trait definition and +prompt/stream, cancel, shutdown). The integrated daemon is retired; current +service/provider ownership is described above. No fixed client-method count is normative: the trait definition and its adapter implementation are the source authority as protocol support evolves. @@ -67,6 +67,8 @@ evolves. ## 2. Integration Architecture +> **Historical design record (§§2–10):** the module layout, daemon dependencies, worker topology and migration tasks below describe the original V1.0 proposal, not the current boot composition. Use the shipped-boundary amendment above and [registry-integration.md](registry-integration.md) for current ACP registry behavior. + ### 2.1 High-Level Architecture ``` @@ -705,7 +707,7 @@ cat ~/.nexus42/registry/cache_meta.json - `apps/nexus42/src/acp/error.rs` **Files to modify:** -- `apps/nexus42/Cargo.toml` — originally planned `agent-client-protocol = "=0.10.4"` dependency; current pin is `=2.1.0` in `crates/nexus-acp-host/Cargo.toml` +- `apps/nexus42/Cargo.toml` — originally planned `agent-client-protocol = "=0.10.4"` dependency; current pin is `=2.2.0` in `crates/nexus-acp-host/Cargo.toml` - `apps/nexus42/src/main.rs` — add `mod acp;` and `Agent` command variant - `apps/nexus42/src/commands/mod.rs` — add `pub mod agent;` @@ -834,5 +836,5 @@ For implementer reference, the ACP protocol lifecycle: > **Durable roadmap:** DR-20, DR-21, DR-22 (ACP-R3..R11: daemon-mediated tool access + permission policy, session persistence, `terminal.kill`/`terminal.wait_for_exit`, `slash_commands`, `agent_plan`, persistent skills manifest, binary auto-update, `session.modes`). > -> Historical V1.0-era framing; ACP hosting now runs in acp-worker child processes — verify before picking up. +> Historical V1.0-era framing; at the time, ACP hosting ran in per-creator `acp-worker` child processes (retired v1.193 P2 — current composition per the shipped boundary in the header). Verify before picking up. diff --git a/.mstar/specs/agent-host.md b/.mstar/specs/agents/agent-host.md similarity index 99% rename from .mstar/specs/agent-host.md rename to .mstar/specs/agents/agent-host.md index a4dfee482..6bfd122c6 100644 --- a/.mstar/specs/agent-host.md +++ b/.mstar/specs/agents/agent-host.md @@ -7,7 +7,7 @@ | **Status** | Normative — shipped through V1.188: Host-mediated orchestration, configured ACP/native registration, dsh SDK runtime/streaming cutover, and verified provider readiness | | **Document class** | Master | | **Normative scope** | Host boundaries, provider model, capability contract, security/supervision invariants | -| **Related** | [daemon-runtime.md](./daemon-runtime.md), [local-runtime-boundary.md](./local-runtime-boundary.md), [acp-client-tech-spec.md](./acp-client-tech-spec.md) | +| **Related** | [daemon-runtime.md](../archived/daemon-runtime.md), [local-runtime-boundary.md](../architecture/local-runtime-boundary.md), [acp-client-tech-spec.md](acp-client-tech-spec.md) | --- @@ -32,7 +32,7 @@ Define **`nexus-agent-host`**: the orchestration/facade above ACP and native CLI ```text OSS CLI (cli-spec) └─ nexus-daemon-runtime - ├─ /v1/daemon/agent-host/* (Daemon API — normative surface per [daemon-runtime.md §2 layered surface](./daemon-runtime.md)) + ├─ /v1/daemon/agent-host/* (Daemon API — normative surface per [daemon-runtime.md §2 layered surface](../archived/daemon-runtime.md)) └─ Arc └─ nexus-agent-host ├─ core: sessions, operations, lifecycle @@ -64,7 +64,7 @@ health. Missing verified Creator/workspace context leaves candidates unavailable **Shipped orchestration path (V1.186, retained in V1.188):** orchestration uses the in-process `PromptExecutor` → daemon adapter → existing `HostFacade` plane -specified in [orchestration-engine.md](orchestration-engine.md) §15. All graph +specified in [orchestration-engine.md](../orchestration/orchestration-engine.md) §15. All graph and capability prompt consumers migrate off worker echo-success together; standalone Character execution stays on the same Host without new Actor IR. @@ -117,7 +117,7 @@ Host discovers providers via: - Explicit configuration - PATH / known command scan -- ACP Registry client (see [registry-integration](./registry-integration.md)) +- ACP Registry client (see [registry-integration](registry-integration.md)) Admission policy limits sessions, concurrent ops, and risky tool classes (detail in implementation SSOT). diff --git a/.mstar/specs/agent-nexus-tool-bridge.md b/.mstar/specs/agents/agent-nexus-tool-bridge.md similarity index 85% rename from .mstar/specs/agent-nexus-tool-bridge.md rename to .mstar/specs/agents/agent-nexus-tool-bridge.md index 0c193aceb..ebac8c152 100644 --- a/.mstar/specs/agent-nexus-tool-bridge.md +++ b/.mstar/specs/agents/agent-nexus-tool-bridge.md @@ -1,19 +1,30 @@ # Agent Nexus Tool Bridge — Normative Specification v1 -**Status**: Master (V1.57 P-last promote) +**Status**: Normative — retained core tool-execution contract; V1.34–V1.186 daemon bridge history preserved below **Document class**: Master **Created**: 2026-06-04 -**Scope**: How **external ACP Agents** invoke selected **Nexus logical capabilities** (`nexus.*`) through the **daemon** — parallel to, not replacing, preset orchestration +**Scope**: Retained admission and dispatch of **Nexus logical capabilities** (`nexus.*`) through `nexus-core`, plus the historical external-ACP-agent / daemon bridge design. This spec does not assert that the deleted worker-to-daemon HTTP topology still ships. **Coordinates with**: - [acp-capability-set.md](acp-capability-set.md) — full logical capability catalog (mostly deferred DF-46) - [agent-host.md](agent-host.md) — Managed-only host, mediation invariants -- [orchestration-engine.md](orchestration-engine.md) — schedule tool dispatch (worker `agent_tool_request` IPC removed, M-007) -- [local-runtime-boundary.md](local-runtime-boundary.md) — CLI vs daemon vs Agent topology -- [creator-workflow.md](creator-workflow.md) — FL-E stages; Work read/patch tools +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — schedule tool dispatch (worker `agent_tool_request` IPC removed, M-007) +- [local-runtime-boundary.md](../architecture/local-runtime-boundary.md) — current core / TS service / Agent ownership and retired daemon topology +- [creator-workflow.md](../creator/creator-workflow.md) — FL-E stages; Work read/patch tools --- +## 0. Current execution authority (post-v1.193 P2) + +The integrated daemon and its `HostToolExecutor` wrappers were deleted in v1.193 P2. The retained execution authority is [`crates/nexus-core/src/execution/capabilities.rs`](../../../crates/nexus-core/src/execution/capabilities.rs), not a daemon handler or an ACP discovery registry: + +- `execute_tool(&ToolContext, &ToolExecuteRequest)` runs admission, calls `host_tool_registry().dispatch(...)`, and audits both success and refusal. `ToolContext` supplies resolved core/domain inputs instead of the retired daemon `WorkspaceState`. +- The allowlist is derived from the **same dispatch spine**: static builtin row → admitted peer tool → admitted user capability from the live orchestration registry. `spine_resolves` and `dispatch` share that order; unresolved IDs return lowercase `not_supported` without invoking a handler. Builtin creator/workspace/permission gates and per-handler ownership checks remain enforced; peer/user tools retain their own admission boundaries. +- `host_tool_registry()` is a process-global `LazyLock` registry with **30 static tools (28 `nexus.*` + 2 `fs/*`)**, not the original six-tool `nexus.*` set. The current roster, exclusion of `nexus.profile.*` metadata, and retirement of daemon caller wrappers are recorded in [`retained_peer_contracts.rs`](../../../crates/nexus-core/tests/retained_peer_contracts.rs), `host_tool_registry_roster_is_the_declared_nexus_surface`. +- The core's host-tool registry and the [`nexus-orchestration` `CapabilityRegistry`](../../../crates/nexus-orchestration/src/capability/mod.rs) are distinct. The latter owns orchestration capabilities; it is not a second static `nexus.*` dispatch table. [capability-registry.md](capability-registry.md) is the shipped registry contract. + +**Historical boundary (§§1–12):** the V1.34 six-tool roster, worker HTTP `tool-executions` topology, daemon `HostToolExecutor`, three-caller wrappers, and P3/P4 handoff below preserve the old design and delivery record. They do not define the current transport or require the deleted daemon to exist. The retained core surface above is not evidence that every former external-ACP-agent entrypoint survives. + ## 1. Purpose Preset orchestration drives **multi-step** creative work via schedules and capabilities (`acp.prompt`, `judge.llm`, `creator.read_memory`, …). External LLM agents can also **actively** request Nexus context during a session (tool calls). V1.34 defines a **single mediated path** through the daemon so that: @@ -26,7 +37,7 @@ Preset orchestration drives **multi-step** creative work via schedules and capab --- -## 2. Frozen decisions +## 2. Frozen decisions (historical daemon design) | # | Decision | | --- | --- | @@ -38,7 +49,7 @@ Preset orchestration drives **multi-step** creative work via schedules and capab --- -## 3. Topology +## 3. Topology (historical worker / daemon HTTP path) ```text [External ACP Agent] @@ -67,7 +78,7 @@ The two paths **must not** share session secrets across creators (IDOR preventio --- -## 4. V1.34 minimal tool registry +## 4. V1.34 minimal tool registry (historical roster) | Tool ID | Access | Handler summary | FL-E relevance | Admission rule | | --- | --- | --- | --- | --- | @@ -125,18 +136,18 @@ Allowed patch fields: Rejected examples: -- `current_stage`, `stage`, `stage_status`, `stage_started_at`, or `stage_completed_at` — direct stage mutation is forbidden; use the stage-advance Daemon API / CLI path defined by [creator-workflow.md](creator-workflow.md). +- `current_stage`, `stage`, `stage_status`, `stage_started_at`, or `stage_completed_at` — direct stage mutation is forbidden; use the stage-advance Daemon API / CLI path defined by [creator-workflow.md](../creator/creator-workflow.md). - `creator_id`, `workspace_id`, `work_id`, or ownership fields — cross-creator reassignment is forbidden. - `run_intents`, schedule rows, preset ids, or capability grants — preset routing remains under orchestration policy, not an agent patch. - Manuscript/body replacement fields outside the `inspiration_log` append surface — full content persistence remains outside P3/P4 minimal tool scope. Invalid or rejected fields fail with `INVALID_INPUT` when malformed and `FORBIDDEN` when they would bypass creator/workspace/stage policy. -**V1.41 (DF-60):** `nexus.work.patch` is blocked while `Works//.completion-lock.json` exists. Mutating patches must acquire the same `works.runtime_lock_holder` path as `creator run continue` (see [novel-writing/multi-work-lifecycle.md](novel-writing/multi-work-lifecycle.md) §5.4). +**V1.41 (DF-60):** `nexus.work.patch` is blocked while `Works//.completion-lock.json` exists. Mutating patches must acquire the same `works.runtime_lock_holder` path as `creator run continue` (see [novel-writing/multi-work-lifecycle.md](../novel-writing/multi-work-lifecycle.md) §5.4). --- -## 5. Request / response contract (normative shape) +## 5. Request / response contract (historical V1.34 shape) Wire JSON types live in `nexus-contracts` when codegen’d; until then: @@ -170,7 +181,7 @@ Wire JSON types live in `nexus-contracts` when codegen’d; until then: --- -## 6. Permissions +## 6. Permissions (historical daemon enforcement) 1. Load `permissions.toml` under workspace `.nexus42/` when present (existing HostToolExecutor behavior). 2. Default-deny for `nexus.work.patch` if policy file exists and tool not granted. @@ -180,9 +191,9 @@ Audit: append row to tool audit log (existing ACP tool audit table pattern). --- -## 7. Dispatch lane unification +## 7. Dispatch lane unification (historical daemon wrappers) -Cross-reference with [orchestration-engine.md](orchestration-engine.md) §6.4: the worker `agent_tool_request` IPC lane was **removed** (M-007) — the surviving dispatch lanes are daemon HTTP tool execute, the internal agent-host route, and the in-process schedule lane (`HostToolExecutor::dispatch_for_schedule` with `HostToolCallerKind::Schedule`). Every `tool_name` in the `nexus.*` namespace or V1.33 `fs/*` baseline must be admitted through this spec's registry. Each lane is an entrypoint into the registry, not a second registry. +Cross-reference with [orchestration-engine.md](../orchestration/orchestration-engine.md) §6.4: the worker `agent_tool_request` IPC lane was **removed** (M-007) — the surviving dispatch lanes are daemon HTTP tool execute, the internal agent-host route, and the in-process schedule lane (`HostToolExecutor::dispatch_for_schedule` with `HostToolCallerKind::Schedule`). Every `tool_name` in the `nexus.*` namespace or V1.33 `fs/*` baseline must be admitted through this spec's registry. Each lane is an entrypoint into the registry, not a second registry. ### 7.1 Single dispatch table invariant @@ -234,7 +245,7 @@ DF-47 row in the deferred tracker is narrowed. Full DF-46 capability matrix (all --- -## 8. Capability registry direction (V1.53 → V1.54) +## 8. Capability registry direction (historical V1.53 → V1.54) Skills-export CLI/spec work is **Cancelled** (DF-50, V1.53). Runtime `nexus.*` dispatch now converges on the [`capability-registry.md`](capability-registry.md) Draft overlay: the bridge remains the mediated external-agent tool path, while the registry becomes the handler/admission/wire/failure/test-vector SSOT. @@ -365,7 +376,7 @@ Required side effects: no platform HTTP attempt; audit row recorded with `audit_ --- -## 11. Contract gap list +## 11. Contract gap list (historical P3 snapshot) This section is informational for P3 and documents current contract gaps. P3 does **not** add schemas or run codegen. The future codegen envelope work (gap table below) is DR-23. @@ -391,7 +402,7 @@ Until the gap is closed, P4 must keep the runtime DTO boundary localized in `Hos --- -## 12. P4 implementer handoff +## 12. P4 implementer handoff (historical) P4 implements this spec; it must not expand into DF-46/47/49/50/55 unless PM opens a separate plan. The minimal handoff is: @@ -554,4 +565,4 @@ Add one schedule-lane test proving `dispatch_for_schedule` and HTTP execute hit --- -*Normative agent tool bridge for V1.34. Implementation: P3 (spec/registry design), P4 (code).* +*Historical agent tool bridge for V1.34: P3 (spec/registry design), P4 (code). Current retained execution authority: §0.* diff --git a/.mstar/specs/capability-registry.md b/.mstar/specs/agents/capability-registry.md similarity index 82% rename from .mstar/specs/capability-registry.md rename to .mstar/specs/agents/capability-registry.md index f76d1192a..82435673d 100644 --- a/.mstar/specs/capability-registry.md +++ b/.mstar/specs/agents/capability-registry.md @@ -1,20 +1,30 @@ # Capability Registry — Master v1 -**Status**: Master (V1.57 P-last promote — bridge Master promotion + P0/P1/P3 spec changes folded in) +**Status**: Normative / Shipped — Master (promoted V1.57 P-last; current core ownership reconciled 2026-09-29) **Document class**: Master **Created**: 2026-06-20 (V1.53 P-1 Draft) -**Last updated**: 2026-06-22 (V1.57 P-last — folded in P0 test vectors + P1 3-caller dispatch + P3 dynamic allowlist mechanism) -**Scope**: Runtime SSOT for Nexus `nexus.*` capability dispatch — 18 host tools (per V1.57 P0 acp §4 roster, reconciled from 35 plan estimate) + dynamic worker allowlist (per V1.57 P3) + 3-caller entry point shape (per V1.57 P1) -**Coordinates with**: [acp-capability-set.md](acp-capability-set.md), [agent-nexus-tool-bridge.md](agent-nexus-tool-bridge.md) (now Master), [acp-client-tech-spec.md](acp-client-tech-spec.md), [orchestration-engine.md](orchestration-engine.md) (§6.4 worker IPC), [daemon-runtime.md](daemon-runtime.md) (3-caller topology), [local-runtime-boundary.md](local-runtime-boundary.md) (3-caller adapter pattern) +**Last updated**: 2026-09-29 — retained core dispatch, static roster and historical authority labels +**Scope**: Runtime SSOT for the retained Nexus host-tool registry and dispatch spine — **30 static host tools (28 `nexus.*` + 2 `fs/*`)**, peer/user-capability resolution, admission and audit ownership. Former daemon worker allowlists and three-caller wrappers are historical. +**Coordinates with**: [acp-capability-set.md](acp-capability-set.md), [agent-nexus-tool-bridge.md](agent-nexus-tool-bridge.md), [acp-client-tech-spec.md](acp-client-tech-spec.md), [orchestration-engine.md](../orchestration/orchestration-engine.md) (separate orchestration registry), [daemon-runtime.md](../archived/daemon-runtime.md) (retired three-caller topology), [local-runtime-boundary.md](../architecture/local-runtime-boundary.md) (current host boundaries) --- ## 0. Document position -This Draft overlay defines the target runtime registry shape for Nexus `nexus.*` capability dispatch. It does **not** replace [acp-capability-set.md](acp-capability-set.md): the capability-set spec remains the logical catalog (capability id + one-line description). This registry spec is the runtime SSOT for handler binding, ACP wire shape, failure mode, and test-vector coverage. +This **Master** defines the **shipped runtime registry contract** for Nexus host-tool dispatch. It does **not** replace [acp-capability-set.md](acp-capability-set.md): that spec remains the logical catalog (capability id + one-line description). This registry spec owns handler binding, catalog shape, admission/failure behavior and test-vector authority. Its former Draft-overlay/target-shape status ended at V1.57 P-last. Non-overlap rule: **catalog = ID + one-liner**; **registry = handler + wire + failure mode + test vector**. +### 0.1 Current implementation authority + +[`nexus_core::execution::capabilities`](../../../crates/nexus-core/src/execution/capabilities.rs) owns `host_tool_registry()` and its process-global `LazyLock`. `execute_tool` runs admission, calls that registry's `dispatch`, then audits success or refusal; `ToolContext` replaces the former daemon `WorkspaceState`. The allowlist uses `spine_resolves`: static builtin → admitted peer → admitted user capability. Unknown IDs fail with `not_supported`; callers must not maintain a second lookup/allowlist table. + +The static registry contains **30 rows: 28 `nexus.*` and 2 `fs/*`**. `build_registry` is the row authority; [`retained_peer_contracts.rs`](../../../crates/nexus-core/tests/retained_peer_contracts.rs), `host_tool_registry_roster_is_the_declared_nexus_surface`, pins the same set and excludes `nexus.profile.*` grouping metadata. Dynamic peer/user entries are additional spine resolutions, not part of this static count. The former 18-tool count was a V1.57 snapshot. + +The [`nexus-orchestration` `CapabilityRegistry`](../../../crates/nexus-orchestration/src/capability/mod.rs) is a **separate registry** of orchestration `Capability` implementations. Its live admitted user entries may be resolved by the core spine; it does not own the static host-tool dispatch table. ACP **agent discovery/selection** is yet another surface, governed by [registry-integration.md](registry-integration.md), not by this spec. + +**Historical boundary:** the integrated daemon and `HostToolExecutor` were deleted in v1.193 P2. §2 preserves versioned field-design/migration records; §5 preserves the promotion checklist; the dated amendments retain their delivery context. Any `WorkspaceState`, daemon wrapper, worker transport, or Draft-overlay wording in those records is historical, not an alternative current authority. + --- ## 1. Scope / non-goals @@ -23,18 +33,20 @@ Non-overlap rule: **catalog = ID + one-liner**; **registry = handler + wire + fa - Registry fields needed to route `nexus.*` capabilities consistently. - Authority chain between catalog, bridge, ACP tech spec, orchestration, and runtime handler code. -- Promote-decision checklist for P-last. +- Preserve the versioned migration and promotion record without treating it as a second current authority. ### 1.2 Non-goals -- Full field semantics in P-1; P0 owns details. +- Reopening the completed P-1/P0 field-design and Master-promotion decisions. - New ACP wire protocol design outside existing ACP-client topology. - Platform REST contracts, cloud publish, standalone MCP, or third-party registry. - Skills-export CLI compatibility; DF-50 is Cancelled. --- -## 2. Registry field skeleton +## 2. Registry field skeleton (historical design and migration record) + +The original field definitions below retain their V1.53–V1.175 context. Current `CapabilityRow` metadata, `RegistryHandlerFn` (using `&ToolContext`, not `&WorkspaceState`), catalog emission and execution are defined in §0.1's core source. Audit ownership is `execute_tool`; the old `HostToolExecutor::execute()` attribution below is historical. | Field | One-line meaning | P0 detail status | | --- | --- | --- | @@ -154,7 +166,7 @@ named remainder placeholder route (`GET /v1/daemon/tools`) carries those strings verbatim. Schemas are descriptive — the builtin dispatch path gains no schema-validation gate this iteration. See -[v1.175 lock spec AR-78](../iterations/v1.175/specs/v1.175-catalog-and-cli-lock.md). +[v1.175 lock spec AR-78](../../iterations/v1.175/specs/v1.175-catalog-and-cli-lock.md). **Cross-reference**: `acp-capability-set.md` is the logical catalog (one-liner per ID). The daemon catalog is the runtime emission of @@ -201,6 +213,8 @@ verifies that all 7 fields are populated for every registered row. ### 2.8 `nexus.reference.refresh` (V1.58 P1 — DF-44) +**Historical V1.58 P1 binding:** the following row predates the V1.58 P3 host-tool addition. Today `build_registry` also binds `nexus.reference.refresh` as a core host tool (`Access::Write`, `ADMISSION_WRITE_WORKSPACE`, `registry_reference_refresh`); the separate orchestration handler remains distinct. + **id**: `nexus.reference.refresh` **access**: `Read` + side-effect (writes `last_refreshed_at` / `refresh_status` to `reference_sources`) **admission**: Reference source must exist in `reference_sources` table; `refresh_policy != 'offline'` (else `policy_blocked`); URL must be valid (else `invalid_input`); network timeout returns `transient_error`. @@ -215,9 +229,9 @@ verifies that all 7 fields are populated for every registered row. 1. Repo root `AGENTS.md` defines scope and local-first boundaries. 2. `acp-capability-set.md` defines the logical capability catalog. -3. This Draft overlay defines the runtime registry contract for active V1.53 work. -4. `agent-nexus-tool-bridge.md` defines mediated external-agent tool invocation and admission invariants. -5. `acp-client-tech-spec.md` and `orchestration-engine.md` define ACP client topology and schedule/tool request participation. +3. This shipped Master defines the runtime registry contract; §0.1 identifies current core ownership and the historical sections it supersedes. +4. `agent-nexus-tool-bridge.md` defines retained core admission/execution invariants and preserves the historical external-agent transport record. +5. `acp-client-tech-spec.md` and `orchestration-engine.md` define current ACP provider composition and the separate orchestration capability surface. 6. Runtime implementation must not create a second dispatch table for the same `nexus.*` id. --- @@ -227,16 +241,16 @@ verifies that all 7 fields are populated for every registered row. | Existing spec | Boundary | | --- | --- | | `acp-capability-set.md` | Logical catalog only; no runtime dispatch authority. | -| `agent-nexus-tool-bridge.md` | Master spec (promoted V1.57 P-last). Entrypoint/admission history and mediated external-agent tool invocation; registry is the shared runtime SSOT underneath it. | +| `agent-nexus-tool-bridge.md` | Master spec (promoted V1.57 P-last). Retained core admission/execution boundary plus historical external-agent transport; this registry is the shared runtime dispatch authority. | | `acp-client-tech-spec.md` | ACP client behavior and handshake; registry rows may reference wire details but do not redefine ACP. | -| `orchestration-engine.md` | Schedules and worker tool requests; registry may serve schedule-initiated tool dispatch but does not replace preset grammar. | +| `orchestration-engine.md` | Preset grammar and orchestration capabilities; its registry is separate from the core host-tool registry. Former worker-tool topology is historical. | | `cli-spec.md` | User-visible commands; capability registry is not a CLI command tree. | --- -## 5. Acceptance (spec-level) +## 5. Acceptance (historical promotion checklist) -Promote decision checklist for P-last: +V1.53–V1.57 promotion checklist, preserved as recorded. Master promotion completed in V1.57 P-last; the unchecked decision row below is historical, not an open authority choice. - [x] P0 has filled field semantics for all registry fields. - [x] P0 has recorded explicit cutover triggers and no lingering dual dispatch path. @@ -248,9 +262,9 @@ Promote decision checklist for P-last: --- -## V1.58 P0 Draft overlay: `registry.refresh` capability body extension +## V1.58 P0: `registry.refresh` capability body extension (historical amendment) -**Status**: Draft (V1.58 P0) +**Historical status**: Draft (V1.58 P0 record; not the status of this shipped Master). ### Body extension @@ -436,7 +450,7 @@ in `crates/nexus-orchestration/src/capability/mod.rs`, NOT in failure + admission gate) live inline in each handler module. Delta-package semantics and the agent-vs-runtime split are normatively defined -in [`world-delta-propose-apply.md`](world-delta-propose-apply.md) (Draft, V1.60 +in [`world-delta-propose-apply.md`](../contracts/world-delta-propose-apply.md) (Draft, V1.60 P0). No new DB migrations — all five reuse existing `narrative_worlds`, `narrative_timeline_events`, and `kb_key_blocks` tables. diff --git a/.mstar/specs/agents/registry-integration.md b/.mstar/specs/agents/registry-integration.md new file mode 100644 index 000000000..97d7e0bb6 --- /dev/null +++ b/.mstar/specs/agents/registry-integration.md @@ -0,0 +1,212 @@ +# Nexus ACP Registry Integration + +**Status**: Normative for the shipped behavior identified below; original unshipped design is explicitly labeled +**Document class**: Master + +## 0. Document position + +This document specifies **ACP agent discovery and selection**, registry caching and agent transport. It does **not** govern `nexus.*` host-tool dispatch or the `nexus.registry.refresh` tool: those belong to [capability-registry.md](capability-registry.md) and the retained core execution surface. + +Related docs: nexus-platform `v1-spec/architecture.md` §6.4–6.5, [`cli-spec.md`](../cli/cli-spec.md) §6.8、§11。 + +**Current owners (post-v1.193 P2; reconciled 2026-09-29):** [`nexus-acp-host`](../../../crates/nexus-acp-host/src/registry.rs) owns the Rust registry client/cache and ACP client/transport; [`nexus-agent-host::HostManager`](../../../crates/nexus-agent-host/src/core/manager.rs) owns provider/session admission; [`packages/nexus-provider-acp`](../../../packages/nexus-provider-acp/src/acp.ts) owns the TS service's ACP callback implementation and its agent subprocesses. [`apps/nexus-service/src/index.ts`](../../../apps/nexus-service/src/index.ts) supplies those callbacks to the native core except in domain-only mode. Electron owns the local service lifecycle, not the ACP Registry. The old daemon-owned supervision/restart/backoff model is **historical**: `nexus-daemon-runtime` and the integrated daemon were deleted in v1.193 P2. + +### 0.1 Upstream registry (canonical source) + +The **Agent Client Protocol registry** is maintained upstream as open data and tooling: agent listings, distribution metadata, and JSON schemas live in the community project **`agentclientprotocol/registry`**, with a published **HTTPS index** for clients to fetch. Nexus does not host that authority. + +- **Shipped canonical endpoint:** `REGISTRY_URL` in [`registry.rs`](../../../crates/nexus-acp-host/src/registry.rs) is `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json`. The client parses the response as `RegistryManifest`; it does not currently negotiate upstream schema revisions. +- **Original design (not shipped as a source-selection policy):** workspace overrides / enterprise mirrors, pinned index versions or ETags, and explicit upstream `FORMAT.md` / schema-revision compatibility remain design considerations, not current fetch guarantees. + +Authentication expectations for agents are negotiated on the ACP connection; registry metadata is not proof of provider readiness or permission to execute. + +--- + +## 1. Goals + +- Treat Registry as the ecosystem layer for compatible agents. +- Make agent resolution deterministic, auditable, and offline-tolerant where possible. +- Keep **stdio** as V1.0 default for local agents; position remote transports as optional/future. + +--- + +## 2. Roles and non-roles + +### 2.1 Current runtime responsibilities + +- `nexus-acp-host::RegistryClient` fetches the canonical index and reads/writes its local cache (§§3–4). +- The CLI resolves registry references and persists a workspace default agent; selection is not the original compatibility/scoring algorithm (§5). +- `HostManager` owns admitted provider recipes, session routing and readiness policy. Its normal boot catalog is built from explicit configuration and PATH discovery; [`core/readiness.rs`](../../../crates/nexus-agent-host/src/core/readiness.rs) passes an empty registry-source list to `ProviderCatalog::build_from_sources`. The registry-to-catalog mapper is not evidence of an automatic remote fetch at service boot. +- Rust `AcpProvider` and the TS ACP provider own their agent connections/subprocesses; the core/native composition chooses the provider port. See [acp-client-tech-spec.md](acp-client-tech-spec.md) for that current composition. + +**Historical design scope:** generalized ACP-version/capability/platform filtering, creator-registration probing, and daemon-owned process supervision/restart/backoff were original integration goals. They must not be inferred from registry membership or treated as current daemon responsibilities. + +### 2.2 Explicit non-responsibilities + +- Publishing Nexus hosting infrastructure as an agent discoverable by third-party ACP clients (including the historical daemon). +- Acting as Registry hosting authority. + +--- + +## 3. Manifest sources and fetch rules + +### 3.1 Shipped source behavior + +`RegistryClient::get_registry()` prefers a usable local cache. With no usable cache it fetches the fixed canonical HTTPS endpoint; it does not implement workspace override or mirror precedence. + +**Original source-priority design (not shipped):** + +1. Remote canonical Registry (HTTPS) +2. Workspace override +3. User cache +4. Local static mirror + +### 3.2 Shipped fetch behavior + +`fetch_from_cdn` / `fetch_and_save` perform a GET, require a successful HTTP status and parse JSON. The client has a 30-second request timeout; the background helper additionally bounds the send with 60 seconds. Cache-write failure does not fail a successful foreground fetch. Conditional ETag/If-Modified-Since requests and manifest signature/checksum verification are **not implemented** by this client. + +**Original fetch design (not shipped guarantees; daemon wording historical):** + +- Use ETag / If-Modified-Since when available. +- Failures must not crash daemon; enter degraded mode. +- Verify manifest signatures/checksums when Registry provides them. + +### 3.3 Shipped offline behavior + +A stale cache is returned immediately even when background refresh fails; 24 hours is a freshness threshold, not an offline-use expiry. No usable cache plus a failed fetch returns an error. A usable cache without readable metadata is returned without scheduling a refresh. This is the `get_registry` implementation, not the original TTL-constrained fallback below. + +**Original offline design (superseded, not current behavior):** + +- If remote fetch fails, runtime uses last good cached manifest if within TTL. +- If no cache exists, runtime requires local override or manual agent configuration. + +--- + +## 4. Cache policy + +**Shipped cache contract:** [`registry.rs`](../../../crates/nexus-acp-host/src/registry.rs) stores `cache.json` (full registry response) and `cache_meta.json` (`fetched_at`, `registry_version`) under **`$HOME/.nexus42/registry/`**. Fresh cache (<24h) skips the network; stale cache (≥24h with metadata) is served immediately and triggers background refresh. `RegistryClient::refresh()` bypasses freshness; CLI registry probing calls it. There is no separate icon/package/version-list cache or config/doctor invalidation mechanism in this client. + +**Historical design boundary (§§4.1–4.4):** the artifact matrix, invalidation triggers, proposed `registry refresh` CLI spelling and `cache/registry/` location below are the original design, **not the shipped cache contract**. + +### 4.1 What is cached + +- Registry manifest files +- Agent package metadata +- Small artifacts such as icons/descriptions + +### 4.2 TTL and freshness + +| Artifact | Default TTL | Notes | +| --- | --- | --- | +| Manifest index | 24h | refresh in background | +| Agent version list | 24h | pin overrides TTL | +| Downloaded agent package | explicit | only if Registry supports binary distribution | + +Runtime may serve stale cache immediately while async refresh proceeds. + +### 4.3 Cache invalidation triggers + +- User runs `nexus42 acp registry refresh` +- TTL expiry + next online event +- Workspace config changes +- Doctor detects checksum mismatch vs pinned agent + +### 4.4 Storage location + +- Under `$HOME/.nexus42/cache/registry/` (or a workspace-keyed subtree still under `$HOME/.nexus42/cache/`) + +--- + +## 5. Selection and filtering rules + +**Shipped selection:** `RegistryClient::find_agent` returns the first case-insensitive ID/name **prefix** match in registry order, falling back to the first substring match. It does not rank exact IDs ahead of earlier prefix matches or implement the hard-filter/soft-scoring design below. [`apps/nexus42/src/commands/acp/mod.rs`](../../../apps/nexus42/src/commands/acp/mod.rs) implements `agent use` as a validated reference persisted to `$HOME/.nexus42/creators//workspaces//acp-default-agent.toml`; it does not fetch or compatibility-check the agent at pin time. `registry inspect` displays the matched entry, not filter pass/fail reasoning. + +**Historical design boundary (§§5.1–5.4):** the compatibility filters, scoring order, explanatory inspect output and fallback policy below are original design targets, **not shipped selection guarantees**. Explicit provider configuration and Host readiness admission are separate from this registry lookup. + +### 5.1 Hard filters + +- ACP protocol version outside supported window +- Transport unsupported for current OS / runtime mode +- Missing required Nexus capabilities for selected profile +- Platform policy flags + +### 5.2 Soft scoring + +Prefer, in order: + +1. User pinned agent +2. Workspace default +3. Highest compatible version within same major line +4. Local stdio agents over remote agents +5. Recent successful agent + +### 5.3 Explicit user binding + +- `nexus42 acp agent use` writes pin record under `$HOME/.nexus42/` or workspace-linked config (not ad-hoc under `/` without user intent) +- `nexus42 acp registry inspect` shows why an agent passed/failed filters + +### 5.4 Fallback path + +If Registry resolution fails: + +- Allow manual agent command in config +- Doctor prints actionable fix steps + +--- + +## 6. Transports: stdio vs remote + +**Current local transport/ownership:** the CLI resolves NPX first, otherwise a binary recipe for the current platform, and errors if neither is usable (`resolve_launch_command`). [`nexus-acp-host/src/transport.rs`](../../../crates/nexus-acp-host/src/transport.rs) spawns the stdio agent and owns its process teardown; [`nexus-agent-host/src/providers/acp.rs`](../../../crates/nexus-agent-host/src/providers/acp.rs) binds an owned process to each Rust Host session. For the TS service path, [`process-owner.ts`](../../../packages/nexus-provider-acp/src/process-owner.ts) spawns the admitted recipe and connects `ClientSideConnection` over the child's pipes. Neither composition uses the retired daemon supervisor or establishes a daemon restart/backoff contract. + +### 6.1 V1.0 default: JSON-RPC over stdio + +- Nexus client spawns agent subprocess and speaks JSON-RPC over stdin/stdout. +- **Historical ownership claim (superseded v1.193 P2):** “Process supervision and restart/backoff are owned by daemon.” Current owners are listed above; no such daemon exists. +- Logs should go to stderr with a structured policy, not stdout framing. + +### 6.2 HTTP / WebSocket (unshipped design) + +- Supported only when explicitly enabled by user policy. +- Require TLS and policy gating. + +### 6.3 Transport selection algorithm (historical design; not shipped) + +1. If pinned agent specifies transport, honor it if allowed. +2. Else prefer `stdio` local launch when manifest provides launch spec. +3. Else use remote endpoint if permitted. +4. Else fail with explicit configuration error. + +--- + +## 7. CLI commands + +Minimum recommended: + +**Historical recommendation, not an executable command inventory:** in the current CLI `RegistryCommand` has `list` and `inspect`, not `refresh`; `nexus42 acp probe --registry` invokes `RegistryClient::refresh()`. The list below retains the original recommendation. + +- `nexus42 acp registry list` +- `nexus42 acp registry inspect ` +- `nexus42 acp registry refresh` +- `nexus42 acp agent use ` +- `nexus42 acp probe` + +`nexus42 acp probe` should be reusable by creator registration flows to capture declared capabilities and transport metadata before the platform issues creator credentials. + +--- + +## 8. Security considerations + +- **Supply chain**: prefer signed manifests when available. +- **Typosquatting**: show publisher identity prominently. +- **Remote agents**: higher risk; default-off or strict allowlist in v1. +- **Privacy**: Registry fetch leaks coarse usage timing; provide optional offline mode. + +--- + +## 9. Open items + +> **Durable roadmap:** the open items below (pin upstream schema compat, enterprise mirror, binary distribution) are DR-55. + +- Pin field-level compatibility to upstream **`registry.schema.json` / `agent.schema.json`** revisions as they ship in the **`agentclientprotocol/registry`** project (repo URL and default index in §0.1 below). +- Enterprise mirror documentation and trust roots. +- Binary agent distribution vs path-only local agents. diff --git a/.mstar/specs/actor-product-model.md b/.mstar/specs/architecture/actor-product-model.md similarity index 97% rename from .mstar/specs/actor-product-model.md rename to .mstar/specs/architecture/actor-product-model.md index 35a3aa760..c2b77c191 100644 --- a/.mstar/specs/actor-product-model.md +++ b/.mstar/specs/architecture/actor-product-model.md @@ -3,7 +3,7 @@ > **Status:** Draft overlay (2026-09-04 user product lock; **honesty amended 2026-09-06**). **v1.184 shipped** the Character bearer, ActorWorldBinding, three KE owner scopes, Character KnowledgeView, one-host Character execution, Character SOUL/Memory, and ToM L1/L2 (PR [#240](https://github.com/42ch-dev/nexus/pull/240)). **v1.185 shipped** (PR [#241](https://github.com/42ch-dev/nexus/pull/241)): identity edit, reversible archive/restore, post-create WorldSheet maintenance, KE content/detail/edit/delete, and run-connected `--remember`. **v1.191 shipped** on the v1.191 plan branch (integration/PR delivery is PM-owned; no merge artifact yet): the Actor holder governance on the existing CLI/daemon surfaces — stable Creator/Character holders, native `holder_entry_id`/`disclosure`, Creator management review vs holder-filtered ActorView, the `creator_only` cutover, production extraction through the SPOKE orchestration boundary, and Connect Actor grants ([holder-governance.md](holder-governance.md)). Product vocabulary herein remains authoritative. This file is **not** a second wire/API SSOT for local implementation snapshots. > **Document class:** Draft overlay (product-model SSOT; user-locked product semantics, authoritative for planning) > **Scope:** `ActorRef` (`Creator | Character`) with per-kind bearers; Creator operational ownership; Character SOUL/Memory/ToM/image; ActorWorldBinding (1..n per active Character, atomic initial binding); WorldSheet distinction; KnowledgeEntry canonical ownership and read views (Creator omniscient read, Character KnowledgeView); one-Agent-Host execution with session isolation; Viewpoint; current-vs-planned migration contract; shipped v1.185 developer maintenance (§11); non-goals. -> **Coordinates with:** [entity-scope-model.md](entity-scope-model.md) (shipped KE taxonomy + scope hierarchy), [agent-host.md](agent-host.md) and [acp-client-tech-spec.md](acp-client-tech-spec.md) (the one host plane; ACP sessions), [creator-workflow.md](creator-workflow.md) and [creator-memory-soul-lifecycle.md](creator-memory-soul-lifecycle.md) (shipped Creator SOUL/Memory bearer), [spoke-adapter-architecture.md](spoke-adapter-architecture.md) (V1.164–V1.166 l5 MindState/belief/observation carriers; moment context assembly), [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md), [world-membership.schema.json](../../schemas/domain/world-membership.schema.json) (shipped Creator↔World aggregate), repo-root [STRATEGY.md](../../STRATEGY.md) + [CONCEPTS.md](../../CONCEPTS.md). +> **Coordinates with:** [entity-scope-model.md](entity-scope-model.md) (shipped KE taxonomy + scope hierarchy), [agent-host.md](../agents/agent-host.md) and [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) (the one host plane; ACP sessions), [creator-workflow.md](../creator/creator-workflow.md) and [creator-memory-soul-lifecycle.md](../creator/creator-memory-soul-lifecycle.md) (shipped Creator SOUL/Memory bearer), [spoke-adapter-architecture.md](spoke-adapter-architecture.md) (V1.164–V1.166 l5 MindState/belief/observation carriers; moment context assembly), [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md), [world-membership.schema.json](../../../schemas/domain/world-membership.schema.json) (shipped Creator↔World aggregate), repo-root [STRATEGY.md](../../../STRATEGY.md) + [CONCEPTS.md](../../../CONCEPTS.md). ## 0. Document position @@ -50,8 +50,8 @@ Each Actor kind has its **own bearer** — the storage/identity aggregate that c The Creator is the first Actor kind: the god/orchestrator/narrative driver who **conducts** the story, and the **operational owner / admission identity** for everything Nexus executes. -- **Ownership.** The Creator owns Worlds via the shipped `WorldMembership` aggregate — Creator↔World only ([world-membership.schema.json](../../schemas/domain/world-membership.schema.json)). Characters are **Creator-owned** durable identities. ActorWorldBindings join owned entities (§4.2). -- **Bearer.** The Creator carries SOUL + Memory through the shipped Creator memory pipeline (see [creator-workflow.md](creator-workflow.md), [creator-memory-soul-lifecycle.md](creator-memory-soul-lifecycle.md)). +- **Ownership.** The Creator owns Worlds via the shipped `WorldMembership` aggregate — Creator↔World only ([world-membership.schema.json](../../../schemas/domain/world-membership.schema.json)). Characters are **Creator-owned** durable identities. ActorWorldBindings join owned entities (§4.2). +- **Bearer.** The Creator carries SOUL + Memory through the shipped Creator memory pipeline (see [creator-workflow.md](../creator/creator-workflow.md), [creator-memory-soul-lifecycle.md](../creator/creator-memory-soul-lifecycle.md)). - **Omniscient read** over owned knowledge — see §5.2. - **Execution gate.** Character execution requires the requesting Creator to own **both** the Character and the World, plus an active binding; a missing/invalid binding or incomplete view **fails closed** — never falls back to the Creator/god context or a default ACP session. - **Stability.** Existing `creator_id` storage and FKs are not re-keyed, and Creator execution stays byte-stable when no Character is bound. @@ -123,7 +123,7 @@ One stable service-managed holder KE belongs to each Creator and Character ident ## 6. Execution — one Agent Host, session isolation -- **One Agent Host / runtime / provider plane serves both Actor kinds** (see [agent-host.md](agent-host.md), [acp-client-tech-spec.md](acp-client-tech-spec.md)). No second runtime or process plane. +- **One Agent Host / runtime / provider plane serves both Actor kinds** (see [agent-host.md](../agents/agent-host.md), [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md)). No second runtime or process plane. - A Character session executes **under the owning Creator's admission boundary**, with an **isolated ACP conversation history** per Actor/World view. - The ACP session (`HostSessionId`) is a pipe: isolation boundary, not identity (§2.1). - Actor identity in Moment context is optional and additive; the Creator-only execution path is byte-stable (§8). diff --git a/.mstar/specs/entity-scope-model.md b/.mstar/specs/architecture/entity-scope-model.md similarity index 87% rename from .mstar/specs/entity-scope-model.md rename to .mstar/specs/architecture/entity-scope-model.md index 2575ea334..65a1f56e5 100644 --- a/.mstar/specs/entity-scope-model.md +++ b/.mstar/specs/architecture/entity-scope-model.md @@ -8,7 +8,7 @@ | **Document class** | Master | | **Scope** | Global/User/Creator/World/Timeline/Event/Moment hierarchy; entity ownership; `kb`/`knowledge` naming boundaries; scope transition rules | | **Last updated** | 2026-08-12 — V1.162 Review & Edit chain (architect pass 2): §6.6 fork-creation write boundary + lineage projection contract (PD-01 local-vs-platform reconciliation; carrier approach B locked). | -| **Related** | [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md), [cli-spec.md](./cli-spec.md), [daemon-runtime.md](./daemon-runtime.md), [orchestration-engine.md](./orchestration-engine.md), [compute-module-abi.md](./compute-module-abi.md), [wasm-host.md](./wasm-host.md), [local-db-schema.md](./local-db-schema.md), [spoke-adapter-architecture.md](./spoke-adapter-architecture.md), [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md) | +| **Related** | [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md), [cli-spec.md](../cli/cli-spec.md), [daemon-runtime.md](../archived/daemon-runtime.md), [orchestration-engine.md](../orchestration/orchestration-engine.md), [compute-module-abi.md](../compute/compute-module-abi.md), [wasm-host.md](../compute/wasm-host.md), [local-db-schema.md](../runtime/local-db-schema.md), [spoke-adapter-architecture.md](spoke-adapter-architecture.md), [`docs/ARCHITECTURE.md`](../../../docs/ARCHITECTURE.md) | This file is normative for V1.23 crate wiring and naming alignment. When this file overlaps older wording in prior specs, keep the locked decisions here and update the @@ -56,7 +56,7 @@ Global > **V1.156 amendment (shipped)**: the 3×2 matrix is completed (World×Moment + Work×Brief closed — see §1.4.4). The amendment is frontend-only (`wire_contracts_changed: false`); it adds no scope-ownership, uniqueness, or transition rule. The V1.123 carrier locks (§1.4.1) are unchanged. Product semantics: `product-locks.md` PD-2 / PD-3. -> **V1.200 carrier amendment (shipped) — persisted Work-owned scene/beat carrier.** V1.200 replaces the deferred/fixtures-only Moment carrier described in §1.4.1, §1.4.3 and §1.4.4 with persisted Work-owned `WorkOutline.scenes[]` / `beats[]` (`{scene_id, chapter_id, title, status}` / `{beat_id, scene_id, title, status}`), authored through four additive `outline.patch_structure` operations (`add_scene` / `remove_scene` / `add_beat` / `remove_beat`) and read through the existing outline read route. Carrier/write-boundary contract: [`canvas-strategy-surface.md`](canvas-strategy-surface.md) §3.3.3 (V1.200 amendment) + §3.5 (V1.200 scene/beat authoring). This is a wire-carrier extension, **not a new scope**: Outline remains the authoring home, both Timeline Moment projections stay read-only, default layers remain unchanged, and Moment Context Assembly is unaffected. The V1.156 frontend-only statement remains historical (V1.200 itself is a wire change). +> **V1.200 carrier amendment (shipped) — persisted Work-owned scene/beat carrier.** V1.200 replaces the deferred/fixtures-only Moment carrier described in §1.4.1, §1.4.3 and §1.4.4 with persisted Work-owned `WorkOutline.scenes[]` / `beats[]` (`{scene_id, chapter_id, title, status}` / `{beat_id, scene_id, title, status}`), authored through four additive `outline.patch_structure` operations (`add_scene` / `remove_scene` / `add_beat` / `remove_beat`) and read through the existing outline read route. Carrier/write-boundary contract: [`canvas-strategy-surface.md`](../surfaces/canvas-strategy-surface.md) §3.3.3 (V1.200 amendment) + §3.5 (V1.200 scene/beat authoring). This is a wire-carrier extension, **not a new scope**: Outline remains the authoring home, both Timeline Moment projections stay read-only, default layers remain unchanged, and Moment Context Assembly is unaffected. The V1.156 frontend-only statement remains historical (V1.200 itself is a wire change). This subsection is **additive** — it does not rewrite §1.1 (canonical scope tree) or §1.2 (scope definitions). It canonizes three Timeline zoom layers — **Brief**, **Narrative**, **Moment** — as a re-projection of the existing `World > Timeline > Event > Moment` scope hierarchy, and locks the World/Work layer composition. @@ -139,12 +139,12 @@ The canonical `World > Timeline > Event > Moment` scope tree (§1.1) is **unchan - Narrative → Event-level projection (already in §1.1 as `Timeline > Event`). - Moment → Work-scoped projection at `Event > Moment` granularity (with the dual meaning noted in §1.4.3). -No new scope-ownership rule. No new uniqueness constraint. No new transition rule. The V1.123 changes are confined to (a) one additive wire enum value (`BlockType::Era`) per §5.1.1 narrative taxonomy extension and (b) one additive overlay on the Canvas surface contract (`specs/canvas-strategy-surface.md` V1.123 overlay — see `canvas-strategy-surface.md`). The V1.156 matrix completion adds **no** scope-ownership, uniqueness, or transition rule either — it is a frontend-only projection extension (`wire_contracts_changed: false`, version-scoped to V1.156); both non-owned layers (World-Moment, Work-Brief) are read-only projections that preserve the existing `World > Timeline > Event > Moment` scope tree. The **V1.200** scene/beat carrier lands on the same terms: it extends the persisted shape of an already-Work-owned outline artifact (`WorkOutline.scenes[]` / `beats[]`) and its patch operation enum, adding **no** scope, ownership, uniqueness, or transition rule — the scope tree is unchanged. +No new scope-ownership rule. No new uniqueness constraint. No new transition rule. The V1.123 changes are confined to (a) one additive wire enum value (`BlockType::Era`) per §5.1.1 narrative taxonomy extension and (b) one additive overlay on the Canvas surface contract (`specs/surfaces/canvas-strategy-surface.md` V1.123 overlay — see `canvas-strategy-surface.md`). The V1.156 matrix completion adds **no** scope-ownership, uniqueness, or transition rule either — it is a frontend-only projection extension (`wire_contracts_changed: false`, version-scoped to V1.156); both non-owned layers (World-Moment, Work-Brief) are read-only projections that preserve the existing `World > Timeline > Event > Moment` scope tree. The **V1.200** scene/beat carrier lands on the same terms: it extends the persisted shape of an already-Work-owned outline artifact (`WorkOutline.scenes[]` / `beats[]`) and its patch operation enum, adding **no** scope, ownership, uniqueness, or transition rule — the scope tree is unchanged. #### 1.4.6 Cross-reference - **Iteration-scoped architecture (authoritative for carrier implementation):** `three-layer-architecture.md` §2 (Brief carrier), §3 (Moment carrier), §4 (wire_contracts_changed), §6 (conflict policy), §7 (Work Timeline adapter contract). -- **Canvas surface contract overlay:** [`specs/canvas-strategy-surface.md`](canvas-strategy-surface.md) §3.3.3 (V1.123 three-layer overlay + V1.156 3×2 matrix completion amendment + **V1.200 persisted scene/beat carrier amendment**) and §3.5 (structured write boundary — **V1.200 scene/beat authoring through `outline.patch_structure`**). +- **Canvas surface contract overlay:** [`specs/surfaces/canvas-strategy-surface.md`](../surfaces/canvas-strategy-surface.md) §3.3.3 (V1.123 three-layer overlay + V1.156 3×2 matrix completion amendment + **V1.200 persisted scene/beat carrier amendment**) and §3.5 (structured write boundary — **V1.200 scene/beat authoring through `outline.patch_structure`**). - **Product spec (author voice + demo script):** `three-layer-product-spec.md`. - **V1.156 product locks (World-Moment + Work-Brief semantics):** `product-locks.md` PD-2 (Work-Brief projection) + PD-3 (World-Moment projection). - **Layer feel contract (P4 handoff):** `layer-feel-differentiation.md`. @@ -155,7 +155,7 @@ No new scope-ownership rule. No new uniqueness constraint. No new transition rul | Scope | Entity types that live here | Primary owner crate(s) | | --- | --- | --- | -| `Global` | Schema bundle identity, contract schema versions, product-wide command/capability names, global daemon/runtime constants | `nexus-contracts`; `nexus42` for CLI surface; `nexus-daemon-runtime` for local runtime process constants | +| `Global` | Schema bundle identity, contract schema versions, product-wide command/capability names, global runtime constants | `nexus-contracts`; `nexus42` for the CLI and headless `nexus-runtime` process (`apps/nexus42/src/bin/nexus-runtime.rs`) | | `User` | User account/profile, platform session, Pairing records, user-level knowledge index, user-global reference corpus | `nexus-cloud-domain` for User/Pairing invariants; `nexus-cloud-sync` for HTTP transport; `nexus-knowledge` for user-scoped knowledge/reference index | | `Creator` | Creator aggregate, Creator credentials/cache records, active Creator selection, workspace registrations, SOUL, long-term memory, review queue/personality I/O | `nexus-creator`; `nexus-creator-memory`; `nexus-home-layout`; `nexus-local-db` for local persistence mechanics | | `World` | World aggregate, world membership, fork branches, story manifests, manuscript state/projections, narrative KB graph, KnowledgeEntries, SourceAnchors | `nexus-narrative`; `nexus-knowledge` for KB graph insertion/query and KnowledgeEntry/SourceAnchor logic | @@ -168,7 +168,7 @@ No new scope-ownership rule. No new uniqueness constraint. No new transition rul Local persistence is an implementation boundary and does not add new canonical scopes: - `$HOME/.nexus42/creators//workspaces//state.db` - is the per-Creator/per-workspace local working copy from [local-db-schema.md](./local-db-schema.md). + is the per-Creator/per-workspace local working copy from [local-db-schema.md](../runtime/local-db-schema.md). - `workspace_slug` is unique under `creator_id` and is managed by CLI/daemon local state. - A workspace may stage or bind multiple `world_id` values; requests that touch a World MUST carry `world_id` explicitly. @@ -228,10 +228,10 @@ explicitly declares uniqueness. | `nexus-creator` | `Creator` | Owns Creator aggregate logic, credential/cache hooks, active Creator local state, and conversions over contract types. No platform HTTP. | | `nexus-creator-memory` | `Creator` memory subdomain | Owns SOUL, long-term memory, review, and personality/experience I/O under Creator scope. | | `nexus-knowledge` | `World` (narrative KB) + `User` (global knowledge) | Two-tier knowledge crate merged in V1.139 (former `nexus-kb`). World-scoped: narrative KnowledgeEntries, SourceAnchors, graph insertion/query, narrative KB lifecycle; holds spoke `KnowledgeEntry` natively with `extensions.nexus` accessors via `nexus-spoke-adapter`. User-scoped: global knowledge/reference indexing and storage; tag-driven, may be pulled into Moment context assembly. Does not own Creator memory semantics. | -| `nexus-narrative` | `World`, `Timeline`, `Event` | Owns creative-work narrative state: current work background, world state, forks, timelines, events, story/manuscript projections, and narrative consistency. | +| `nexus-narrative` | `World`, `Timeline`, `Event` | Owns creative-work narrative domain models: world state, `World::fork` / `ForkBranch`, timelines, events, story/manuscript projections, and narrative consistency. Domain fork models do not imply populated local world-fork metadata: local authoring forks use branch-level marker lineage, while the SQLite gateway returns world-level fork fields as `false` / `None` (§6.6). | | `nexus-spoke-adapter` | SPOKE consumption boundary | Constructs spoke standard objects with `extensions.nexus` populated; delegates standard lifecycle ops to `spoke-operations`. Enforces the spoke-operations call-boundary invariant (spoke-standard operands only). The sole crate that directly depends on `spoke-operations`. | | `nexus-moment-context-assembly` | `Moment` | Owns session-start moment context aggregation. It runs before a session begins and aggregates relevant local domains: Creator memory, narrative state, World KB assets, and User knowledge. Optional `cloud-stage` may merge platform context, but daemon default remains local Stage-0. | -| `nexus-daemon-runtime` | Runtime host, not entity owner | Hosts local APIs, DB handles, orchestration, and agent-host. It MUST NOT own cloud transport or platform User/Pairing invariants. | +| `nexus-daemon-runtime` (historical; retired v1.193) | Former runtime host, not entity owner | Hosted local APIs, DB handles, orchestration, and agent-host before retirement. This is a historical ownership boundary, not a current implementation anchor; current service-family authority is `nexus-core` (see [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md) §2.1). | | `nexus-orchestration` | Execution sessions/schedules, not hierarchy owner | Owns presets, schedules, workers, and capability registry. It carries `creator_id`/workspace/world references as execution context, but it does not redefine entity ownership. | #### 5.5.8 Conditional routing branch input visibility (V1.56 P3 amendment) @@ -241,7 +241,7 @@ When the conditional routing engine (DF-56) evaluates a state's `next: { kind: c - **`_context.registry_refresh.*`** — fields projected from the `nexus.registry.refresh` capability output (which is itself an entity-scope snapshot of the capability registry). Fields include `source` (`synthetic` | `network` | `synthetic_fallback`), `snapshot_version`, `capability_count`, `fallback_reason` (CdnError variant stringified per V1.56 P1 fix-wave), `retry_count`. The branch input is read-only; the capability invocation does not mutate the registry. - **`_context.workspace.*`** — fields projected from the active workspace session (V1.56 P0 OCC + persistent session). Fields include `session_id`, `conflict_detected` (bool; OCC outcome of last commit), `changes_applied` (count of paths committed), `workspace_root` (canonical path). The branch input is read-only; expression evaluation does not invoke `workspace.commit` itself. -Branch inputs do **not** redefine entity ownership. The expression evaluator reads through existing API surfaces: +Branch inputs do **not** redefine entity ownership. The following API wiring is a **V1.56 historical snapshot**; the former daemon handlers are not current implementation anchors: - Registry refresh input: `nexus-orchestration::tasks::inject_registry_refresh_context()` → reads `nexus.registry.refresh` capability output via existing capability registry machinery. - Workspace input: `nexus-orchestration::tasks::inject_workspace_context()` → reads active workspace session via existing `nexus-daemon-runtime` workspace handlers. @@ -269,8 +269,8 @@ participating in WASM compute. Its semantics are: The flag is a filterable marker — the KB query layer (`KbQuery::with_computable(bool)`) can select only computable KnowledgeEntries -when building the invocation snapshot. This was implemented in V1.61 P1 -(`crates/nexus-kb/src/query.rs`, `InMemoryKbStore`, `SqliteKbStore`). +when building the invocation snapshot. The V1.61 P1 historical implementation +anchors were `crates/nexus-kb/src/query.rs`, `InMemoryKbStore`, and `SqliteKbStore`. ##### 5.5.9.2 `state` field @@ -292,7 +292,7 @@ to the KnowledgeEntry. Its shape is nested by `block_type` (compass V1.61 Q5): The nesting by `block_type` avoids field-name collisions when the same KnowledgeEntry is used by different module types. The `state` object is mutable — the host applies `state_delta` operations (`+/-/set`) from `ComputeOutput.state_delta` -(see [compute-module-abi.md](./compute-module-abi.md) §5.1). +(see [compute-module-abi.md](../compute/compute-module-abi.md) §5.1). The `state` field is carried in the KnowledgeEntry's `body_json` (TEXT column in SQLite). No separate DB column is required — the JSON is transparent to the @@ -331,23 +331,23 @@ schemas. V1.61 placed placeholder schemas under in V1.62 P0. Their content (per-`BlockType` shape declarations) is replaced by per-module JSON Schema fragments declared in each compute module's `manifest.json` `schemas` block (V1.62 P1; see -[compute-module-abi.md](./compute-module-abi.md) §7.3). +[compute-module-abi.md](../compute/compute-module-abi.md) §7.3). The structured validation mode is: -1. The `nexus-kb::validation` module provides `ValidationMode::Structured` - (added in V1.61 P1, `crates/nexus-kb/src/validation.rs`). This mode +1. The `nexus_knowledge::world_kb::validation` module provides `ValidationMode::Structured` + (introduced in V1.61 P1; current source: `crates/nexus-knowledge/src/world_kb/validation.rs`). This mode requires `computable: true` on KnowledgeEntries that carry `state`. 2. Per-module attribute/state shapes are declared in the module's `manifest.json` `schemas.key_block_attributes[block_type]` and `schemas.key_block_state[block_type]` blocks. 3. At compute invocation time, the host (`nexus-wasm-host`) validates each KnowledgeEntry in `ComputeInput.key_blocks` against the manifest-declared - schemas (see [wasm-host.md](./wasm-host.md) §8.5). + schemas (see [wasm-host.md](../compute/wasm-host.md) §8.5). 4. Validation failures produce `ComputeError::ManifestValidationFailed` with a JSON path to the offending field. -The `ValidationMode::Structured` variant in `nexus-kb` validates the +The `ValidationMode::Structured` variant in `nexus-knowledge` validates the computable flag and state field at the KB layer; the manifest-driven validation in `nexus-wasm-host` validates the **shapes** of those fields at compute time. Both layers are additive — KB validation ensures the @@ -371,7 +371,7 @@ Specs and code MUST NOT reference the deleted paths `schemas/compute/compute-entity-attributes.schema.json` or `schemas/compute/compute-entity-state.schema.json`. The canonical replacement is `manifest.json` `schemas` as documented in -[compute-module-abi.md](./compute-module-abi.md) §7.3. +[compute-module-abi.md](../compute/compute-module-abi.md) §7.3. | `nexus42` | CLI surface | Owns user-facing command routing and wording. It invokes the owning crates; it MUST NOT become a second domain implementation for scope rules. | @@ -390,9 +390,9 @@ replacement is `manifest.json` `schemas` as documented in #### 5.1.1 Narrative World KB item taxonomy (V1.40 grill-me locked — **Shipped V1.40 P1**) -The `nexus-knowledge` persistence model stores World-scoped KnowledgeEntries with `block_type`, `canonical_name`, `body`, provenance anchors, and active uniqueness under `(world_id, block_type, canonical_name)` (see [local-db-schema.md](./local-db-schema.md) §4.1.2). +The `nexus-knowledge` persistence model stores World-scoped KnowledgeEntries with `block_type`, `canonical_name`, `body`, provenance anchors, and active uniqueness under `(world_id, block_type, canonical_name)` (see [local-db-schema.md](../runtime/local-db-schema.md) §4.1.2). -**SSOT for `block_type` (wire enum):** `schemas/common/common.schema.json` → `BlockType` → `@42ch/nexus-contracts` / `nexus-contracts`. Shipped values (snake_case on wire): `character`, `ability`, `scene`, `organization`, `item`, `conflict`, `info_point`, `event`. Implementations MUST NOT introduce a parallel `block_type` enum in `nexus-knowledge` or orchestration presets. `kb-extract`, `SqliteKbStore`, and `assemble_moment` / `fetch_world_kb` already use this vocabulary. +**SSOT for `block_type` (wire enum):** `schemas/common/common.schema.json` → `BlockType` → `@42ch/nexus-contracts` / `nexus-contracts`. Current shipped values (snake_case on wire): `character`, `ability`, `scene`, `organization`, `item`, `conflict`, `info_point`, `event`, `species`, `faction`, `magic_system`, `technology`, `deity`, `level`, `economy_tier`, `dialogue`, `beat`, `act`, `era`. The eight-value V1.40 baseline was extended by the game-bible, script, and Brief-era additions documented below; `era` is the cross-profile Brief carrier in §§1.4.4–1.4.5. The generated patch wire enum is in `crates/nexus-contracts/src/generated/daemon_api/canvas/world_kb/world_kb_entity_patch.rs`. Implementations MUST NOT introduce a parallel `block_type` enum in `nexus-knowledge` or orchestration presets. `kb-extract`, `SqliteKbStore`, and `assemble_moment` / `fetch_world_kb` already use this vocabulary. **Design decision: `environment` NOT in `BlockType` (R-V161P0-INFO-001).** The V1.61 compass initially named `environment` as a potential computable BlockType for environmental context (weather, terrain, lighting). After evaluation, `environment` was intentionally excluded from the wire enum: @@ -404,7 +404,7 @@ Module authors should use the `scene` + `info_point` BlockType combination to mo **Novel profile semantics (body layer):** The V1.37 novel "seven categories" (`foundation`, `background`, `character`, `location`, `society`, `rules`, `economy`) are carried in `KnowledgeEntry.body.attributes.novel_category` (string) plus type-specific fields in `body.attributes` / `body.summary`. They do **not** replace wire `block_type`. -**V1.40 P1 implementation:** `nexus-kb::validation` module provides `validate_body(block_type, body, ValidationMode)` that enforces `novel_category` presence and validity when `ValidationMode::Novel` is active. Both `InMemoryKbStore` and `SqliteKbStore` run validation on insert/update. Validation errors are structured (`ValidationKind` enum) so callers can produce precise diagnostics without string matching. `canonical_name` is validated for format/safety (no control chars, path separators, shell metacharacters, max 256 chars). Advisory warnings for `novel_category` ↔ `block_type` mismatch are emitted via `tracing::warn!`. See `crates/nexus-kb/src/validation.rs`. +**V1.40 P1 validation (current owner):** `nexus_knowledge::world_kb::validation` provides `validate_body(block_type, body, ValidationMode)` that enforces `novel_category` presence and validity when `ValidationMode::Novel` is active. Both `InMemoryKbStore` and `SqliteKbStore` run validation on insert/update. Validation errors are structured (`ValidationKind` enum) so callers can produce precise diagnostics without string matching. `canonical_name` is validated for format/safety (no control chars, path separators, shell metacharacters, max 256 chars). Advisory warnings for `novel_category` ↔ `block_type` mismatch are emitted via `tracing::warn!`. See `crates/nexus-knowledge/src/world_kb/validation.rs`. **`canonical_name` grammar (V1.40 P1):** `[^\x00-\x1F\x7F/\\`$;&|> **Status**: Normative (V1.160 Review & Edit chain, architect pass 2) — closes the entity-create half of `R-V1159P1-001`. Documents the carrier that the World Timeline Brief 「新建 era」 affordance ([`canvas-strategy-surface.md`](canvas-strategy-surface.md) §3.3.3 "Create entry") drives. `wire_contracts_changed: false`: the route, request DTO, response DTO, and success status are unchanged from V1.73; create-on-absent is an internal handler branch, not a new wire contract. +> **Status**: Normative (V1.160 Review & Edit chain, architect pass 2) — closes the entity-create half of `R-V1159P1-001`. Documents the carrier that the World Timeline Brief 「新建 era」 affordance ([`canvas-strategy-surface.md`](../surfaces/canvas-strategy-surface.md) §3.3.3 "Create entry") drives. `wire_contracts_changed: false`: the route, request DTO, response DTO, and success status are unchanged from V1.73; create-on-absent is an internal handler branch, not a new wire contract. `POST /v1/daemon/worlds/{world_id}/kb/patch-entity` (`kb.patch_entity`, V1.73) is the sole author-facing World KB entity write surface. V1.160 makes it a true **create-or-update** handler by branching on the store read result instead of failing on absent entities (pre-V1.160 the handler mapped `NotFound` → 500). No new route, no DTO rename, no `upsert` re-branding — the wire name stays `patch-entity`. @@ -612,7 +612,7 @@ Minimum common `body` shape for script items: **Conflict / validation policy (normative).** Reuses the shipped error family — no new error code: **403** foreign world; **404** cross-world entity (Found); **409** `WorldKbConflictError` (OCC stale, create-on-existing, update-on-absent); **422** `WorldKbValidationError` (missing create fields, terminal status, body / canonical-name validation); **500** genuine storage error. -**Cross-reference.** Frontend create affordance contract: [`canvas-strategy-surface.md`](canvas-strategy-surface.md) §3.3.3 "Create entry" (V1.159). Orchestrator create path + tests: `orchestrate_upsert` → `put_create` (`knowledge_entry_port.rs`), `orchestrate_upsert_happy_create` / `orchestrate_upsert_happy_create_path`. +**Cross-reference.** Frontend create affordance contract: [`canvas-strategy-surface.md`](../surfaces/canvas-strategy-surface.md) §3.3.3 "Create entry" (V1.159). Orchestrator create path + tests: `orchestrate_upsert` → `put_create` (`knowledge_entry_port.rs`), `orchestrate_upsert_happy_create` / `orchestrate_upsert_happy_create_path`. ### 5.2 `nexus-knowledge` — two-tier knowledge (World + User) @@ -642,7 +642,7 @@ The term `KB` MUST be qualified in architecture/spec text when ambiguity matters > **Status**: Normative (V1.50) — V1.50 T-B P1 shipped on 2026-06-18. Migration `202606180002_kb_extract_jobs.sql` landed; review-time extraction hook verified end-to-end; promotion row promoted Draft → Normative at V1.50 P-last. > **Plan**: -> **Cross-refs**: [workflow-profile.md §11.5](novel-writing/workflow-profile.md#115-auto-chronology-per-work-opt-in) — auto-advance logs auto-promotion status; [quality-loop.md §3](novel-writing/quality-loop.md) — review-time extraction hook. +> **Cross-refs**: [workflow-profile.md §11.5](../novel-writing/workflow-profile.md#115-auto-chronology-per-work-opt-in) — auto-advance logs auto-promotion status; [quality-loop.md §3](../novel-writing/quality-loop.md) — review-time extraction hook. World KB rows enter the World through a **promotion state machine** governed by `kb_extract_jobs.status` and the World-scoped KnowledgeEntries (`nexus-knowledge` storage, see §5.1.1). @@ -678,7 +678,7 @@ Invalid transitions return `422` with stable error code on Daemon API. Rejected promotion candidates are retained in `Logs/kb/rejected/-.md` for audit. Retention is **indefinite** by default (no TTL); future iterations may add a `--prune-rejected` CLI — **durable roadmap:** DR-18 (`creator world kb` rejected-candidate `--prune-rejected`). -#### 5.5.5 Relationship to existing `nexus-kb` taxonomy +#### 5.5.5 Relationship to existing World KB taxonomy The promotion state machine does **not** change the `BlockType` enum (see §5.1.1 SSOT) or the `ValidationMode` constraints (see V1.40 P1 validation module). It governs **how** a row enters the World, not **what** the row contains. @@ -688,7 +688,7 @@ V1.51 T-A P0 closes `R-V150KBED-01`. The V1.50 heuristic defaulted every review-time candidate to `block_type_guess='character'` (capitalized noun phrase), forcing authors to correct the type on adopt for every non-character entity. V1.51 replaces the heuristic with the `nexus.llm.extract` capability -(see [llm-extract.md](llm-extract.md)) at the review-time extraction hook. +(see [llm-extract.md](../orchestration/llm-extract.md)) at the review-time extraction hook. The state machine in §5.5.1–§5.5.2 is **unchanged** — LLM extraction only improves the *quality* of the `block_type_guess` + `canonical_name_guess` @@ -836,7 +836,7 @@ User scope. ### 6.3 User knowledge → World KB Promoting User knowledge into a World creates or updates a World-scoped narrative KB -asset through `nexus-kb`/`nexus-narrative`. The promoted World KB asset MUST carry +asset through `nexus-knowledge`/`nexus-narrative`. The promoted World KB asset MUST carry source/anchor provenance back to the User knowledge material when available. The source material remains User-scoped. @@ -858,6 +858,8 @@ alternate histories, or rewrites use Fork semantics; they do not mutate prior Ev records in place. There are two distinct fork kinds, and the boundary between them is normative. +**Domain vs local persistence.** `nexus-narrative` owns the narrative fork models (`crates/nexus-narrative/src/world.rs`, `crates/nexus-narrative/src/fork_branch.rs`), not a promise that local world-copy fork fields are populated. `CoreService::create_fork` (`crates/nexus-core/src/forks.rs`) creates the local branch marker; `crates/nexus-local-db/src/narrative_gateway.rs` reads its timeline metadata while leaving the separate world-level fork projection unset. + #### 6.6.1 Local authoring fork (in-scope; local surface) A **local authoring fork** is a single creator branching the timeline of a world they @@ -902,7 +904,7 @@ Because a local fork is a branch within a world (not a forked world), fork linea - `parent_branch_id` — the branch this fork diverged from (drives one-hop return-to-parent). - `forked_from_event_id` — the fork-point event on the parent branch. - `label` (optional) — the human-readable label given at create. -- **World-level `WorldState` fork fields** (`is_fork`, `fork_branch_id`, `parent_world_id`, `forked_from_event_id`) describe the platform world-copy fork model (§6.6.2); they are NOT the carrier for local branch lineage and are NOT populated for local forks on the SQLite read path. Compute branch derivation reads `WorldState.fork_branch_id` as the world's current branch — that world-level semantic is unchanged by V1.162. +- **World-level `WorldState` fork fields** (`is_fork`, `fork_branch_id`, `parent_world_id`, `forked_from_event_id`) describe the platform world-copy fork model (§6.6.2); they are NOT the carrier for local branch lineage. `WorldRow::to_world_state` in `crates/nexus-local-db/src/narrative_gateway.rs` explicitly returns `is_fork: false` and `None` for the other three fields, even when local fork markers exist. Local `is_fork` / `parent_branch_id` / `forked_from_event_id` lineage must therefore come from the branch marker, not from populated world-fork columns. Compute's interpretation of `WorldState.fork_branch_id` is a separate world-level semantic and does not make that field a local lineage carrier. - **No spoke dependence.** The nexus-local lineage projection is independent of spoke round-trip fidelity (DR-44 stays deferred); lineage is read from the local `narrative_timeline_events` marker, never reconstructed from a spoke round-trip. ### 6.7 Creator/User pairing @@ -918,13 +920,15 @@ Cloud transport may synchronize or fetch representations of multiple scopes, but does not own their domain invariants. In particular: - User/Pairing invariants go through `nexus-cloud-domain`. -- Narrative World/Timeline/Event/KB invariants go through `nexus-narrative` and `nexus-kb`. +- Narrative World/Timeline/Event/KB invariants go through `nexus-narrative` and `nexus-knowledge`. - Moment assembly remains `nexus-moment-context-assembly`; optional cloud Stage-1 is an input source, not a replacement owner. --- ## 7. Wiring implications for V1.23 +> **Historical V1.23 wiring snapshot.** The former `nexus-kb` and separate User-only `nexus-knowledge` responsibilities below describe that version, not current crate ownership. Current World/User knowledge ownership is in §4 and §5.2. + 1. `nexus-moment-context-assembly` target wiring should aggregate local `nexus-creator-memory`, `nexus-narrative`, `nexus-kb`, and `nexus-knowledge` inputs for Stage-0 moment context. 2. `nexus-narrative` is the core entry point for creative-work narrative state and should be the natural owner for World/Timeline/Event queries consumed by context assembly and CLI/daemon local APIs. 3. `nexus-knowledge` must be described and wired as User-scoped global knowledge, not Creator-scoped knowledge. diff --git a/.mstar/specs/holder-governance.md b/.mstar/specs/architecture/holder-governance.md similarity index 99% rename from .mstar/specs/holder-governance.md rename to .mstar/specs/architecture/holder-governance.md index 957cdc6ae..c44519b5d 100644 --- a/.mstar/specs/holder-governance.md +++ b/.mstar/specs/architecture/holder-governance.md @@ -2,7 +2,7 @@ > **Status:** Shipped (v1.191 P1) — implemented and exercised on the v1.191 plan branch (`feat/v1.191-p1-spoke-0-13-adoption`) and **merged to `main`** in the v1.191 iteration PR (`ee23ec47c`, #325); the registry (`crates/nexus-local-db/src/holders.rs`, `knowledge_holders`) is shipped current state. Current SPOKE pins are the pinned upstream lockstep release recorded in the workspace manifests (D17). Per-row acceptance evidence lives in the plan's own task reports (harness-process paths, deliberately not linked from a tracked doc). > **Document class:** Draft overlay, sole technical authority for Actor holders and their disclosure policy. -> **Related:** [actor-product-model.md](actor-product-model.md), [spoke-adapter-architecture.md](spoke-adapter-architecture.md), [local-db-schema.md](local-db-schema.md), [rust-core-service-boundary.md](rust-core-service-boundary.md). +> **Related:** [actor-product-model.md](actor-product-model.md), [spoke-adapter-architecture.md](spoke-adapter-architecture.md), [local-db-schema.md](../runtime/local-db-schema.md), [rust-core-service-boundary.md](rust-core-service-boundary.md). ## 1. Independent identity axes diff --git a/.mstar/specs/local-runtime-boundary.md b/.mstar/specs/architecture/local-runtime-boundary.md similarity index 75% rename from .mstar/specs/local-runtime-boundary.md rename to .mstar/specs/architecture/local-runtime-boundary.md index c603722f1..4a43b9f9a 100644 --- a/.mstar/specs/local-runtime-boundary.md +++ b/.mstar/specs/architecture/local-runtime-boundary.md @@ -1,13 +1,15 @@ # Nexus Local Runtime Boundary -**Status**: Normative +**Status**: Normative for retained wire/ACP boundaries; daemon host-process sections are historical (retired in v1.193 P2) **Document class**: Master ## 0. Document position +> **Retired daemon host model (v1.193 P2).** The `nexus-daemon-runtime` crate and integrated `nexus42 daemon` process mode are deleted. Retained `/v1/daemon/*` wire families are served by the standalone TypeScript service, `apps/nexus-service`, over `nexus-core`; Electron owns the app-managed service lifecycle and is the desktop host since v1.192. An independently owned service may be attached without transferring ownership to the app. The Connect host is `nexus-runtime`, an independent bin of `apps/nexus42`, not a daemon mode. Current topology authority: [rust-core-service-boundary.md](rust-core-service-boundary.md); desktop lifecycle: [desktop-shell.md](../surfaces/desktop-shell.md). The original scope outline below and explicitly marked process sections remain historical, not setup instructions. + This document defines boundaries between: -- `nexus42` CLI（产品名 Nexus；见 [`cli-spec.md`](./cli-spec.md) §0.1） +- `nexus42` CLI（产品名 Nexus；见 [`cli-spec.md`](../cli/cli-spec.md) §0.1） - daemon runtime mode (single-binary `nexus42`) - Nexus Daemon API / IPC - ACP sessions @@ -15,7 +17,7 @@ This document defines boundaries between: It preserves the ACP client-only topology from nexus-platform `v1-spec/architecture.md` §6.2.1 and the single-binary daemon runtime boundary (see nexus-platform `v1-spec/adr/adr-026-single-binary-daemon-runtime-and-hybrid-agent-host.md`). -ACP Registry 默认上游索引与仓库入口见 [`registry-integration.md`](./registry-integration.md) §0.1。 +ACP Registry 默认上游索引与仓库入口见 [`registry-integration.md`](../agents/registry-integration.md) §0.1。 Logical `nexus.*` capabilities are shared with platform-hosted creators; this document only defines the **local** runtime boundary, not a separate capability model. @@ -23,6 +25,8 @@ Logical `nexus.*` capabilities are shared with platform-hosted creators; this do ## 1. Frozen topology recap +> **Historical topology.** The daemon process and CLI↔daemon link below are retired. The ACP client-only invariant survives; current hosts are identified in §0. + | Component | ACP role | Notes | | --- | --- | --- | | User-owned agent | **ACP Agent** | Hosts tools/resources; executes model calls | @@ -34,6 +38,8 @@ Logical `nexus.*` capabilities are shared with platform-hosted creators; this do ## 2. Process model +> **Historical process composition (§2.1–§2.3).** The single-binary daemon mode and its managed-host placement below describe the deleted host, not the current CLI or Electron lifecycle. The retained CLI calls Rust core/cloud/Connect directly; the TS/native service composes the Rust execution and provider owners ([rust-core-service-boundary.md](rust-core-service-boundary.md) §§4–5). + ### 2.1 One-shot CLI Examples: `auth`, `doctor`, `sync pull`, `config` @@ -49,7 +55,7 @@ Owns: - Long-lived agent session supervision - Local IPC listener -Does **not** own platform sync or registration (see [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md)). +Does **not** own platform sync or registration (see [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md)). Does not own: @@ -70,6 +76,8 @@ Daemon runtime hosts agent sessions through a managed host subsystem with these ### 3.1 Why Daemon API exists +> **Historical motivation.** The CLI↔daemon use case below is no longer a supported CLI dependency; browser/Electron retain the HTTP wire families through the TS service. + ACP is for agent integration. Nexus still needs a stable internal interface for: - CLI talking to daemon without spawning agents @@ -77,18 +85,22 @@ ACP is for agent integration. Nexus still needs a stable internal interface for: ### 3.2 Daemon API characteristics +Here “Daemon API” names the retained wire namespace, not the retired Rust process. Exact current route identities and auth tiers come from `apps/nexus-service/src/routes.ts` and its family modules; the inventory below preserves its historical release annotations. + - Loopback-only by default -- Minimal surface: workspace status, daemon health, orchestration/agent-host, local KB/memory — **no** sync or platform registration proxy (see [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md)) +- Minimal surface: workspace status, daemon health, orchestration/agent-host, local KB/memory — **no** sync or platform registration proxy (see [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md)) - Auth: OS user boundary, with optional token / IPC artifacts under **`$HOME/.nexus42/run/`** (or workspace-scoped subpaths still rooted at `$HOME/.nexus42/`, never under `/`) - Versioned schema: all stable endpoints live under `/v1/daemon/*` so TS / Rust codegen can share one contract ### 3.2.1 Daemon API endpoint families -The Daemon API is the **codegen-ready** internal contract between CLI, daemon, and local automation. +The retained Daemon API is the **codegen-ready** HTTP contract for browser/Electron clients of `apps/nexus-service`; it is not a CLI dependency or evidence that the deleted Rust daemon still runs. -**Routing policy (long-term):** [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md) §5. **Removal acceptance:** v1.21 delivery compass. +**Current ownership:** `apps/nexus-service/src/routes.ts` composes the endpoint families and owns runtime health/status HTTP projections. `actors.ts`, `memory.ts`, `context.ts`, `presets.ts`, `works.ts`, and the World/knowledge family modules translate requests to the native facade over `nexus-core`; Rust owns stored-principal authorization and domain/storage effects. `execution.ts` and `workflow-observation.ts` expose the core execution owner, while `routes.ts`/`provider.ts` adapt the retained Agent-Host/provider surface. Current topology and qualification status: [rust-core-service-boundary.md](rust-core-service-boundary.md) §§4, 7.5. -| Endpoint / family | Status on daemon | Notes | +> **Historical endpoint inventory.** The exact inventory below is retained from the Rust-host record. “Active” means active in that record, not that every legacy identity is mounted today. Retained identities are served only when registered in the TS route composer; old `api/mod.rs`/`orchestration_routes()` references and daemon restart wording below are historical. Do not infer current support from these annotations or restore retired `/v1/local/*` routes. + +| Endpoint / family | Recorded status (historical Rust host) | Notes | | --- | --- | --- | | `GET /v1/daemon/runtime/health` | Active | Unguarded liveness route. | | `GET /v1/daemon/runtime/status` | Active | Unguarded diagnostic route. | @@ -141,7 +153,7 @@ Rules: - `request_id` is caller-generated and traceable in logs - `workspace_id` is mandatory for workspace-scoped actions - `error_code` should align with sync / conflict schemas where applicable -- Research-specific routes may use the `/v1/daemon/*` namespace only after they are registered in the daemon router. +- Research-specific routes may use the `/v1/daemon/*` namespace only after they are registered in the TS-service route composer. - **V1.24 KCA-002 B2:** `POST /v1/local/context/assemble` is retired from the Daemon API. CLI/platform context assembly should call `nexus-moment-context-assembly` in-process rather than proxying through the daemon. - **V1.2**：若请求体支持可选 **`as_of`**，Local 与 Platform HTTP **须**共享 **同一**字段语义与校验；不得仅在一侧出现私有历史参数。 @@ -153,6 +165,8 @@ Rules: ### 3.4 Relationship diagram +> **Historical relationship diagram (retired host).** The daemon IPC/`DaemonClient` path below was deleted in v1.193 P2. Current CLI/core, browser/TS-service, and Connect boundaries are in [rust-core-service-boundary.md](rust-core-service-boundary.md). + ```text CLI --Daemon API--> daemon runtime mode --ACP Client--> ACP Agent | @@ -241,6 +255,8 @@ V1.53 cancelled the skills-export CLI/spec line (DF-50). Nexus keeps the static ## 7. Operational boundaries +> **Historical path table.** Daemon health through the CLI below is retired; current HTTP health belongs to `apps/nexus-service`, desktop lifecycle belongs to Electron, and the one-shot CLI does not launch or status that service. + | Action | Preferred path | | --- | --- | | Agent reasons & writes manuscript via tools | ACP session | @@ -253,6 +269,8 @@ V1.53 cancelled the skills-export CLI/spec line (DF-50). Nexus keeps the static ## 8. Open items +> **Historical open questions.** These are the original daemon-model questions, not an instruction to recreate that host. Current service transport/lifecycle authority is [rust-core-service-boundary.md §8.1](rust-core-service-boundary.md#81-independent-service-launch-and-attach). + - Whether loopback TCP is allowed on shared machines - Multi-workspace daemon strategy vs one-daemon-multi-workspace - Whether the frozen `/v1/daemon/*` envelope should be JSON-over-HTTP only or also mirrored on unix socket RPC @@ -261,6 +279,8 @@ V1.53 cancelled the skills-export CLI/spec line (DF-50). Nexus keeps the static ## V1.57 P1 Draft overlay: 3-caller adapter topology +> **Historical draft overlay (host retired in v1.193 P2).** The original V1.57 draft status and diagram below are preserved as history. `host-call`, daemon IPC, and the daemon-runtime registry placement are not current entrances; retained tool/execution authority is composed through the Rust core/native and TS-service owners. + **Status**: Draft (V1.57 P1) ### Updated topology diagram diff --git a/.mstar/specs/rust-core-service-boundary.md b/.mstar/specs/architecture/rust-core-service-boundary.md similarity index 86% rename from .mstar/specs/rust-core-service-boundary.md rename to .mstar/specs/architecture/rust-core-service-boundary.md index 78d2f066d..e19615ada 100644 --- a/.mstar/specs/rust-core-service-boundary.md +++ b/.mstar/specs/architecture/rust-core-service-boundary.md @@ -3,7 +3,7 @@ **Status:** Accepted target — locked 2026-09-13; **v1.193 overlay delivered (P2 complete 2026-09-21).** The **M1 subset is exercised** (v1.189 PR #306, merge `71e01cf9`, 2026-09-15). **v1.192** delivered the Electron desktop cutover and retired Tauri. **v1.193 P2 delivered the remaining cutover:** the whole `nexus42 daemon` group, hidden `daemon-run`, Model A `mcp serve`/`host-call`, the app-only `legacy-cli` / `basic-cli` / `web-embed` / `connect-client` / `embedded-mcp` selectors, the `nexus-daemon-runtime` crate and the DaemonClient CLI leaves are **deleted** — retained leaves call core/cloud/Connect directly, with no TS-launcher alias and no permanent legacy fallback. This document is normative for that boundary and is self-contained; the per-leaf command inventory for the iteration is process material, not a tracked contract. Do **not** describe the `Current:` records below as the shipped state — they are the pre-cutover migration record. **Document class:** Master **Pillar (V1.122):** Cross-cutting — Harness, Canvas, and Computable consumption ends keep their product identities; this spec only locks the service-boundary target those pillars run on. -**Coordinates with:** [local-runtime-boundary.md](local-runtime-boundary.md), [daemon-runtime.md](daemon-runtime.md) (historical host spec — its crate was deleted in v1.193 P2), [cli-spec.md](cli-spec.md), [desktop-shell.md](desktop-shell.md), [web-ui.md](web-ui.md), [agent-host.md](agent-host.md), [concurrency.md](concurrency.md), [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md), [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md), [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md), [schemas-directory-layout.md](schemas-directory-layout.md) +**Coordinates with:** [local-runtime-boundary.md](local-runtime-boundary.md), [daemon-runtime.md](../archived/daemon-runtime.md) (historical host spec — its crate was deleted in v1.193 P2), [cli-spec.md](../cli/cli-spec.md), [desktop-shell.md](../surfaces/desktop-shell.md), [web-ui.md](../surfaces/web-ui.md), [agent-host.md](../agents/agent-host.md), [concurrency.md](../runtime/concurrency.md), [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md), [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md), [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md), [schemas-directory-layout.md](schemas-directory-layout.md) ## 0. Authority @@ -15,12 +15,14 @@ | **Wire DTOs** | `schemas/` → generated Rust + `@42ch/nexus-contracts` | Unchanged by this lock | | **Product names** | Root `AGENTS.md` | `Nexus`, `nexus42`, `nexus-runtime`, `@42ch` — the retired integrated daemon runtime is no longer a product name | -**Activation rule:** a family uses the target topology only after the extracted Rust service is the single effect owner **and** the old mixed-handler path for that family has an explicit deletion owner and proof. **Delivered (v1.193 P2):** that gate fired for every retained family — the old mixed-handler path is the deleted daemon/SPA composition, so no shipped Master still describes an implementable daemon topology, and the retained SSOT is this document plus `cli-spec`, `desktop-shell` and the TS service. What has *not* been exercised is the rest of the program: the RFT-05–11 destinations listed in §7.5 (complete TS API, remaining World/Work families, Actor families) remain open, apart from the retained public first-run half of RFT-11 that v1.195 P3 exercises (§7.5.1). Do not describe an unexercised destination as delivered, and do not describe the M1 subset as the complete program. +**Activation rule:** a family uses the target topology only after the extracted Rust service is the single effect owner **and** the old mixed-handler path for that family has an explicit deletion owner and proof. **Delivered (v1.193 P2):** that gate fired for every retained family — the old mixed-handler path is the deleted daemon/SPA composition, so no shipped Master still describes an implementable daemon topology, and the retained SSOT is this document plus `cli-spec`, `desktop-shell` and the TS service. **Implementation is not product qualification:** the RFT-05–07 route families are implemented and exercised through the TS service and Rust core (§7.5); outstanding product acceptance/QA and Run Studio completeness must not be reported as missing or wholly unexercised routes. RFT-10 distribution qualification and RFT-11 first-run qualification remain distinct obligations (§7.5.1). Neither the M1 subset nor subsequent route-level exercise alone proves the complete program. Historical 2026-09-12 research (source baseline `3bb262b`) is advisory structure only. It is not runtime proof, a measurement, or this spec's authority. The merged v1.189 record for the exercised M1 subset is `71e01cf9e1a8c64cb68062ac9a08762e2156a925` (PR #306); the baseline has since advanced — v1.192 (RFT-09 cutover + unsigned packaging) and v1.193 P2 (obsolete-host retirement) are **merged on `main`**, so the retained `cli`/`connect-host` cohorts and the Electron host are shipped current state, not target state. Inherited v1.188 reliability remains `bbaae32d422b673576d683859b474da6bd787743`. ## 1. Problem +> **Historical problem statement (before the v1.193 P2 cutover).** The mixed daemon-handler/HTTP-client topology below is retired; current identities and ownership are in §§0, 2, and 4. + Operators and authors already have three consumption ends. The local stack that serves them mixes: - authorized domain reads/writes, OCC/CAS, storage, and recovery inside daemon HTTP handlers and `WorkspaceState` @@ -51,6 +53,19 @@ These names and roles stay. The refactor does not invent a second CLI, a second | Content creators | `apps/web` + desktop shell wrapping the same SPA | No visual redesign. Browser uses generated `NexusClient`. The desktop host cut over to Electron in v1.192 (RFT-09 accepted) and stays exactly one desktop host. | | Third-party users | `nexus-runtime` + Connect | Keep the existing Connect-only served-op profile. No first-party player. | +### Current workspace boundary inventory + +These six workspace crates extend the frozen 2026-05 inventory in [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md); they support the authority graph in §4.2, not another product or host. Membership is declared in root `Cargo.toml`; the linked per-crate `AGENTS.md` files own their detailed rules. + +| Workspace crate | Boundary role | +| --- | --- | +| [`nexus-core`](../../../crates/nexus-core/AGENTS.md) | Owned transport-neutral World KB service and stored Actor/holder admission authority; no transport or SQL pool in its public domain surface. | +| [`nexus-core-node`](../../../crates/nexus-core-node/AGENTS.md) | Thin Node-API cdylib composing core and provider ports, with environment-local state and an audited FFI boundary. | +| [`nexus-preset`](../../../crates/nexus-preset/AGENTS.md) | Pure preset authoring/source-file domain library shared by core and orchestration; no execution, Host, WASM, HTTP, or database dependency. | +| [`nexus-provider-conformance`](../../../crates/nexus-provider-conformance/AGENTS.md) | Provider-neutral normalized `HostEvent` stream conformance runner; CI/test-only, not wired into product binaries. | +| [`nexus-provider-ports`](../../../crates/nexus-provider-ports/AGENTS.md) | Port-only `ProviderPort`/`ProviderResult` contracts; no Host, SDK, SQL, napi, or orchestration implementation. | +| [`nexus-storage-guard`](../../../crates/nexus-storage-guard/AGENTS.md) | Audited SQLite FFI boundary installing connection-local writer-protocol functions; no business SQL or independent pool. | + ## 3. Topology before the v1.193 cutover (migration record) **Historical record.** The numbered items below describe the mixed shipped @@ -75,6 +90,8 @@ Kept as the record of the mix at lock time; nothing below is a supported instruc ## 4. Target topology +> **Migration edge only:** “Old HTTP adapter” in the frozen target diagram and temporary-adapter rule below describes the cutover path, not a surviving host. That adapter and `nexus-daemon-runtime` were deleted in v1.193 P2; browser/Electron now reach core through the standalone TS/native service. + ```text Basic Rust CLI ──────┐ Connect-only host ───┼──> nexus-core ──> guarded SQLite / canonical spoke ports @@ -128,6 +145,8 @@ These are the shipped dependency cohorts (v1.193 P2 delivered them), kept as the | Connect-only runtime (`connect-host`, no defaults) | Existing stored-Actor invoke authority and spoke-connect/libp2p; explicit spoke-adapter `compute` preserves WASM/module-cache behavior | CLI-only ACP/agent-host, orchestration scheduler, SPA/HTTP/Node; `connect-host` must not imply `cli` | | TS native service | Current selection on `main` is core `[execution]` with native-owned Host/ProviderPort. The v1.195 current-host completion selects `[execution,provider-host,compute]` and composes existing Rust owners: the workflow-control, observation/recovery and Compute whole-plan releases are accepted, and P3 adds the exercised public first workflow. Completing it is not merely changing the feature list, and the P3 driver/guidance stay pending plan QC/QA and iteration integration (§7.5.1). | old-daemon proxy, TS domain/SQL owner, duplicate engine/Host/WASM runtime; domain/default and Connect-only cohorts must not inherit native-service startup | +> **Historical row wording.** The TS native service row retains its v1.193 selection / v1.195 opening target; current route implementation and qualification are in §7.5. + The existing pure `nexus-preset` closure and default-disabled MCA/core spoke edges are retained. The app's spoke dependency also disables defaults; only `connect-host` explicitly enables its real compute feature. Current Connect invoke code already serves compute with stored holder/module scope and a shared cache; removing WASM to satisfy a graph slogan would delete supported functionality. The ordinary CLI may retain orchestration **library** edges for chronology/cron/ops without starting an engine. Core domain closure remains engine/Host/WASM-free. **Delivered (v1.193 P2).** The app cohorts are `default = ["cli"]`, independent `connect-host`, and `nexus42` binary `required-features = ["cli"]`. `basic-cli`, `legacy-cli`, `web-embed` and the app-only `connect-client`/`embedded-mcp` selectors are deleted; the core `connect-client`/`embedded-mcp` **library** features remain. The ACP factory that prescribed `nexus42 mcp serve` is deleted; generic ACP MCP descriptors remain. No second CLI, renamed legacy mode or no-op compatibility feature was introduced. @@ -136,6 +155,8 @@ The existing pure `nexus-preset` closure and default-disabled MCA/core spoke edg `CoreService::start_execution(&self, _providers: Arc, mut deps: RunnerDeps) -> Result, ExecutionOpenError>` requires EngineOwner and preserves typed ownership/closing errors. Production prompt/tool/workspace dependencies must be supplied; default dependencies are not execution parity. Domain open starts no scheduler or Host. CoreService remains bound to the selected Creator/workspace generation; selection changes require reopen. Direct CLI adapters obtain a stored Principal, call typed family methods, and await close on success and failure without pool escape hatches or JSON dispatch. +> **Historical cutover instructions / v1.195 opening target (next three paragraphs).** Preserve their original “route-not-migrated” / “not yet delivered” wording as the starting record, not today's route availability. Workflow control, same-run observation, and Compute are implemented and exercised; current support limits and outstanding product qualification are in §7.5–§7.5.1. + Retire CLI `creator run`, `bootstrap`, Work `intake`/`resume-chain`, `preset run`, Character `run`/`soul reflect`, reference refresh, compute run and old runtime catalog/tool entrances where the complete direct production/observation closure does not exist. Preserve underlying Work/execution/Host/capture/SOUL/reference/compute libraries. `resume_driven_sessions` is not Work auto-chain; HostHandle query does not supply the Character CLI capture stream. Existing TS schedule add/signal and provider routes are not claimed as equivalent workflow replacements; TS compute run is currently route-not-migrated and forced native SOUL reflection has no synthesizer. **Current target (v1.195, not yet delivered):** complete retained workflow admission/list/inspect/context/control, same-run bounded observation/restart, and first-party Compute discovery/run/review/history/terminal-clear through the existing execution or compute owner. One Rust-owned production composition binds the admitted Creator/canonical workspace, real Host prompt/catalog, scheduler starter, workspace-intent recovery and conditionally shared WASM engine/cache/serializer before readiness. Public workflow events use durable root ownership and the existing epoch-based run rings, not Host identity. Context append precedes resume; cancellation success requires durable confirmed settlement, not provider acknowledgement. This target does not restore retired CLI entrances or alter SPOKE/version pins. @@ -180,6 +201,8 @@ Selected M2 composition reuses actual maintained adapters: TS ACP uses `packages **Destination:** daemon-free, Node-free, full-engine-free product cohort completed in **RFT-08**. **Delivered (v1.193 P2):** the ordinary default authoring/storage entries are this cohort (`default = ["cli"]`, `nexus42` bin `required-features = ["cli"]`); M1 delivered **one real slice** of it, and it is not the whole basic CLI. +> **Historical M1 planning record below (§7.1).** The HTTP transports, daemon-mediated Works reads, leaf counts, and remaining-family assignments describe the M1 baseline and its planned expansion, not current CLI dependencies. The delivered direct-core CLI disposition above supersedes those transport claims; current RFT-05–07 implementation/qualification is in §7.5. + **M1 first slice (RFT-01) — delivered in v1.189:** | Operator action | Current public command | Current transport | Target | @@ -229,32 +252,35 @@ RFT-00–04 shipped together as milestone **RFT-M1** (v1.189). RFT-05–08 are o | RFT-02 | napi adapter, provider ports, ACP LocalSet lifecycle | Shipped (v1.189) | | RFT-03 | Native npm + packaged Electron **development** feasibility go/no-go | Shipped development GO (v1.189). Production signing is RFT-10 | | RFT-04 | Standalone TS service + browser vertical of the M1 slice | Shipped (v1.189). Complete TS API is RFT-07 | -| RFT-05 | Remaining World/Work/KB/narrative/fork families, including Works reads/writes beyond the M1 slice | M2 / not started | -| RFT-06 | Actor/Character/admission/memory/context | M2 / not started | -| RFT-07 | Execution/scheduler/Host/providers/capabilities/MCP/Connect control plane **and** complete TS API/default service entry | M2 / not started | -| RFT-08 | Complete independent Rust CLI + headless product cutover (default authoring entry; Connect-only runtime). **v1.193 target:** no CLI operator control surface for the TS service | **Delivered (v1.193 P2)** — the ordinary `cli` cohort is the default authoring entry, `nexus-runtime` is the Connect-only headless binary, and no CLI operator control surface for the TS service exists. The unexercised destinations above stay open | +| RFT-05 | Remaining World/Work/KB/narrative/fork families, including Works reads/writes beyond the M1 slice | **Implemented and exercised family paths** in `apps/nexus-service` (`works.ts`, `world-kb.ts`, World/content/knowledge modules) over `nexus-core`. Not “M2 / not started”; product-wide acceptance/QA is not established by route-level exercise alone. | +| RFT-06 | Actor/Character/admission/memory/context | **Implemented and exercised family paths** in `apps/nexus-service` (`actors.ts`, `memory.ts`, `context.ts`) over the core admission/domain owners. Product acceptance/QA remains a separate qualification, not an implementation-absence claim. | +| RFT-07 | Execution/scheduler/Host/providers/capabilities/MCP/Connect control plane **and** complete TS API/default service entry | **Implemented and exercised retained route families**, including `execution.ts`, `workflow-observation.ts`, and `compute.ts`, over core execution/Compute owners. Default host cutover is delivered (v1.193 P2); outstanding product acceptance/QA, Run Studio completeness, and specific unmounted identities (§7.5.1) do not mean the service is unstarted or wholly unexercised. | +| RFT-08 | Complete independent Rust CLI + headless product cutover (default authoring entry; Connect-only runtime). **v1.193 target:** no CLI operator control surface for the TS service | **Delivered (v1.193 P2)** — the ordinary `cli` cohort is the default authoring entry, `nexus-runtime` is the Connect-only headless binary, and no CLI operator control surface for the TS service exists. The distinct product-qualification obligations above remain open. | | RFT-09 | Formal desktop cutover (Electron host after the M1 development GO; reuse web/Studio; no visual redesign) | M3 / **delivered in v1.192** (accepted) | | RFT-10 | Production distribution / Developer ID signing / notarization / stapling | M3. **v1.192 delivers the unsigned half** (`.app` and `.dmg`, both macOS architectures, no Apple credentials required); that delivery is not dual-architecture GUI qualification. Signing remains the durable destination and is a Non-Goal until explicit release authorization | | RFT-11 | Obsolete-host retirement **and** retained v1.188 P5 public first-run / Quick Start / live request | **v1.192** retired Tauri. **v1.193 P2 delivered:** the remaining daemon/SPA/`legacy-cli` composition and the dormant CLI rows listed in §7.4 were retired in that iteration. **v1.195 P3** exercises the retained public first-run as a clean-home deterministic example with its Quick Start/startup guidance, and one user-authorized live request has been exercised against the pinned official origin (all of it pending plan QC/QA and iteration integration) — see §7.5.1 | +**Implementation and exercise anchors:** `apps/nexus-service/src/routes.ts` mounts the family modules named above; `crates/nexus-core/src/service.rs`, `execution/handle_ops.rs`, and `execution/compute.rs` retain the Rust authority. Existing real-native HTTP journeys in `apps/nexus-service/tests/domain-http.test.mjs`, `actor-http.test.mjs`, `workflow-control-http.test.mjs`, `workflow-observation-http.test.mjs`, and `compute-http.test.mjs` exercise persisted domain effects, stored ownership, control/observation, and Compute accept/discard/clear. These are bounded family exercises, not blanket product acceptance, a Run Studio completeness claim, or permission for another live model request. + ### 7.5.1 Current-target reading (v1.195) The milestone labels above are historical program keys. They are not a blank-slate order, and they are not a claim that every family is product-complete. - Landed World/Work, Actor/Character, ordinary CLI, and desktop-host behavior stay out of v1.195 except where a selected workflow or Compute operation touches their existing authorization, CAS, or durable-effect contracts. -- RFT-07 is partial on the public service. Mounted schedule add and schedule signal are not list, inspect, core-context steering, cancellation settlement, or same-workflow observation. -- The TS-service Compute / Run Studio rows in the v1.195 inventory are still open. A native `compute` feature flag is not that closure. +- RFT-07 public workflow control includes schedule add/signal **and** `listSchedules`, `inspectSchedule`, `listWorkflowSessions`, `getWorkflowSession`, and `editCoreContext` in `apps/nexus-service/src/execution.ts`. Same-run `GET /v1/daemon/orchestration/sessions/{run_id}/events` is mounted by `workflow-observation.ts` over core-owned subscription/replay. The real-native control/observation journeys exercise append/resume, cancellation settlement, and restart visibility; these are not missing list/inspect/observation surfaces. +- The remaining unmounted identities in this execution surface are core-context **history reads** and schedule **label/delete** mutations (`execution.ts` explicitly retains `route_not_migrated` for them). That narrow gap is distinct from product-wide acceptance/QA. +- The TS-service Compute C1–C8 discovery/detail/run/history/accept/discard/terminal-clear routes are implemented in `compute.ts` over `crates/nexus-core/src/execution/compute.rs` and exercised by `compute-http.test.mjs`. What remains unqualified here is product acceptance/QA and Run Studio completeness, not backend route presence. A native feature flag or HTTP exercise alone does not close that UI/product obligation. - RFT-11 public first-run and Quick Start: v1.195 P3 exercises them as the clean-home public first workflow (`scripts/public-first-workflow.mjs` in deterministic mode) plus the Quick Start/current-startup guidance that replaced the retired daemon text. Those are P3 plan artifacts pending plan QC/QA and iteration integration; the deterministic receipt is loopback-only and is **not** live qualification. - The single user-authorized live request has been **exercised once** against the pinned official origin: one admitted request, guard evidence complete, same-run replay, committed revision, restart without repeating the commit and confirmed cleanup all observed. It is a P3 plan-scope receipt, not a product shipment — it stays pending plan QC/QA and iteration integration, and the authorization is now spent, so a further live attempt needs a new explicit user grant. - The live gate still refuses an environment that does not name the inherited credential channel: that case stops at `credentials_unavailable` with zero admissions, and an inherited model-origin override is refused rather than silently stripped. The driver never reads, copies, prints or persists the secret — its value stays with the sealed runtime's normal credential resolver — and a transport or authentication failure **after** an admission consumes the authorization, with no retry. Retired daemon commands stay retired. ## 8. Concurrent writes (user-locked) -While a TS service **or** the current integrated host is active, **authorized direct Rust CLI transactions are allowed**. Policy: +While a TS service is active, **authorized direct Rust CLI transactions are allowed**. The integrated Rust host is historical and was deleted in v1.193 P2. Policy: 1. **One engine/effect owner.** CLI and HTTP/native callers invoke the same Rust commands. No second workflow/recovery engine and no dual-writer caches that diverge. 2. **Per-resource CAS/OCC remains the conflict tool** for the M1 slice (`expected_version` on World KB entity patch). -3. **Per-Work advisory locks** (`Works//.lock`, [concurrency.md](concurrency.md)) stay per-Work. They are not workspace-host ownership and not the M1 writer protocol. +3. **Per-Work advisory locks** (`Works//.lock`, [concurrency.md](../runtime/concurrency.md)) stay per-Work. They are not workspace-host ownership and not the M1 writer protocol. 4. **Workspace host / migration fencing** is a distinct protocol: atomic conditional acquisition, serialized migrations, cache invalidation, and event/resync visibility. WAL, a per-process mutex, or the current `runtime_lock` read-then-update helper is not sufficient proof. 5. Unauthorized or stale writes deny. Owner collision is observable. Crash/reopen does not duplicate effects. 6. Two stable OS lock files separate shared-writer/exclusive-migration admission from exclusive engine ownership. Engine takeover requires actual OS lock release and SQL conditional monotonic epoch acquisition, never a heartbeat timeout or read-then-update. @@ -298,7 +324,7 @@ Preserve current cohorts. Selected candidate pins distinguish tooling, standalon | Product | Current preserved support | M1 proof | | --- | --- | --- | -| Desktop GUI | macOS arm64 and x86_64 (Electron host since the v1.192 cutover) | Electron evidence covers these macOS architectures with the accepted macOS 13+ floor; dual-architecture GUI and installed-deployment rows remain **[UNVERIFIED]** ([desktop-shell.md](desktop-shell.md) §12). Windows/Linux GUI is not current desktop support. | +| Desktop GUI | macOS arm64 and x86_64 (Electron host since the v1.192 cutover) | Electron evidence covers these macOS architectures with the accepted macOS 13+ floor; dual-architecture GUI and installed-deployment rows remain **[UNVERIFIED]** ([desktop-shell.md](../surfaces/desktop-shell.md) §12). Windows/Linux GUI is not current desktop support. | | Headless `nexus-runtime` | Windows x64 MSVC, macOS arm64, Linux x64 GNU | Keep this matrix. Runtime is not a desktop UI artifact. | | Browser / Studio | Current ESNext / system webview; Studio daemon-free on 5174 | No new browser matrix. No visual redesign. | | Node / native API | Root tooling remains `node >=22.22`, `pnpm >=11` | Standalone service floor Node22.22.0; proof Node22.22.0 and24.20.0 independently. Node-API8; napi3.12.4/derive3.6.5/build2.4.2, CLI3.9.1, Rust1.98.1. napi's MSRV1.88 is not a workspace support claim. | @@ -307,7 +333,7 @@ No new ARM Linux, musl, or Windows ARM support promise. Missing signing credenti Native targets: Windows x64 MSVC (Windows10/Server2016 ABI floor), macOS arm64/x64 (11.0 ABI floor), Linux x64 GNU (kernel4.18/glibc2.28). Use one existing sqlx0.9.0/libsqlite3-sys0.30.1 link. Electron44.3.0 embeds Node24.20.0/Chromium152.0.7977.78; packager20.3.0; TS ACP SDK1.4.0/zod4.6.2. Exact build candidates are Xcode16.4/deployment11.0, VS2022 17.14/v143/Windows SDK10.0.26100 and a glibc2.28 GNU sysroot/GCC10.1+. -**Desktop floor (resolved 2026-09-13):** Electron44 requires macOS13+ (Ventura); the retired Tauri config did not state a `minimumSystemVersion`. The user accepted macOS 13+ on arm64 and x86_64 as the Electron desktop target floor; v1.192 delivered the RFT-09 cutover, so the floor now governs the shipped Electron host rather than a future target. The M1 development GO did not require signed dual-architecture execution (signing is release-only / RFT-10 durable). **v1.192** does not implement signing. The accepted floor is not qualification evidence: GUI/x64 and installed-deployment rows remain **[UNVERIFIED]** ([desktop-shell.md](desktop-shell.md) §12). Missing runners, SDKs or signing evidence block qualification, not permission to reduce cohorts. +**Desktop floor (resolved 2026-09-13):** Electron44 requires macOS13+ (Ventura); the retired Tauri config did not state a `minimumSystemVersion`. The user accepted macOS 13+ on arm64 and x86_64 as the Electron desktop target floor; v1.192 delivered the RFT-09 cutover, so the floor now governs the shipped Electron host rather than a future target. The M1 development GO did not require signed dual-architecture execution (signing is release-only / RFT-10 durable). **v1.192** does not implement signing. The accepted floor is not qualification evidence: GUI/x64 and installed-deployment rows remain **[UNVERIFIED]** ([desktop-shell.md](../surfaces/desktop-shell.md) §12). Missing runners, SDKs or signing evidence block qualification, not permission to reduce cohorts. ## 12. Desktop: Electron shipped (delivered in v1.192), Tauri retired @@ -316,7 +342,7 @@ Electron is the **shipped** desktop host — v1.192 delivered the cutover and un - Reuse `apps/web`, Design Studio, and `packages/nexus-ui`. No visual redesign and no second desktop UI. - P3 was feasibility, not production distribution (RFT-10) and not Tauri retirement (RFT-11); v1.192 delivered the RFT-09 cutover and retired the Tauri composition. - **No-go does not complete M1.** M1 recorded a **development GO**, authorized by the v1.189 compass and native matrix run `34881345823`, not shipped desktop migration or production signing; v1.192 then delivered the RFT-09 product switch with unsigned app+DMG only, superseding that GO as the desktop's product basis. The historical decision JSON remains blocked (13 pass / 0 fail / 22 missing-or-unobserved, including x64 GUI rows); the CI matrix does not prove those rows passed. RFT-11 retired the replaced Tauri family after host/packaging acceptance; the still-consumed daemon/SPA composition and callable dormant CLI rows were **not** retired by that desktop change and stayed until v1.193 P2 removed them (see the delivered sentence at the end of this bullet). Product does not silently choose an alternative desktop. **Delivered (v1.193 P2):** the still-retained daemon/SPA composition and the dormant CLI rows are retired in that iteration (§7.2, §7.4); the desktop half stays as delivered. -- Tauri sidecar/IPC/path-guard behavior is retired with the composition; the shipped host's IPC/path/credential contract is owned by [desktop-shell.md](desktop-shell.md). Dual-architecture GUI and installed-deployment rows remain **[UNVERIFIED]** there. +- Tauri sidecar/IPC/path-guard behavior is retired with the composition; the shipped host's IPC/path/credential contract is owned by [desktop-shell.md](../surfaces/desktop-shell.md). Dual-architecture GUI and installed-deployment rows remain **[UNVERIFIED]** there. ## 13. Frontend DX (hard product goal) @@ -376,7 +402,7 @@ Measurement protocol: same candidate hardware and seeded real DB (500 entities,1 - Uninterrupted native continuation across TS restart - New ARM Linux / musl / Windows ARM / Windows-or-Linux GUI support - Unauthorized paid or live model requests. Historical P5 public first-run stays unshipped on `main`, and the v1.195 P3 example is a plan-scope receipt rather than a release qualification. v1.195 may execute only the one short request named by that iteration's Decision D5, after deterministic prerequisites and a one-request guard; that request has now been exercised once under the user's explicit authorization and is spent, an environment that does not name the credential channel still stops with zero admissions, a future admitted failure would consume a new authorization, and none of this reopens general live spend. -- Destructive data reset as migration/implementation shortcut; this does not remove the shipped explicitly confirmed desktop local-state-reset function, whose scope/fencing/recovery contract is preserved in [desktop-shell.md](desktop-shell.md) §8 +- Destructive data reset as migration/implementation shortcut; this does not remove the shipped explicitly confirmed desktop local-state-reset function, whose scope/fencing/recovery contract is preserved in [desktop-shell.md](../surfaces/desktop-shell.md) §8 - Browser/device/installed-deployment E2E as a development acceptance gate ## 17. Conflict with shipped Masters @@ -387,4 +413,4 @@ A family that has landed on the target: 2. Use this document for destination, host/lifetime, CLI disposition, the delivered M1 vertical identity, and the remaining RFT-05–11 keep/cutover rules. 3. When a remaining family lands on the target, fold the superseded section or record the deletion gate in the family plan. Do not leave two contradictory implementable topologies for the same family. -**Delivered (v1.193 P2):** the M1 World KB graph/patch, napi ACP, TS M1 vertical **and** the remaining retained families all fired their gates — the old mixed-handler topology no longer exists to conflict with. The rule above now binds only the unexercised RFT-05–11 destinations (§7.5), which must not be described as delivered before their own gates fire. +**Delivered (v1.193 P2):** the M1 World KB graph/patch, napi ACP, TS M1 vertical **and** the remaining retained families all fired their host-retirement gates — the old mixed-handler topology no longer exists to conflict with. RFT-05–07 route families are implemented and exercised (§7.5), while their product acceptance/QA and Run Studio completeness remain distinct from that evidence. Do not label implemented routes “unexercised”, or claim the remaining product/distribution/first-run qualification obligations are delivered without their own evidence. diff --git a/.mstar/specs/schemas-directory-layout.md b/.mstar/specs/architecture/schemas-directory-layout.md similarity index 93% rename from .mstar/specs/schemas-directory-layout.md rename to .mstar/specs/architecture/schemas-directory-layout.md index f45de915a..4004864d1 100644 --- a/.mstar/specs/schemas-directory-layout.md +++ b/.mstar/specs/architecture/schemas-directory-layout.md @@ -8,7 +8,7 @@ | **Document class** | Master | | **Scope** | Folder names, consumer-scope mapping, README rules, rename policy; **not** field-level DTO definitions (those stay in platform `v1-spec` + `data-model-v1`) | | **Last updated** | 2026-09-04 — reconciled current Daemon API schema and generated-module names through V1.183. | -| **Related** | [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md), [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md), [compute-module-abi.md](./compute-module-abi.md) §4–§5, [wasm-host.md](./wasm-host.md) §6–§7, [spoke-adapter-architecture.md](./spoke-adapter-architecture.md), [schemas/AGENTS.md](../../schemas/AGENTS.md), [tooling/AGENTS.md](../../tooling/AGENTS.md) | +| **Related** | [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md), [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md), [compute-module-abi.md](../compute/compute-module-abi.md) §4–§5, [wasm-host.md](../compute/wasm-host.md) §6–§7, [spoke-adapter-architecture.md](spoke-adapter-architecture.md), [schemas/AGENTS.md](../../../schemas/AGENTS.md), [tooling/AGENTS.md](../../../tooling/AGENTS.md) | **Do not confuse:** @@ -101,7 +101,7 @@ schemas/ - **Not** Daemon API proxies (V1.20 removed world/explore **daemon** routes; platform HTTP contracts **remain** wire here). - Grouping is **flat** (no `http-bff/explore/` subfolders) — use filename prefix: `explore-*`, `world-*`, `publish-*`, `notifications-*`, `context-assembly-v1`, etc. - `$id` / `$ref` URIs use `https://nexus42.invalid/schemas/platform/http-bff/...`. -- Maintain [`platform/http-bff/README.md`](../../schemas/platform/http-bff/README.md) index when adding files. +- Maintain [`platform/http-bff/README.md`](../../../schemas/platform/http-bff/README.md) index when adding files. ### 3.2 `platform/sync/` @@ -109,7 +109,7 @@ schemas/ - **`bundle.schema.json`** is the **codegen canonical** `Bundle` type. **`bundle-refinement.schema.json`** is a **validation refinement** (allOf of the canonical bundle with CLI-specific constraints) — codegen skips it (see `tooling/codegen/src/ts-gen.ts` `SKIP_LIST` / `tooling/codegen/rust-gen/src/main.rs` `SKIP_SCHEMAS`). - `delta.schema.json` and `sync-command.schema.json` moved here from `domain/` (V1.62 P0) because they are sync-protocol payloads, not wire entities. - `$id` / `$ref` URIs use `https://nexus42.invalid/schemas/platform/sync/...`. -- Maintain [`platform/sync/README.md`](../../schemas/platform/sync/README.md). +- Maintain [`platform/sync/README.md`](../../../schemas/platform/sync/README.md). ### 3.3 `domain/` @@ -127,7 +127,7 @@ Wire entities aligned with platform `data-model-v1` §5–§10. Current inventor (bundle/delta/sync-command moved to `platform/sync/` in V1.62 P0 — they are sync payloads, not wire entities.) -[`domain/README.md`](../../schemas/domain/README.md) MUST list only files that exist under `schemas/domain/*.json`. +[`domain/README.md`](../../../schemas/domain/README.md) MUST list only files that exist under `schemas/domain/*.json`. ### 3.4 `common/` @@ -141,9 +141,9 @@ Wire entities aligned with platform `data-model-v1` §5–§10. Current inventor - Compute module ABI envelopes consumed by **external** WASM compute modules and generated clients: `compute-input.schema.json`, `compute-output.schema.json`. - These are cross-language contracts (Rust host ↔ wasm32 module), so they live under `schemas/` and run through codegen, not as hand-written local types. -- Per-module shape declarations do **not** live here — they live in each module's `manifest.json` `schemas` block. See [modules/README.md](../../modules/README.md). +- Per-module shape declarations do **not** live here — they live in each module's `manifest.json` `schemas` block. See [modules/README.md](../../../modules/README.md). - `$id` / `$ref` URIs use `https://nexus42.invalid/schemas/daemon-api/compute/...`. -- Maintain [`daemon-api/compute/README.md`](../../schemas/daemon-api/compute/README.md). Compute ABI normative detail: [compute-module-abi.md](./compute-module-abi.md). Host-side runtime detail: [wasm-host.md](./wasm-host.md). +- Maintain [`daemon-api/compute/README.md`](../../../schemas/daemon-api/compute/README.md). Compute ABI normative detail: [compute-module-abi.md](../compute/compute-module-abi.md). Host-side runtime detail: [wasm-host.md](../compute/wasm-host.md). ### 3.5A `daemon-api/common/` @@ -168,7 +168,7 @@ Wire entities aligned with platform `data-model-v1` §5–§10. Current inventor Chapter contracts live in `daemon-api/works/chapters/` and use `/v1/daemon/works/{work_id}/chapters/*`; preset contracts live in `daemon-api/preset-management/`. Detailed chapter semantics: -[chapter-content-local-api.md](./chapter-content-local-api.md), whose filename +[chapter-content-local-api.md](../runtime/chapter-content-local-api.md), whose filename is historical. --- @@ -221,7 +221,7 @@ hand-maintained aggregate count. `schemas/README.md` and | --- | --- | --- | | `common/` | 3 | `common`, `source-anchor`, `version-ref` | | `domain/` | 10 → **9** (V1.139: `key-block.schema.json` deleted) | Wire entities (see §3.3 table) | -| `platform/http-bff/` | Current disk inventory | Platform HTTP bodies (flat; prefix grouping in [http-bff/README.md](../../schemas/platform/http-bff/README.md)) | +| `platform/http-bff/` | Current disk inventory | Platform HTTP bodies (flat; prefix grouping in [http-bff/README.md](../../../schemas/platform/http-bff/README.md)) | | `platform/sync/` | Current disk inventory | Bundle, pull, delta, command, and conflict contracts | | `daemon-api/common/` | Current disk inventory | Shared error/envelope contracts | | `daemon-api/compute/` | Current disk inventory | Compute input/output ABI | @@ -242,7 +242,7 @@ Do not hand-maintain an exact total here; `schemas/README.md` and `pnpm run vali **Not in tree:** `acp-runtime/`, `meta/`, `cli-sync/`, `cloud-sync/`, `compute/` (all removed/renamed). -Historical audit (pre-rename paths): [archived `schemas-boundary.md` §5.2](../archived/knowledge/schemas-boundary.md) — use this section for current paths. +Historical audit (pre-rename paths): [archived `schemas-boundary.md` §5.2](../../archived/knowledge/schemas-boundary.md) — use this section for current paths. --- diff --git a/.mstar/specs/schemas-external-consumer-boundary.md b/.mstar/specs/architecture/schemas-external-consumer-boundary.md similarity index 89% rename from .mstar/specs/schemas-external-consumer-boundary.md rename to .mstar/specs/architecture/schemas-external-consumer-boundary.md index 8242540f6..63cbf3648 100644 --- a/.mstar/specs/schemas-external-consumer-boundary.md +++ b/.mstar/specs/architecture/schemas-external-consumer-boundary.md @@ -1,7 +1,8 @@ # Schemas — External-Consumer Boundary **Status**: Active — current external daemon contracts use the Daemon API namespace; V1.64 originally established the bundled Web UI as an external API consumer -**Supersedes**: `schemas-wire-platform-sync-boundary.md` (renamed 2026-06-23, V1.62 P0; same file, expanded scope). Companion to archived [`schemas-boundary.md`](../archived/knowledge/schemas-boundary.md). +**Document class**: Companion +**Supersedes**: `schemas-wire-platform-sync-boundary.md` (renamed 2026-06-23, V1.62 P0; same file, expanded scope). Companion to archived [`schemas-boundary.md`](../../archived/knowledge/schemas-boundary.md). **Aligned with**: `nexus` `schemas/AGENTS.md`, `crates/nexus-contracts/src/local/` **Last reconciled**: 2026-09-04 — current schema tree, generated module names, and Daemon API namespace through V1.183. @@ -31,7 +32,7 @@ Everything else is **local**: hand-written Rust under `crates/nexus-contracts/sr Folder names, consumer-scope tree, and product-line mapping: **[schemas-directory-layout.md](schemas-directory-layout.md)**. On-disk index: -[schemas/README.md](../../schemas/README.md). +[schemas/README.md](../../../schemas/README.md). ## What still lives in `schemas/` today (2026-09, current through V1.183) @@ -51,15 +52,15 @@ V1.62 reorganized `schemas/` along consumer-scope lines and first moved compute ## Drift / housekeeping -- **README SSOT**: [schemas/README.md](../../schemas/README.md) + per-folder READMEs; layout rules in [schemas-directory-layout.md](schemas-directory-layout.md). Re-verify after moves. +- **README SSOT**: [schemas/README.md](../../../schemas/README.md) + per-folder READMEs; layout rules in [schemas-directory-layout.md](schemas-directory-layout.md). Re-verify after moves. - **Stale path risk**: do not reference `schemas/cli-sync/`, `schemas/meta/`, `schemas/acp-runtime/`, `schemas/cloud-sync/`, or `schemas/compute/` — removed or renamed (see layout spec §1 + §5 historical renames). - **Codegen**: only files under `schemas/` generate TS in `@42ch/nexus-contracts`; platform upgrades follow npm semver + `schema_version`. - **Promoted Daemon API handlers**: handlers must return generated contract shapes for promoted schemas; strict drift detection is required before a schema-promoted route is considered consumer-safe. -- **Historical audit table**: [archived `schemas-boundary.md` §5.2](../archived/knowledge/schemas-boundary.md) (53 wire / 10 local at audit time). Re-run an equivalent source scan before further moves; search `` in `nexus-platform` before deleting generated TypeScript. +- **Historical audit table**: [archived `schemas-boundary.md` §5.2](../../archived/knowledge/schemas-boundary.md) (53 wire / 10 local at audit time). Re-run an equivalent source scan before further moves; search `` in `nexus-platform` before deleting generated TypeScript. ## Related -- [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md) — local vs cloud product lines, crate graph, daemon API classes +- [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) — local vs cloud product lines, crate graph, daemon API classes --- diff --git a/.mstar/specs/spoke-adapter-architecture.md b/.mstar/specs/architecture/spoke-adapter-architecture.md similarity index 99% rename from .mstar/specs/spoke-adapter-architecture.md rename to .mstar/specs/architecture/spoke-adapter-architecture.md index 08989304a..9f1456880 100644 --- a/.mstar/specs/spoke-adapter-architecture.md +++ b/.mstar/specs/architecture/spoke-adapter-architecture.md @@ -5,7 +5,7 @@ > **Holder amendment (v1.191 P1 — shipped):** [holder-governance.md](holder-governance.md) owns the complete Actor-holder registry, native disclosure, trusted read policies, cutover and production extraction contract. The package pins moved together to the iteration's pinned upstream lockstep release (version SSOT: the manifest pins; compass D17 records the adoption decision). `creator_only` was removed only by that complete migration, not by a wire-only version bump. > **Document class:** Master > **Scope:** The `nexus-spoke-adapter` crate boundary, `extensions.nexus` namespace contract, spoke-operations delegation rules, daemon-api envelope strategy, drift detection adaptation, the `/kb/` HTTP route stability decision, the opt-in Connect Host N-C0 surface (DF-72), lore emission hygiene (DF-79), and Narrative Knowledge Pack I/O including the clean-room SillyTavern importer (DF-77/DF-80). -> **Related:** [entity-scope-model.md](entity-scope-model.md), [actor-product-model.md](actor-product-model.md), [holder-governance.md](holder-governance.md), [local-db-schema.md](local-db-schema.md), [schemas-directory-layout.md](schemas-directory-layout.md), and upstream SPOKE data/operations/Connect specifications. +> **Related:** [entity-scope-model.md](entity-scope-model.md), [actor-product-model.md](actor-product-model.md), [holder-governance.md](holder-governance.md), [local-db-schema.md](../runtime/local-db-schema.md), [schemas-directory-layout.md](schemas-directory-layout.md), and upstream SPOKE data/operations/Connect specifications. ## 0. Document Position @@ -648,8 +648,8 @@ explicit refs and automatic inclusion; archived never evaluates. Author-list default omission is separately owned by the core list boundary, before its SQL probe/cap, with explicit archived inclusion for CLI/HTTP/native callers. See -[Daemon API Surface Conventions §13](daemon-api-surface-conventions.md#13-world-structured-rule-lifecycle) -and [CLI specification](cli-spec.md); these are different read purposes, +[Daemon API Surface Conventions §13](../runtime/daemon-api-surface-conventions.md#13-world-structured-rule-lifecycle) +and [CLI specification](../cli/cli-spec.md); these are different read purposes, not two competing lifecycle authorities. **Stub behavior contract:** each stub is a documented empty/static return with a doc-comment referencing its roadmap trigger and residual. Stubs must never fabricate data — they return exactly what the backing storage would if it were empty/static. **V1.155 P0 (N-C3): the last stub is gone** — `HostManifestPort.list_peer_host_capability_manifests` is production (see the matrix row); the adapter has zero stubs. See `host_manifest_port.rs` module-level docs and §10. diff --git a/.mstar/specs/world-kb-runtime-architecture.md b/.mstar/specs/architecture/world-kb-runtime-architecture.md similarity index 83% rename from .mstar/specs/world-kb-runtime-architecture.md rename to .mstar/specs/architecture/world-kb-runtime-architecture.md index c60951abd..3373aec53 100644 --- a/.mstar/specs/world-kb-runtime-architecture.md +++ b/.mstar/specs/architecture/world-kb-runtime-architecture.md @@ -1,7 +1,8 @@ # World KB Runtime Architecture **Status**: Normative — V1.74 Shipped (§2 `kb_relationships` store + symmetric read projection; prior V1.51 §5.5 LLM pathway + §6 OCC extension). **V1.139 SPOKE alignment**: crate `nexus-kb` merged INTO `nexus-knowledge`; `KeyBlock` → `KnowledgeEntry` (technical wire name). Crate table §2 updated to reflect current topology. Full terminology sweep deferred to P3. -**Authority**: Implementation SSOT below normative specs. Does not override [entity-scope-model.md](../specs/entity-scope-model.md) or [novel-writing/workflow-profile.md](../specs/novel-writing/workflow-profile.md). +**Document class**: Master +**Authority**: Implementation SSOT below normative specs. Does not override [entity-scope-model.md](entity-scope-model.md) or [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md). **Iteration**: · (SPOKE alignment) --- @@ -16,24 +17,26 @@ World KB concerns were split across `nexus-knowledge` (formerly `nexus-kb`, merg | Layer | Crate | Responsibility | | --- | --- | --- | -| **Domain authority** | `nexus-core` | Transport-neutral family authority: `worlds`, `world_kb`, `forks`, `world_pack`, `world_rules` (+findings), `timeline` services, one ownership guard, guarded storage (§2.1) | -| **Domain (local)** | `nexus-knowledge` (V1.139: `nexus-kb` merged in) | KnowledgeEntry, SourceAnchors, taxonomy validation, `ingest_from_artifact()`, `KbStore` CRUD/query | -| **Domain (narrative)** | `nexus-narrative` | World entity, timeline binding | +| **Service-family authority** | `nexus-core` | `CoreService` orchestration and authorization for `worlds`, `world_kb`, `forks`, `world_pack`, `world_rules` (+findings), and `timeline`; shared ownership guard and guarded storage (§2.1), not ownership of the underlying domain aggregates | +| **World KB domain** | `nexus-knowledge` | `crates/nexus-knowledge/src/world_kb/` owns `KnowledgeEntryRecord`, `SourceAnchor`, taxonomy/body validation, `KbStore` traits and query types, and extraction preparation/persistence coordination. The former `nexus-kb` crate was merged here in V1.139. | +| **Narrative domain** | `nexus-narrative` | World, fork, timeline/event, and manuscript domain models; local branch persistence remains separate from the world-copy fork model (§6.6 of entity-scope-model) | | **Read SSOT** | `nexus-moment-context-assembly` | `WorldKbQueryBuilder` — shared filter/taxonomy logic; `assemble_moment` (wide session snapshot) and `build_chapter_kb_block` (narrow prompt slice) | | **User knowledge** | `nexus-knowledge` | User-scoped global knowledge — **also owns World KB after V1.139 merger** | | **Execution** | `nexus-orchestration` | Presets + capabilities; LLM inner graphs; schedule/job lifecycle — **no** KB domain rules | -| **Persistence mechanics** | `nexus-local-db` | SQLite migrations, `kb_extract_jobs`, `kb_key_blocks` tables | +| **SQLite persistence** | `nexus-local-db` | `crates/nexus-local-db/src/kb_store.rs` implements `SqliteKbStore`; `crates/nexus-local-db/src/kb_relationships.rs` owns relationship CRUD/OCC. This crate owns SQLite migrations and persistence for `kb_key_blocks`, `kb_relationships`, and `kb_extract_jobs`, not the domain aggregate definitions. | Platform integration reads World KB through `assemble_moment` / moment-context-assembly contracts, not through orchestration presets. V1.74 adds `kb_relationships` as the first-class relationship store under the World KB graph. Source/target entities FK to `kb_key_blocks`; source anchors remain optional JSON projection ids validated by the daemon. `GET graph` reads stored rows and emits derived reverse projections for `symmetric=true` without writing duplicate rows. -### 2.1 `nexus-core` — single World/KB/narrative family authority (v1.190 P0 — Normative) +### 2.1 `nexus-core` — single World/KB/narrative service-family authority (v1.190 P0 — Normative) -The World/KB/narrative family is owned by `nexus-core` behind `CoreService`; each family lives in its own module under `crates/nexus-core/src/`: `worlds` (World lifecycle list/get/create/delete), `world_kb` (graph / patch-entity / candidates / promote / relationship), `forks` (local timeline forks over immutable parent history), `world_pack` (pack import/export), `world_rules` (structured rules plus the advisory world-findings read) and `timeline` (timeline overview + per-World keyset event pages). Family reads and writes reuse the existing shared repositories (`SqliteNarrativeGateway`, `narrative_write`, `KbStore` and the spoke operations) — one SQL implementation, the same one the CLI uses. +World/KB/narrative **service orchestration and authorization** live behind `CoreService` in `nexus-core`; this is not a transfer of data/domain ownership from `nexus-knowledge` or `nexus-narrative`. Each family lives in its own module under `crates/nexus-core/src/`: `worlds` (World lifecycle list/get/create/delete), `world_kb` (graph / patch-entity / candidates / promote / relationship), `forks` (local timeline forks over immutable parent history), `world_pack` (pack import/export), `world_rules` (structured rules plus the advisory world-findings read) and `timeline` (timeline overview + per-World keyset event pages). Family reads and writes reuse the shared persistence implementations in `nexus-local-db` (`SqliteNarrativeGateway`, `narrative_write`, `SqliteKbStore`, `kb_relationships`) and the spoke operations; the `KbStore` trait and `KnowledgeEntryRecord` aggregate remain in `nexus_knowledge::world_kb`. **One ownership guard.** `world_kb::guards::check_world_owner` is the single ownership SQL: `SELECT owner_creator_id FROM narrative_worlds WHERE world_id = ?`. It reports a typed denial — `Missing` (no row), `Foreign` (the row names another creator), `Unowned` (`owner_creator_id` is NULL) — and every family (kb, pack, fork, rules, findings, timeline) calls this one guard; the daemon runs no ownership SQL of its own. +> **Historical v1.190 adapter/bridge notes (below).** The daemon HTTP adapters and transitional CLI pack bridge described in the next three paragraphs belong to the pre-retirement host topology, not current implementation anchors. Current pack service authority is `CoreService::import_world_pack` in `crates/nexus-core/src/world_pack.rs`; the `nexus-daemon-runtime` host was retired in v1.193. + **Denial → retained envelopes.** The guard surfaces the neutral `CoreError::WorldOwnerDenied { world_id, reason }`; the daemon adapter maps it to `Forbidden { resource: "world {id}", reason }` and HTTP 403. Each transport family keeps its retained envelope verbatim: World-KB-family routes render `world {id}` 404 plus the cross-author/unowned 403 reasons; timeline routes render `world {id} not found` 404 plus `you do not own this world` 403. **Daemon HTTP handlers are thin translations.** The narrative/worlds, world_kb, fork, world_rules, world_findings, world_kb_pack, timeline and timeline_events handlers only resolve the active creator + stored principal, call the matching `CoreService` method and map the neutral error onto the retained status/body envelopes. World-KB canonical mutations keep the ownership check, expected-version CAS (`kb_key_blocks.revision` / `kb_extract_jobs.version`) and the durable `core_changes` outbox inside one private transaction in core; no handler keeps business SQL or a second mutation path. @@ -106,7 +109,7 @@ Retire work-entry-only job semantics in V1.40; keep wire `BlockType` from contra V1.51 T-A P0 closes `R-V150KBED-01` by swapping the V1.50 heuristic (`block_type_guess='character'` for every capitalized noun phrase) for an LLM-driven extraction pathway. The `nexus.llm.extract` capability -([llm-extract.md](../specs/llm-extract.md)) is a sibling to `judge.llm`: both +([llm-extract.md](../orchestration/llm-extract.md)) is a sibling to `judge.llm`: both use the injected `PromptExecutor` and daemon Host plane, while `nexus.llm.extract` emits `Vec` carrying LLM-judged `block_type`, `canonical_name`, `confidence`, and a verbatim `source_quote`. @@ -134,7 +137,7 @@ queryable/sortable. Heuristic rows keep the V1.50 shape (columns `NULL`, V1.76 extends the extraction pathway to also **propose relationships** from chapter prose. `nexus.llm.extract` may now return `{ candidates, relationships? }` -(see [llm-extract.md](../specs/llm-extract.md) §1.2). The review-time hook +(see [llm-extract.md](../orchestration/llm-extract.md) §1.2). The review-time hook (`quality_loop::extract_kb_candidates_for_review`) parses the optional `relationships` array and persists suggestions into `kb_relationships` after endpoint resolution: @@ -151,8 +154,14 @@ nexus.llm.extract → { candidates, relationships? } `LlmExtractTask` remains a pure parser/invoker (it does not persist). Entity candidates continue through `quality_loop::persist_candidates` / -`kb_extract_jobs`; `extract_finalize` remains the `kb.extract_work` direct -KnowledgeEntry insert helper (not the suggestion path). Relationship persistence runs +`kb_extract_jobs`. The separate extraction finalization seam in +`crates/nexus-knowledge/src/world_kb/extract_finalize.rs` exposes +`prepare_extract` + `persist_prepared_extract`: preparation validates the +canonical name, body and trusted job-policy governance, allocates the entry ID +once, and attaches the source anchor and governance pair; persistence inserts +that exact prepared `KnowledgeEntryRecord` through `KbStore` without allocating +another ID or rebuilding defaults. The caller retains job-lifecycle ownership; +this seam is separate from the relationship-suggestion path. Relationship persistence runs **after** endpoint resolution and writes idempotent suggestions only when both endpoints already exist as non-deleted KnowledgeEntries (entity-scope-model §5.6.7). The `needs_review` gate + GET graph default-filter + confidence-weighting UX diff --git a/.mstar/specs/cli-command-ia.md b/.mstar/specs/archived/cli-command-ia.md similarity index 62% rename from .mstar/specs/cli-command-ia.md rename to .mstar/specs/archived/cli-command-ia.md index 6c30dcafe..54d8081c5 100644 --- a/.mstar/specs/cli-command-ia.md +++ b/.mstar/specs/archived/cli-command-ia.md @@ -1,15 +1,16 @@ # CLI Command Information Architecture — Normative Specification v1 **Status**: Shipped (V1.35) -**Document class**: Master (V1.35 lock effective) +**Document class**: Master (historical V1.35 lock; retained rationale supplement) **Created**: 2026-06-06 **Shipped**: 2026-06-07 (V1.35 P5 spec-tracker-hygiene) -**Supersedes**: pre-V1.35 [cli-spec.md](cli-spec.md) §6.0B six-group lock -**Merged into**: [cli-spec.md](cli-spec.md) §6.0B in V1.35 P5; retained as shipped IA rationale and acceptance supplement +**Supersedes**: pre-V1.35 [cli-spec.md](../cli/cli-spec.md) §6.0B six-group lock +**Merged into**: [cli-spec.md](../cli/cli-spec.md) §6.0B in V1.35 P5; retained as shipped IA rationale and acceptance supplement **Scope**: Top-level `nexus42` command groups, deprecation rules, creator-centric entry +**Supersession (v1.193 P2)**: Current command authority is [cli-spec.md](../cli/cli-spec.md) §6.0B plus its delivered v1.193 P2 overlay, checked against `apps/nexus42/src/cli.rs`. The daemon group (including lifecycle/schedule controls and hidden `daemon-run`), `web-embed`, DaemonClient leaves, `creator run` / `creator bootstrap` and the other incomplete runner entries, and the top-level `sync` alias were removed. `platform sync` is canonical; the direct-core `cli` cohort is the ordinary default (`apps/nexus42/Cargo.toml`). The V1.35 rationale and later pre-retirement amendments below are historical, not current command or onboarding rules. **Coordinates with**: -- [cli-spec.md](cli-spec.md) — per-command detail (§6 subsections remain authoritative for flags) +- [cli-spec.md](../cli/cli-spec.md) — per-command detail (§6 subsections remain authoritative for flags) - [creator-centric-entry-model.md](creator-centric-entry-model.md) — entry semantics - [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md) — local vs cloud split @@ -27,12 +28,12 @@ V1.35 revises top-level IA to **five groups** while preserving ADR-025 spirit (A --- -## 2. Top-level groups (V1.35 target) +## 2. Top-level groups (historical V1.35 target) | Group | Role | Primary persona | | --- | --- | --- | | **`creator`** | Agent identity hub — Work, workspace, assets, register/use | Creator operator | -| **`daemon`** | Runtime supervisor — start/stop, schedules (power user) | Advanced / automation | +| **`daemon`** (historical; retired v1.193 P2) | Runtime supervisor — start/stop, schedules (power user) | Advanced / automation | | **`acp`** | ACP capability plane — agents, registry, skills, probe | Integrator | | **`platform`** | User session — auth, **sync**, explore, context, publish | Platform user | | **`system`** | Local maintenance — doctor, config, preset list/validate, debug | Operator | @@ -43,9 +44,9 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see --- -## 3. Creator hub principles +## 3. Creator hub principles (V1.35 historical lock) -1. **Creative default path**: `creator run` is the user-facing Work lifecycle entry (V1.33 FL-E). +1. **Historical creative default path**: `creator run` was the user-facing Work lifecycle entry (V1.33 FL-E); its CLI entry was removed in v1.193 P2. 2. **Identity anchor**: All `creator *` commands bind to active `creator_id` from `creator use`. 3. **Optional platform mount**: Creator may operate pure-local; platform commands add cloud capabilities when User is logged in. 4. **Subcommand stability**: Existing `creator` subcommands remain unless P3 locks a rename strategy (§3.2). @@ -54,17 +55,17 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see | Tier | Subcommands | UX | | --- | --- | --- | -| **Primary** | `bootstrap`, `run`, `works`, `workspace`, `register`, `use` | First-run and daily use | +| **Primary** | `bootstrap`, `run` (both retired v1.193 P2), `works`, `workspace`, `register`, `use` | Historical first-run and daily-use tier | | **Assets** | `soul`, `memory`, `kb`, `knowledge`, `reference`, `world` | Scoped; help must disambiguate KB terms | | **Platform bridge** | `pair`, `unpair`, `credentials`, `list` (when User logged in) | Optional | | **Maintenance** | `demo-seed`, `status`, `logout` | Secondary | -**`creator run` (V1.45 target — replaces V1.44 bespoke subcommands):** +**Historical `creator run` amendment (V1.45 target — replaced V1.44 bespoke subcommands; runner retired v1.193 P2):** | Entry | Role | | --- | --- | -| `creator run []` | Generic preset dispatch; see [creator-run-preset-entry.md](creator-run-preset-entry.md) | -| `creator bootstrap …` | Composite Work onboarding (V1.45 generic runner; see creator-run-preset-entry.md) | +| `creator run []` (retired v1.193 P2) | Historical generic preset dispatch; see [creator-run-preset-entry.md](creator-run-preset-entry.md) | +| `creator bootstrap …` (retired v1.193 P2) | Historical composite Work onboarding (V1.45 generic runner; see creator-run-preset-entry.md) | | `creator works …` | Atomic Work ops only (`inspire`, `reopen`, `resume-chain`, `reconcile-chapters`, …) | **Removed in V1.45 (hard delete):** `review-master`, `audit-chapter`, `stage`, `start`, `continue`, `resume`, `reconcile-chapters` under `creator run`. @@ -94,7 +95,7 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see --- -## 4. Group responsibilities +## 4. Group responsibilities (historical V1.35 IA) ### 4.1 `platform` (includes sync) @@ -105,13 +106,13 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see | Context | `platform context assemble-moment` | local path shipped; cloud assemble deferred (DF-55) | | Explore / publish | `platform explore`, `platform publish` | yes | -**Migration (P2):** +**Historical migration (V1.35 P2; alias removed in v1.193 P2):** - Implement `platform sync` as canonical surface. -- Top-level `nexus42 sync` → deprecated hidden alias forwarding to `platform sync` for ≥1 iteration. +- Top-level `nexus42 sync` → deprecated hidden alias forwarding to `platform sync` for ≥1 iteration (historical transition only; the alias is now deleted). - Update cli-spec §6.7 boundary table and shell completion. -### 4.2 `daemon` +### 4.2 `daemon` (historical — entire group retired v1.193 P2) - Lifecycle: `start`, `stop`, `status`, `logs`, `doctor` - Orchestration control: `schedule add|edit|...` — **advanced**; document as power-user path @@ -120,7 +121,7 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see ### 4.3 `acp` - Unchanged separation from daemon (negotiation vs runtime control) -- Worker entry points remain hidden (`acp-worker`, `daemon-run`) +- Historical worker entry points were hidden (`acp-worker`, `daemon-run`); `daemon-run` was deleted in v1.193 P2, not retained as a hidden entry. ### 4.4 `system` @@ -129,7 +130,9 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see --- -## 5. Deprecation and compatibility +## 5. Deprecation and compatibility (historical V1.35 policy) + +The table records the V1.35 transition, not live aliases or runner guidance. The top-level `sync` alias, `daemon` group, and `creator run` entry were deleted in v1.193 P2. | Legacy | Target | V1.35 rule | | --- | --- | --- | @@ -137,24 +140,26 @@ No sixth top-level group in V1.35. Pre-release allows deprecation aliases (see | `daemon schedule` as first-run hint | `creator run` | Help text only; no command removal | | Top-level `preset` (never shipped) | `system preset`, `creator run` | Document only (DF-52) | -**Hard delete** of `sync` top-level: **Out of V1.35** — earliest V1.36 after alias period. **Durable roadmap:** DR-53 (top-level `sync` hard-delete). +**Historical V1.35 deferral:** hard delete of top-level `sync` was out of V1.35 — earliest V1.36 after the alias period (DR-53). **Delivered v1.193 P2:** the alias is deleted; only `platform sync` remains canonical. --- -## 6. First-run paths (summary) +## 6. First-run paths (historical V1.35 summary) -Detailed steps: cli-spec §7. Normative split: +Historical detailed steps: cli-spec §7. V1.35 normative split (current entry authority: cli-spec §6.0B + v1.193 P2 overlay): | Path | When | Platform auth | | --- | --- | --- | | **Local-first** (§7.1) | Default; `platform_integration = paused` | Not required | | **Platform-mounted** (§7.2) | User wants cloud worlds / sync | Required | -Local-first must reach `creator bootstrap` in ≤7 commands (see creator-centric-entry-model §3.1). +Historical V1.35 acceptance required local-first to reach `creator bootstrap` in ≤7 commands (see creator-centric-entry-model §3.1). `creator bootstrap` was removed in v1.193 P2; this is not a current onboarding chain. --- -## 7. Help and discoverability rules (P2/P3 implement) +## 7. Help and discoverability rules (historical V1.35 P2/P3 implement) + +The `creator run` / `daemon schedule` help rules below describe the retired entry model, not current help requirements. 1. Root `long_about` mentions **`creator run`** and **`creator workspace init`**, not `daemon schedule`. 2. `creator --help` ordering: surface `run` near top (implementation detail — P3). @@ -163,7 +168,7 @@ Local-first must reach `creator bootstrap` in ≤7 commands (see creator-centric --- -## 8. Acceptance (spec-level) +## 8. Acceptance (historical V1.35 spec-level criteria) 1. This document and cli-spec §6 header agree on five groups post-P2. 2. `nexus42 --help` lists five groups; sync appears under platform or as deprecated alias only. @@ -174,7 +179,7 @@ Local-first must reach `creator bootstrap` in ≤7 commands (see creator-centric ## 9. Change control -- **Authority**: this spec > cli-spec §6.0B legacy text until P5 hygiene merge. +- **Historical authority**: this spec overrode cli-spec §6.0B legacy text until the V1.35 P5 hygiene merge. Current authority is cli-spec §6.0B + the delivered v1.193 P2 overlay, not this rationale supplement. - **Platform unpause**: Does not automatically add top-level groups; extends `platform` subcommands only. - **Impact before rename**: `gitnexus_impact` required for any `creator kb` rename (P3). diff --git a/.mstar/specs/creator-centric-entry-model.md b/.mstar/specs/archived/creator-centric-entry-model.md similarity index 58% rename from .mstar/specs/creator-centric-entry-model.md rename to .mstar/specs/archived/creator-centric-entry-model.md index 9dd651e7c..6e37618eb 100644 --- a/.mstar/specs/creator-centric-entry-model.md +++ b/.mstar/specs/archived/creator-centric-entry-model.md @@ -1,17 +1,18 @@ # Creator-Centric Entry Model — Normative Supplement v1 **Status**: Shipped (V1.35) -**Document class**: Master (V1.35 lock effective) +**Document class**: Master (historical V1.35 lock; retained entry-model supplement) **Created**: 2026-06-06 **Shipped**: 2026-06-07 (V1.35 P5 spec-tracker-hygiene) -**Merged into**: [cli-spec.md](cli-spec.md) §7 in V1.35 P5; retained as shipped entry-model supplement +**Merged into**: [cli-spec.md](../cli/cli-spec.md) §7 in V1.35 P5; retained as shipped entry-model supplement **Scope**: Product-level rules for **when** users enter via `creator` vs `platform` vs `system` +**Supersession (v1.193 P2)**: Current entry semantics are defined by [cli-spec.md](../cli/cli-spec.md) §6.0B and its delivered v1.193 P2 overlay, not this V1.35 onboarding record. `daemon start`, `creator bootstrap`, `creator run`, and all daemon scheduling controls were retired; the steps below that use them are historical, not current entry rules. The direct-core `cli` cohort is now the ordinary default (`apps/nexus42/src/cli.rs`, `apps/nexus42/src/commands/creator/mod.rs`, `apps/nexus42/Cargo.toml`). **Coordinates with**: - [cli-command-ia.md](cli-command-ia.md) — top-level IA -- [cli-spec.md](cli-spec.md) — command detail -- [work-experience-model.md](work-experience-model.md) — Work journey -- [entity-scope-model.md](entity-scope-model.md) — KB / knowledge scopes +- [cli-spec.md](../cli/cli-spec.md) — command detail +- [work-experience-model.md](../creator/work-experience-model.md) — Work journey +- [entity-scope-model.md](../architecture/entity-scope-model.md) — KB / knowledge scopes --- @@ -26,15 +27,15 @@ V1.35 locks **creator as the creative hub**. Platform capabilities are **optiona --- -## 2. Entry rules (normative) +## 2. Entry rules (historical V1.35 normative lock) | User intent | Primary entry | Notes | | --- | --- | --- | -| Start or continue creative **Work** | `nexus42 creator run ...` | Default product path (V1.33+ FL-E) | +| Start or continue creative **Work** | `nexus42 creator run ...` (retired v1.193 P2) | Historical default product path (V1.33+ FL-E), not a current CLI entry | | Register / switch Creator identity | `nexus42 creator register\|use\|list` | Pure local register allowed pre-release | | Workspace + SOUL + memory + local assets | `nexus42 creator workspace\|soul\|memory\|kb\|knowledge\|reference` | Bound to active `creator_id` | -| Connect external AI agent | `nexus42 acp agent use` | After `daemon start` | -| Run presets / schedules (power user) | `nexus42 daemon schedule ...` | Advanced; not first-run default | +| Connect external AI agent | `nexus42 acp agent use` | Historical prerequisite: `daemon start` (retired v1.193 P2; no longer required) | +| Run presets / schedules (power user) | `nexus42 daemon schedule ...` (retired v1.193 P2) | Historical advanced path; not a current CLI surface | | User login, cloud sync, explore, publish | `nexus42 platform ...` | Requires User session when platform integration enabled | | Doctor, config, preset validate | `nexus42 system ...` | Not creator-scoped maintenance | @@ -42,19 +43,19 @@ V1.35 locks **creator as the creative hub**. Platform capabilities are **optiona ## 3. Pure local vs platform-mounted -### 3.1 Pure local path (default while `platform_integration = paused`) +### 3.1 Pure local path (historical V1.35 default while `platform_integration = paused`) -Minimum chain to first Work (≤7 steps — see cli-spec §7.1): +Historical minimum chain to first Work (≤7 steps — V1.35 cli-spec §7.1). Steps 5 and 7 were retired in v1.193 P2; this chain is not a current first-Work recipe, and no replacement CLI runner is implied: 1. `system doctor` 2. `creator register` (or reuse existing) 3. `creator use ` 4. `creator workspace init` -5. `daemon start` +5. `daemon start` — **historical; retired v1.193 P2** 6. `acp agent use ` -7. `creator bootstrap --idea "..."` +7. `creator bootstrap --idea "..."` — **historical; retired v1.193 P2** -No `platform auth login` or `sync pull` required. +No `platform auth login` or sync pull was required; the current canonical sync spelling is `platform sync pull`, not the retired top-level `sync` alias. ### 3.2 Platform-mounted path @@ -75,14 +76,14 @@ Creator commands **must not** silently require User token when local-only policy | `sync pull\|push` | `platform sync` | User-scoped cloud boundary (PD-05: not short-term focus but IA clarity) | | `doctor`, `config`, `preset validate` | `system` | Machine maintenance, not agent identity | | ACP protocol negotiation | `acp` | Separate capability plane per ADR-025 spirit | -| Daemon lifecycle / schedule control | `daemon` | Runtime supervisor, not identity | +| Daemon lifecycle / schedule control (historical; retired v1.193 P2) | `daemon` (deleted group) | Historical runtime supervisor, not identity; no current CLI control surface | --- ## 5. Invariants 1. **Single active creator** per CLI session (`creator use`); all `creator *` subcommands resolve against it. -2. **Creative entry** for new users is **`creator run`**, not `daemon schedule` (help text and docs must agree). +2. **Historical V1.35 creative entry** for new users was **`creator run`**, not `daemon schedule`; both CLI entries were removed in v1.193 P2, so this is no longer a help-text or onboarding invariant. 3. **`creator kb`** is never generic “all knowledge”; use qualified terms per entity-scope-model §5.4. 4. Platform group remains in IA even when paused — help must say “requires login; skip for local-only”. diff --git a/.mstar/specs/creator-run-preset-entry.md b/.mstar/specs/archived/creator-run-preset-entry.md similarity index 56% rename from .mstar/specs/creator-run-preset-entry.md rename to .mstar/specs/archived/creator-run-preset-entry.md index b64027aa7..51017809c 100644 --- a/.mstar/specs/creator-run-preset-entry.md +++ b/.mstar/specs/archived/creator-run-preset-entry.md @@ -1,25 +1,35 @@ -# Creator Run Preset Entry — Normative Specification v1 +# Creator Run Preset Entry — Retired Historical Record -**Status**: Shipped (V1.45 — 2026-06-13) -**Document class**: Master (wave 0 for V1.45 CLI IA) +**Status**: Retired runner record (v1.193 P2-T1); originally Shipped (V1.45 — 2026-06-13) +**Document class**: Master (historical V1.45 CLI IA; no current dispatch authority) **Created**: 2026-06-13 -**Last updated**: 2026-06-14 (P-last promotion Draft → Shipped) -**Scope**: Author-facing **`nexus42 creator run []`** — generic orchestration preset dispatch; relationship to `creator bootstrap`, atomic `creator works`, and `daemon schedule` +**Last updated**: 2026-09-29 — v1.193 P2-T1 retirement boundary (V1.45 Draft → Shipped promotion: 2026-06-14) +**Scope**: Historical author-facing **`nexus42 creator run []`** — removed generic preset dispatch and its former relationship to `creator bootstrap`, atomic `creator works`, and `daemon schedule` **Coordinates with**: -- [cli-spec.md](cli-spec.md) — per-flag detail (§6.2D implement amendment) +- [cli-spec.md](../cli/cli-spec.md) — per-flag detail (§6.2D implement amendment) - [cli-command-ia.md](cli-command-ia.md) — three-plane IA -- [orchestration-engine.md](orchestration-engine.md) — presets, gates, `run_intents` -- [work-experience-model.md](work-experience-model.md) — Work lifecycle -- [creator-workflow.md](creator-workflow.md) — FL-E stage ↔ preset mapping -- [novel-writing/work-pool.md](novel-writing/work-pool.md) — pool `active` default +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — presets, gates, `run_intents` +- [work-experience-model.md](../creator/work-experience-model.md) — Work lifecycle +- [creator-workflow.md](../creator/creator-workflow.md) — FL-E stage ↔ preset mapping +- [novel-writing/work-pool.md](../novel-writing/work-pool.md) — pool `active` default **Tracker**: BL-12 --- +## 0. Current authority and retirement + +The generic runner shipped in **V1.45** and was removed in **v1.193 P2-T1** with the incomplete Creator execution entrances. **No replacement CLI preset-dispatch entrance was introduced.** Sections §1–§8 preserve the retired runner's shipped contract, grammar, flows, and acceptance history; none is a current setup or execution instruction. + +Current Work operations belong to the retained **`nexus42 creator works`** families: selection/status/pool, `inspire`, `reopen`, `reconcile-chapters`, completion-lock, findings, and rules. They are atomic operations, **not** a replacement generic runner. See [cli-spec.md](../cli/cli-spec.md) for the current CLI contract and [`apps/nexus42/src/commands/creator/works/mod.rs`](../../../apps/nexus42/src/commands/creator/works/mod.rs) for `WorksCommand`, the retirement header, the migrated atomic handlers, and `print_findings_summary` (which no longer advertises `creator run novel-review-master`). + +--- + ## 1. Purpose +> **Historical — shipped V1.45, retired v1.193 P2-T1.** The single preset entry below no longer exists; §0 identifies the retained atomic Work surface. + Pre-V1.45, `creator run` accumulated **hardcoded subcommands** (`start`, `continue`, `stage`, `audit-chapter`, `review-master`, …). Each new embedded preset required editing `RunCommand` in Rust. V1.45 defines a **single product entry** for running any orchestration preset: @@ -34,6 +44,8 @@ Adding a preset ships **YAML + optional docs**, not CLI enum variants. ## 2. Three-plane CLI model +> **Historical V1.45 CLI model.** The strategy-execution plane and its onboarding/daemon execution companions below are not current entrances. Only the retained atomic Work operations are current (§0). + | Plane | Command | Responsibility | | --- | --- | --- | | Composite onboarding | `creator bootstrap` | Create Work + schedule intake/init/produce chain | @@ -46,6 +58,8 @@ Presets may invoke daemon capabilities that perform atomic Work ops during execu ## 3. Command grammar +> **Historical grammar — not runnable.** The syntax, discovery rules, and runner argument mapping in §3.1–§3.3 describe the removed V1.45 runner, not a supported dispatch command. + ### 3.1 Syntax ```text @@ -57,7 +71,7 @@ nexus42 creator run [] [--json] [--force-gates --reason "` | Yes | Resolved via orchestration preset registry (embedded, user, `_system.*`) | | `` | No | Optional **positional** `wrk_…`. Omitted → pool **`active`** Work (same resolution as `creator works status`) | | `--json` | No | Machine-readable schedule response | -| `--force-gates --reason` | No | Audited gate bypass ([orchestration-engine.md](orchestration-engine.md) §7.9). `--reason` required when `--force-gates` set | +| `--force-gates --reason` | No | Audited gate bypass ([orchestration-engine.md](../orchestration/orchestration-engine.md) §7.9). `--reason` required when `--force-gates` set | **Not supported on `creator run`:** `--work-id` flag (use positional); `stage advance --force` (Removed in V1.45; see changelog). @@ -106,7 +120,7 @@ The generic runner maps parsed flags to `AddScheduleRequest.input`. P0 ships `cl 1. Resolve `` (fail if unknown). 2. Resolve ``: positional arg or pool `active`; if none, fail with remediation → `creator bootstrap` or `creator works use`. 3. Build schedule request (preset input from `cli_args`, Work-derived context from daemon). -4. For FL-E default presets (`research`, `novel-writing`, `novel-chapter-review`, `kb-extract`), apply **stage advance** semantics before enqueue: validate stage gates, PATCH Work stage fields, then create schedule. These semantics are **live behavior** of the generic runner — the standalone `creator run stage advance` **subcommand** was removed in V1.45 (replaced by this runner's built-in stage path); see the V1.45 changelog. +4. For FL-E default presets (`research`, `novel-writing`, `novel-chapter-review`, `kb-extract`), apply **stage advance** semantics before enqueue: validate stage gates, PATCH Work stage fields, then create schedule. These semantics were **V1.45 behavior** of the now-retired generic runner — the standalone `creator run stage advance` **subcommand** was removed in V1.45 (replaced then by that runner's built-in stage path); see the V1.45 changelog. 5. `POST /v1/local/orchestration/schedules` — orchestration validates `run_intents` and `gates`. 6. Print schedule id (human or JSON). @@ -145,13 +159,13 @@ Hard delete legacy subcommands — **no deprecated aliases** (pre-release). ## 8. V1.45 supersession notes (P-last promotion) -This Master **supersedes** the V1.44 cli-spec §6.2D/E bespoke subcommand tables and the V1.45 Draft overlay sections in the following specs: +**Historical V1.45 supersession:** this Master superseded the V1.44 cli-spec §6.2D/E bespoke subcommand tables and the V1.45 Draft overlay sections in the following specs. That promotion does not restore dispatch authority after the v1.193 P2-T1 retirement (§0). -- [creator-workflow.md](creator-workflow.md) (FL-E CLI overlay) -- [novel-writing/quality-loop.md](novel-writing/quality-loop.md) (preset-id commands overlay; applied P3) -- [novel-writing/manuscript-audit.md](novel-writing/manuscript-audit.md) (CLI entry overlay; split presets) -- [work-experience-model.md](work-experience-model.md) (side-input + run_intents overlay) -- [orchestration-engine.md](orchestration-engine.md) (`run_intents` dispatch overlay) -- [cli-spec.md](cli-spec.md) (creator run preset entry overlay) +- [creator-workflow.md](../creator/creator-workflow.md) (FL-E CLI overlay) +- [novel-writing/quality-loop.md](../novel-writing/quality-loop.md) (preset-id commands overlay; applied P3) +- [novel-writing/manuscript-audit.md](../novel-writing/manuscript-audit.md) (CLI entry overlay; split presets) +- [work-experience-model.md](../creator/work-experience-model.md) (side-input + run_intents overlay) +- [orchestration-engine.md](../orchestration/orchestration-engine.md) (`run_intents` dispatch overlay) +- [cli-spec.md](../cli/cli-spec.md) (creator run preset entry overlay) **Promotion date**: 2026-06-14 (P-last closeout) diff --git a/.mstar/specs/daemon-runtime.md b/.mstar/specs/archived/daemon-runtime.md similarity index 93% rename from .mstar/specs/daemon-runtime.md rename to .mstar/specs/archived/daemon-runtime.md index 688a825fb..caae1480b 100644 --- a/.mstar/specs/daemon-runtime.md +++ b/.mstar/specs/archived/daemon-runtime.md @@ -4,10 +4,10 @@ | Attribute | Value | | --- | --- | -| **Status** | **Retired host record (v1.193 P2).** The integrated daemon host documented here is **deleted**: the `nexus-daemon-runtime` crate, the whole `nexus42 daemon` group, hidden `daemon-run` and the `web-embed` embedded-SPA bytes are gone, and no replacement service launcher was introduced. Current owners of the retained contracts: the standalone TypeScript service (`apps/nexus-service`) serves `/v1/daemon/*` for browser/Electron, Electron owns the desktop and its service lifecycle, `nexus-runtime` is the independent Connect host (§4.6), and `nexus42` is a one-shot direct-core/cloud/Connect CLI ([rust-core-service-boundary.md](rust-core-service-boundary.md) §7.2, [cli-spec.md](./cli-spec.md) §6.3). Sections below are the **historical record of the retired host** unless they name a retained wire, Connect or checkpoint contract. — Normative — V1.65 Prepare amendment (bundled local Web UI serving + chapter-content Daemon API route family); **V1.66 Phase 2b amendment** (§12: Tauri sidecar mode launch/readiness/lifecycle contract); **V1.86 amendment** (§13: Daemon API trust-boundary security — Origin allowlist, deny-fs-without-workspace, component-wise path guard); **V1.90 amendment** (§14: Daemon API remote bind gate; normative surface renaming from Local API to Daemon API with `/v1/daemon/` path prefix); **V1.92 amendment** (§15–16: transport security (TLS) + remote client connection model); **V1.118 amendment** (§17: no-Profile boot + lazy `state.db` open); **V1.153 amendment** (§4.6: headless `nexus-runtime` profile — second user-facing executable artifact for the integrator channel); **v1.192 amendment** (§12: Tauri desktop host retired — the sidecar section is a historical record; the desktop host is Electron, contract [desktop-shell.md](desktop-shell.md)) | +| **Status** | **Retired host record (v1.193 P2).** The integrated daemon host documented here is **deleted**: the `nexus-daemon-runtime` crate, the whole `nexus42 daemon` group, hidden `daemon-run` and the `web-embed` embedded-SPA bytes are gone, and no replacement service launcher was introduced. Current owners of the retained contracts: the standalone TypeScript service (`apps/nexus-service`) serves `/v1/daemon/*` for browser/Electron, Electron owns the desktop and its service lifecycle, `nexus-runtime` is the independent Connect host (§4.6), and `nexus42` is a one-shot direct-core/cloud/Connect CLI ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §7.2, [cli-spec.md](../cli/cli-spec.md) §6.3). Sections below are the **historical record of the retired host** unless they name a retained wire, Connect or checkpoint contract. — Normative — V1.65 Prepare amendment (bundled local Web UI serving + chapter-content Daemon API route family); **V1.66 Phase 2b amendment** (§12: Tauri sidecar mode launch/readiness/lifecycle contract); **V1.86 amendment** (§13: Daemon API trust-boundary security — Origin allowlist, deny-fs-without-workspace, component-wise path guard); **V1.90 amendment** (§14: Daemon API remote bind gate; normative surface renaming from Local API to Daemon API with `/v1/daemon/` path prefix); **V1.92 amendment** (§15–16: transport security (TLS) + remote client connection model); **V1.118 amendment** (§17: no-Profile boot + lazy `state.db` open); **V1.153 amendment** (§4.6: headless `nexus-runtime` profile — second user-facing executable artifact for the integrator channel); **v1.192 amendment** (§12: Tauri desktop host retired — the sidecar section is a historical record; the desktop host is Electron, contract [desktop-shell.md](../surfaces/desktop-shell.md)) | | **Document class** | Master | | **Normative scope** | Architecture boundaries, process model, subsystem responsibilities, pre-release constraints | -| **Related** | [cli-spec.md](./cli-spec.md), [local-runtime-boundary.md](./local-runtime-boundary.md), [agent-host.md](./agent-host.md) | +| **Related** | [cli-spec.md](../cli/cli-spec.md), [local-runtime-boundary.md](../architecture/local-runtime-boundary.md), [agent-host.md](../agents/agent-host.md) | | **Last reconciled** | 2026-09-12 — shipped V1.186 authoritative run/recovery contract plus V1.188 truthful readiness, retained workspace authority, settle-once cleanup and bounded run SSE (§20) | --- @@ -24,7 +24,7 @@ Pre-release posture: no compatibility migration layer required; local state may ## 2. Normative layering -> **Historical (retired in v1.193 P2).** The `nexus-daemon-runtime` library layer below no longer exists; the retained layering is `nexus42` (one-shot `cli` cohort) / independent `nexus-runtime` (Connect) over the Rust authority, with TypeScript for the HTTP/transport host ([rust-core-service-boundary.md](rust-core-service-boundary.md) §4). The platform-sync/daemon-runtime separation rule at the end of this section still holds for the retained crates. +> **Historical (retired in v1.193 P2).** The `nexus-daemon-runtime` library layer below no longer exists; the retained layering is `nexus42` (one-shot `cli` cohort) / independent `nexus-runtime` (Connect) over the Rust authority, with TypeScript for the HTTP/transport host ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §4). The platform-sync/daemon-runtime separation rule at the end of this section still holds for the retained crates. ```text nexus42 (CLI — entry, routing, UX) @@ -36,7 +36,7 @@ nexus42 (CLI — entry, routing, UX) └─ nexus-cloud-sync (CLI-only; platform HTTP + optional legacy-sync) ``` -Platform sync and registration **must not** live in daemon-runtime. See [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md). +Platform sync and registration **must not** live in daemon-runtime. See [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md). **Rules** (historical — the daemon start path they describe is deleted): @@ -61,7 +61,7 @@ Platform sync and registration **must not** live in daemon-runtime. See [local-c ## 4. Process model -> **Historical (retired in v1.193 P2) — §4.1–§4.4 are not runnable.** `nexus42 daemon start|stop|restart|status|logs|doctor|ui|web` are unknown commands and the embedded-SPA serving model was deleted with the crate. The retained host contract is: the TS service owns its own process/readiness/discovery lifecycle under Electron ([rust-core-service-boundary.md](rust-core-service-boundary.md) §8.1, [desktop-shell.md](desktop-shell.md) §7), and the `nexus42 desktop bundle` entry still delegates to the desktop packaging driver. +> **Historical (retired in v1.193 P2) — §4.1–§4.4 are not runnable.** `nexus42 daemon start|stop|restart|status|logs|doctor|ui|web` are unknown commands and the embedded-SPA serving model was deleted with the crate. The retained host contract is: the TS service owns its own process/readiness/discovery lifecycle under Electron ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §8.1, [desktop-shell.md](../surfaces/desktop-shell.md) §7), and the `nexus42 desktop bundle` entry still delegates to the desktop packaging driver. ### 4.1 Foreground @@ -77,7 +77,7 @@ Default `nexus42 daemon start`: preflight → spawn internal daemon-run mode → ### 4.4 Bundled local Web UI static assets (V1.64 — **retired in v1.193 P2**) -> **Retired.** The daemon no longer serves the SPA and the `web-embed` / `rust-embed` static-asset path is deleted (no embedded SPA bytes exist in the retained graph). Current owner: the standalone TS service serves `apps/web/dist` for browser and Electron; the desktop host loads the same build through its own `nexus://app` protocol ([desktop-shell.md](desktop-shell.md) §6). What survives is the **retained wire family** — the `/v1/daemon/*` routes, their auth tiers and the client-origin admission rules (§13–§16). Everything below is the historical serving model. +> **Retired.** The daemon no longer serves the SPA and the `web-embed` / `rust-embed` static-asset path is deleted (no embedded SPA bytes exist in the retained graph). Current owner: the standalone TS service serves `apps/web/dist` for browser and Electron; the desktop host loads the same build through its own `nexus://app` protocol ([desktop-shell.md](../surfaces/desktop-shell.md) §6). What survives is the **retained wire family** — the `/v1/daemon/*` routes, their auth tiers and the client-origin admission rules (§13–§16). Everything below is the historical serving model. The daemon runtime may serve the bundled local Web UI SPA from the same loopback listener as the Daemon API. The Web UI is a local product surface, not a cloud platform application. @@ -87,7 +87,7 @@ Normative serving model: 2. **SPA shell route**: the static Web UI shell (`index.html` plus assets) is unauthenticated so a local browser can load the app and present setup/auth guidance. This does not grant data access. 3. **Data boundary**: all `/v1/daemon/*` data routes remain protected according to the existing `require_api_key` model except the explicitly unguarded runtime/daemon health and status routes listed in §2/§4 acceptance. The SPA obtains data only through those Daemon API routes. 4. **Dev mode**: during frontend development, Vite serves `apps/web` and proxies `/v1/daemon/*` to a running daemon. Dev proxy behavior is a development convenience only; release behavior is daemon-served embedded static assets. -5. **Desktop readiness**: the desktop host loads the same `apps/web` build output and swaps the frontend transport implementation behind the `NexusClient` boundary. The desktop host is Electron since v1.192 ([desktop-shell.md](desktop-shell.md)) and supervises its own service — see §12's retirement note; the daemon runtime remains the local supervisor for the CLI/browser flows and is still not an ACP Agent/Server. +5. **Desktop readiness**: the desktop host loads the same `apps/web` build output and swaps the frontend transport implementation behind the `NexusClient` boundary. The desktop host is Electron since v1.192 ([desktop-shell.md](../surfaces/desktop-shell.md)) and supervises its own service — see §12's retirement note; the daemon runtime remains the local supervisor for the CLI/browser flows and is still not an ACP Agent/Server. The router integration point is the top-level `create_router` composition in `crates/nexus-daemon-runtime/src/api/mod.rs`: static serving is added beside the unguarded runtime routes and protected Daemon API route tree, without moving the auth middleware boundary for data endpoints. @@ -172,7 +172,7 @@ sibling temp file + flush + atomic rename and updates `outline_path`/`updated_at through the same finalization path. The body writer remains the orchestration host-tool path — the AI owns prose writing; there is no manual body editor (the body-editor direction was rejected 2026-06-26; see -[canvas-strategy-surface.md](canvas-strategy-surface.md)). If a future canvas +[canvas-strategy-surface.md](../surfaces/canvas-strategy-surface.md)). If a future canvas surface flushes structured node-edits to chapter files, the write coordination (no-raw-file-editing principle; structured/node-granular operations) will be designed in the V1.68 canvas context; until then orchestration remains the @@ -202,9 +202,9 @@ under the default `~/.nexus42` home. ## 5. ACP role invariant -> **Historical (the daemon runtime is deleted).** The retained invariant: no Nexus local host or CLI advertises itself as an ACP Agent or ACP Server, and the ACP Client role stays on the Nexus control-plane path ([local-runtime-boundary](./local-runtime-boundary.md) §1). Provider SDK adapters in the TS service sit behind Rust ports rather than becoming ACP servers ([rust-core-service-boundary.md](rust-core-service-boundary.md) §6). +> **Historical (the daemon runtime is deleted).** The retained invariant: no Nexus local host or CLI advertises itself as an ACP Agent or ACP Server, and the ACP Client role stays on the Nexus control-plane path ([local-runtime-boundary](../architecture/local-runtime-boundary.md) §1). Provider SDK adapters in the TS service sit behind Rust ports rather than becoming ACP servers ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §6). -Daemon runtime is a **local supervisor**. It is **not** an ACP Agent or ACP Server and must **not** be advertised via ACP Registry as an agent. ACP Client role stays on the Nexus control plane path ([local-runtime-boundary](./local-runtime-boundary.md) §1). +Daemon runtime is a **local supervisor**. It is **not** an ACP Agent or ACP Server and must **not** be advertised via ACP Registry as an agent. ACP Client role stays on the Nexus control plane path ([local-runtime-boundary](../architecture/local-runtime-boundary.md) §1). --- @@ -220,7 +220,7 @@ Daemon runtime is a **local supervisor**. It is **not** an ACP Agent or ACP Serv 1. Specs and docs do not **require** a standalone daemon runtime product binary. 2. Health endpoint reachable after foreground and background start. 3. Stop/restart leaves no orphan runtime without documented force path. -4. Agent-host subsystem can start under Managed-only rules ([agent-host](./agent-host.md)). +4. Agent-host subsystem can start under Managed-only rules ([agent-host](../agents/agent-host.md)). --- @@ -236,7 +236,7 @@ Daemon runtime is a **local supervisor**. It is **not** an ACP Agent or ACP Serv ## 9. Implementation batches -> **Historical (executed record).** These are the V1.55-era build batches that produced the (now deleted) host crate; they are kept as the delivery record. Current cohorts: `cli` (default) and independent `connect-host` ([rust-core-service-boundary.md](rust-core-service-boundary.md) §4.2). +> **Historical (executed record).** These are the V1.55-era build batches that produced the (now deleted) host crate; they are kept as the delivery record. Current cohorts: `cli` (default) and independent `connect-host` ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §4.2). ### Batch 1: Runtime extraction @@ -501,7 +501,7 @@ The scheduler path does NOT set creator context — therefore body.md on-disk wr ### 11.1 Overview -The orchestration engine's `outbox.flush` and `outbox.compact` capabilities are invoked through the standard capability dispatch path (see [orchestration-engine.md](orchestration-engine.md) §5.7). Both are local-only, pool-backed capabilities that operate directly on the unified `outbox_entries` table in `state.db`. +The orchestration engine's `outbox.flush` and `outbox.compact` capabilities are invoked through the standard capability dispatch path (see [orchestration-engine.md](../orchestration/orchestration-engine.md) §5.7). Both are local-only, pool-backed capabilities that operate directly on the unified `outbox_entries` table in `state.db`. ### 11.2 Dispatch path @@ -514,7 +514,7 @@ CapabilityRegistry::get("outbox.flush") / get("outbox.compact") ### 11.3 Single-writer enforcement -The unified outbox follows a single-writer rule per event type (see [outbox-consolidation.md](outbox-consolidation.md) §2): +The unified outbox follows a single-writer rule per event type (see [outbox-consolidation.md](../runtime/outbox-consolidation.md) §2): - **Sync push/pull commands**: written exclusively by `nexus-cloud-sync::outbox::Outbox` (`append`, `stage`, `stage_if_absent`). - **Flush/compact operations**: written exclusively by `nexus-orchestration` capability layer (`OutboxFlush`, `OutboxCompact`). @@ -530,9 +530,9 @@ Both capabilities receive the `sqlx::SqlitePool` through the standard `with_pool ## 12. Tauri sidecar mode (V1.66 — historical record; desktop sidecar retired in v1.192) -> **v1.192 host note (RFT-11):** the Tauri desktop host was retired; the repository has exactly one desktop host — Electron ([desktop-shell.md](desktop-shell.md) §7). The Electron host does **not** bundle or launch `nexus42` as a sidecar: it supervises its own TS service (`@42ch/nexus-service`) in an Electron utility process. The app-ownership, launch and asset-serving clauses below are a historical record of V1.66–V1.191. The daemon-side contract they rested on (`nexus42 daemon start [--foreground]`, port resolution explicit → `NEXUS_DAEMON_PORT` → `8420`, readiness = `GET /v1/daemon/runtime/health`) is **retired with the host in v1.193 P2**: the CLI has no service-launch entry, and the retained equivalents are the TS service's own port/discovery contract ([desktop-shell.md](desktop-shell.md) §7.1) plus the runtime health/status routes it serves. +> **v1.192 host note (RFT-11):** the Tauri desktop host was retired; the repository has exactly one desktop host — Electron ([desktop-shell.md](../surfaces/desktop-shell.md) §7). The Electron host does **not** bundle or launch `nexus42` as a sidecar: it supervises its own TS service (`@42ch/nexus-service`) in an Electron utility process. The app-ownership, launch and asset-serving clauses below are a historical record of V1.66–V1.191. The daemon-side contract they rested on (`nexus42 daemon start [--foreground]`, port resolution explicit → `NEXUS_DAEMON_PORT` → `8420`, readiness = `GET /v1/daemon/runtime/health`) is **retired with the host in v1.193 P2**: the CLI has no service-launch entry, and the retained equivalents are the TS service's own port/discovery contract ([desktop-shell.md](../surfaces/desktop-shell.md) §7.1) plus the runtime health/status routes it serves. -The Tauri desktop shell ([desktop-shell.md](desktop-shell.md)) may bundle the user-facing `nexus42` binary as a sidecar process. This does **not** create a second daemon product binary: the sidecar is still `nexus42`, launched in daemon foreground mode by the desktop app. (Compass: v1.66 §5 #2/#3 LOCKED.) +The Tauri desktop shell ([desktop-shell.md](../surfaces/desktop-shell.md)) may bundle the user-facing `nexus42` binary as a sidecar process. This does **not** create a second daemon product binary: the sidecar is still `nexus42`, launched in daemon foreground mode by the desktop app. (Compass: v1.66 §5 #2/#3 LOCKED.) ### 12.1 Launch contract @@ -544,7 +544,7 @@ nexus42 daemon start --foreground --port Optional flags such as `--cdn-url ` may be passed only when the desktop app has an explicit configuration source for them. **V1.66 does not add a new daemon-lifecycle Daemon API route** (`wire_contracts_changed: false`). -**Port resolution** (compass §5 #3 LOCKED; conventions in [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) §9): +**Port resolution** (compass §5 #3 LOCKED; conventions in [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md) §9): 1. Explicit configured port (if the Tauri bootstrapper provides one). 2. Else `NEXUS_DAEMON_PORT` when present and valid. @@ -593,7 +593,7 @@ In desktop mode, Tauri serves the bundled `apps/web/dist` via `build.frontendDis ## 13. Daemon API Trust-Boundary Security (V1.86) -> **Current owner (v1.193 P2).** The security contract in this section is **retained**; it is enforced today by the standalone TS service — origin allowlist in `apps/nexus-service/src/security.ts::checkOrigin` over the configured list from `config.ts::resolveAllowedOrigins` (own loopback origins, `nexus://app`, loopback Vite dev origins, the `NEXUS_DAEMON_ALLOWED_ORIGINS` escape hatch) — plus the Electron host's exact-origin CSP and IPC sender checks ([desktop-shell.md](desktop-shell.md) §4/§6). The Rust host that originally enforced it (`api/auth_middleware.rs`, `api/path_guard.rs`) was deleted with the crate, so implementation anchors below are historical. +> **Current owner (v1.193 P2).** The security contract in this section is **retained**; it is enforced today by the standalone TS service — origin allowlist in `apps/nexus-service/src/security.ts::checkOrigin` over the configured list from `config.ts::resolveAllowedOrigins` (own loopback origins, `nexus://app`, loopback Vite dev origins, the `NEXUS_DAEMON_ALLOWED_ORIGINS` escape hatch) — plus the Electron host's exact-origin CSP and IPC sender checks ([desktop-shell.md](../surfaces/desktop-shell.md) §4/§6). The Rust host that originally enforced it (`api/auth_middleware.rs`, `api/path_guard.rs`) was deleted with the crate, so implementation anchors below are historical. > **V1.90 note:** The surface was renamed to **Daemon API** and the path prefix to `/v1/daemon/*` in V1.90. The security rules described below apply unchanged to the renamed surface. References to "Local API" in this section title and in V1.86 iteration names are historical only. @@ -603,7 +603,7 @@ This section codifies the normative security contract for the daemon's Daemon AP ### 13.1 Origin allowlist gate -The daemon's CORS configuration is the primary browser-origin trust boundary. Per [STRATEGY.md](../../STRATEGY.md) Guiding Principle #1 ("Local-first privacy"), cross-origin access from arbitrary websites MUST be denied by default. +The daemon's CORS configuration is the primary browser-origin trust boundary. Per [STRATEGY.md](../../../STRATEGY.md) Guiding Principle #1 ("Local-first privacy"), cross-origin access from arbitrary websites MUST be denied by default. #### 13.1.1 Allowlist composition @@ -707,7 +707,7 @@ Both the read (existing-file) and write (non-existing-file) branches MUST be cov ## 14. Daemon API Remote Bind Gate (V1.90) -> **Current owner (v1.193 P2).** §14–§16 are **retained transport contracts** for the `/v1/daemon/*` wire family; the standalone TS service enforces the bind gate, TLS listener and remote-client rules today, and Electron/`DesktopClient` remain the desktop consumer ([desktop-shell.md](desktop-shell.md) §5–§7). Implementation anchors named in these sections belonged to the deleted Rust host. +> **Current owner (v1.193 P2).** §14–§16 are **retained transport contracts** for the `/v1/daemon/*` wire family; the standalone TS service enforces the bind gate, TLS listener and remote-client rules today, and Electron/`DesktopClient` remain the desktop consumer ([desktop-shell.md](../surfaces/desktop-shell.md) §5–§7). Implementation anchors named in these sections belonged to the deleted Rust host. This section codifies the security contract for optional non-loopback binding of the Daemon API listener. The Daemon API is local-first by default; remote access is opt-in only and subject to a two-condition gate. @@ -878,7 +878,7 @@ Example: `SHA256:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee: ## 16. Remote Client Connection Model (V1.92) -This section codifies the client-side contract for connecting to a remote daemon. It is authoritative for both the web SPA (`BrowserClient`) and the desktop shell (`DesktopClient`, renamed from `TauriClient` in v1.192 without aliases; credential injection is main-owned — [desktop-shell.md](desktop-shell.md) §5). The local same-origin mode is the backwards-compatible default; remote access is opt-in per the setup-screen flow. +This section codifies the client-side contract for connecting to a remote daemon. It is authoritative for both the web SPA (`BrowserClient`) and the desktop shell (`DesktopClient`, renamed from `TauriClient` in v1.192 without aliases; credential injection is main-owned — [desktop-shell.md](../surfaces/desktop-shell.md) §5). The local same-origin mode is the backwards-compatible default; remote access is opt-in per the setup-screen flow. ### 16.1 Client transport parameterisation @@ -946,7 +946,7 @@ The daemon's Origin allowlist (§13.1) already covers: own-origin, Tauri webview - The connecting client's origin MUST be added to `NEXUS_DAEMON_ALLOWED_ORIGINS` — there is **no magic auto-allowlisting** of remote origins. - The daemon does not automatically trust the remote bind address as a browser origin; the author controls the allowlist explicitly. - A remote client that sends an `Origin` header not in the allowlist will receive `403 Forbidden` (consistent with §13.1.2), regardless of whether it holds a valid API key or a pinned TLS fingerprint. -- The `tauri://localhost` / `http://tauri.localhost` origins lived only in the deleted Rust allowlist; they are gone and no shipped desktop runtime uses them ([desktop-shell.md](desktop-shell.md) §6 admits exactly `nexus://app`). +- The `tauri://localhost` / `http://tauri.localhost` origins lived only in the deleted Rust allowlist; they are gone and no shipped desktop runtime uses them ([desktop-shell.md](../surfaces/desktop-shell.md) §6 admits exactly `nexus://app`). - A remote web-app (browser SPA connecting to a remote daemon) needs its serving origin in `NEXUS_DAEMON_ALLOWED_ORIGINS`. ### 16.5 Client key storage @@ -954,7 +954,7 @@ The daemon's Origin allowlist (§13.1) already covers: own-origin, Tauri webview | Platform | Storage mechanism | Notes | |----------|-------------------|-------| | Web SPA | `localStorage` | SPA trust boundary equal to the app itself. Key is always user-entered, never compiled in. | -| Desktop (Electron) | Main-process encrypted store (Electron `safeStorage`; atomic replace, owner-only permissions) with a one-time import of the legacy keychain/app-data entry | No plaintext-write fallback; see [desktop-shell.md](desktop-shell.md) §5. | +| Desktop (Electron) | Main-process encrypted store (Electron `safeStorage`; atomic replace, owner-only permissions) with a one-time import of the legacy keychain/app-data entry | No plaintext-write fallback; see [desktop-shell.md](../surfaces/desktop-shell.md) §5. | The API key is always **user-entered** — never compiled into the binary, never stored in version control, never embedded in build artifacts. Full secret-store hardening (hardware-backed keystore, biometric unlock) is a future concern. **Durable roadmap:** DR-05 (secret-store hardening). @@ -1035,7 +1035,7 @@ Implement **`require_active_creator`** (or equivalent) on Tier-2 route groups. T exposure) is locked in V1.174 (AR-66..77); this section is an ADDITIVE V1.179 P0 overlay — it does not rewrite the lock history. -> **Local retirement note (v1.193 P2) — two CLI spellings below are not current instructions.** The Model A bridge `nexus42 mcp serve` (§18.1 item 2) and the enablement flag `nexus42 daemon start --embedded-mcp` (§18.1 item 3) are **deleted**: the whole `nexus42 daemon` group went with the obsolete Rust host, and Model A lost its CLI entry. Both invocations are clap's "unrecognized subcommand" error (exit 2) — the `mcp serve` half asserted by `retired_operator_entrances_are_unknown` (`apps/nexus42/tests/command_surface_contract.rs`, which drives `mcp serve` and `mcp --help`), while the `daemon start --embedded-mcp` half has no test naming it and is **subsumed by the deleted group's assertion**, not asserted by name: `daemon_tree_is_unknown` (same file) drives `daemon start` — among `daemon --help|stop|restart|status|logs|doctor|ui|web`, the `orchestrate run` / `schedule …` leaves, and `daemon-run` — as an unknown subcommand (exit 2), and since `daemon` is already the unknown first token the trailing flag cannot change the outcome. Both deleted names are recorded in [rust-core-service-boundary.md](rust-core-service-boundary.md) §7.2. The rest of this section is retained: the WS registration lane, the `PeerToolsConfig` keys and the core `embedded-mcp` **library** feature survive (only the app-only selector was deleted). Model B enablement is therefore the config key (`~/.nexus42/connect/daemon.json` key `embedded_mcp`, restart-scoped per §18.3) or the TS service's own `--embedded-mcp` argument (`apps/nexus-service/src/config.ts`) — never a `nexus42` operator leaf. +> **Local retirement note (v1.193 P2) — two CLI spellings below are not current instructions.** The Model A bridge `nexus42 mcp serve` (§18.1 item 2) and the enablement flag `nexus42 daemon start --embedded-mcp` (§18.1 item 3) are **deleted**: the whole `nexus42 daemon` group went with the obsolete Rust host, and Model A lost its CLI entry. Both invocations are clap's "unrecognized subcommand" error (exit 2) — the `mcp serve` half asserted by `retired_operator_entrances_are_unknown` (`apps/nexus42/tests/command_surface_contract.rs`, which drives `mcp serve` and `mcp --help`), while the `daemon start --embedded-mcp` half has no test naming it and is **subsumed by the deleted group's assertion**, not asserted by name: `daemon_tree_is_unknown` (same file) drives `daemon start` — among `daemon --help|stop|restart|status|logs|doctor|ui|web`, the `orchestrate run` / `schedule …` leaves, and `daemon-run` — as an unknown subcommand (exit 2), and since `daemon` is already the unknown first token the trailing flag cannot change the outcome. Both deleted names are recorded in [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §7.2. The rest of this section is retained: the WS registration lane, the `PeerToolsConfig` keys and the core `embedded-mcp` **library** feature survive (only the app-only selector was deleted). Model B enablement is therefore the config key (`~/.nexus42/connect/daemon.json` key `embedded_mcp`, restart-scoped per §18.3) or the TS service's own `--embedded-mcp` argument (`apps/nexus-service/src/config.ts`) — never a `nexus42` operator leaf. ### 18.1 Serving & transport topology @@ -1202,7 +1202,7 @@ were deleted with the crate in v1.193 P2.） ## 20. V1.186 product lock — truthful runs and bounded boot recovery -> **Retained contract (v1.193 P2).** These run/recovery rules are **retained product semantics** — they were never daemon-specific, and the engine/storage owners (`nexus-orchestration`, `nexus-local-db`) are unchanged. Only the *host* that performed boot/lazy attach changed: today the standalone TS service under Electron performs readiness and Creator-DB attach ([desktop-shell.md](desktop-shell.md) §7), and `nexus42 ops inspect` is the retained read-only operator surface ([cli-spec.md](./cli-spec.md) §6.3B). The `/v1/daemon/orchestration/sessions/{run-id}/events` route in §20.2 is part of the retained wire family served by the TS service. +> **Retained contract (v1.193 P2).** These run/recovery rules are **retained product semantics** — they were never daemon-specific, and the engine/storage owners (`nexus-orchestration`, `nexus-local-db`) are unchanged. Only the *host* that performed boot/lazy attach changed: today the standalone TS service under Electron performs readiness and Creator-DB attach ([desktop-shell.md](../surfaces/desktop-shell.md) §7), and `nexus42 ops inspect` is the retained read-only operator surface ([cli-spec.md](../cli/cli-spec.md) §6.3B). The `/v1/daemon/orchestration/sessions/{run-id}/events` route in §20.2 is part of the retained wire family served by the TS service. **Status:** Shipped V1.186; V1.188 reliability amendments are recorded below. @@ -1215,7 +1215,7 @@ Runtime responsibilities: 1. **Durable store and inspect.** `orchestration_sessions.status` is authoritative for versioned new-run records, with revision-fenced atomic status/checkpoint/metadata transitions; position saves never force running over newer terminal/wait state. Legacy/unreadable records are distinguished, not silently upgraded to success. Existing daemon-free `ops inspect` remains read-only and shares the recovery classifier with boot; public session lookup reads persisted terminals even without a live runner. 2. **One coordinator, including lazy attach.** Public session creation and schedule admission enqueue the same bounded drive owner. Boot and lazy Creator-DB attach publish a matching storage/engine/coordinator bundle before readiness. User runs require a durable Creator DB; do not fall back to an in-memory user workflow. Descriptor/input/core seed and schedule→session association commit before enqueue. Repeated admission returns the same owned run, and terminal reconciliation does not duplicate auto-chain children. 3. **Explicit cutover.** An additive schedule execution_policy defaults historical rows to legacy_inert; new user/cron/auto-chain admissions explicitly select driven_v1. Boot/tick/cron exclude legacy never-started pending/running/paused rows; missing session ID or creation time is not automatic opt-in. Explicit public schedule start revalidates and opts only that row in. `_system.maintenance` is system_inert, never queued for user Host work, and generic public start cannot opt it in. -4. **Wait and cancellation.** Human wait_id and root/child checkpoint survive restart with no implicit approval. Token consumption and terminal/cancel races use one durable revision fence. Cancel reaches the actual Host operation independently of a long-running step lock, fences subsequent work and performs bounded owned-child cleanup. Only confirmed stop yields cancelled; unconfirmed cleanup stays interrupted. Wire errors and wait semantics are owned by [orchestration-engine.md](orchestration-engine.md) §15; Host process ownership by [agent-host.md](agent-host.md) §4. +4. **Wait and cancellation.** Human wait_id and root/child checkpoint survive restart with no implicit approval. Token consumption and terminal/cancel races use one durable revision fence. Cancel reaches the actual Host operation independently of a long-running step lock, fences subsequent work and performs bounded owned-child cleanup. Only confirmed stop yields cancelled; unconfirmed cleanup stays interrupted. Wire errors and wait semantics are owned by [orchestration-engine.md](../orchestration/orchestration-engine.md) §15; Host process ownership by [agent-host.md](../agents/agent-host.md) §4. 5. **Recovery before drive.** In-flight dispatch intent/uncertain effects take precedence over old join keys and are not replayed. Terminal rows do not run; waits stay waiting; shipped converge/merge deadlines retain downtime-aware bounded resume. Supported new embedded/user/system presets reconstruct existing IDs/cursors from frozen matching source/template identity with production dependencies. Changed/missing source or unsupported child identity refuses with an actionable reason, not an embedded fallback or fresh run. Checkpoint position is not an effects ledger; exactly-once arbitrary effects remain a non-goal. 6. **Honest isolated live QA.** Nexus CLI home resolves through `HOME/.nexus42`; `NEXUS_HOME` in a recipe denotes that path, not a newly supported CLI environment override. All Nexus processes in QA must resolve the same temp config/DB tree; any runtime NEXUS42_HOME override must equal it. External omp gets a separate temporary HOME/XDG/profile and the admitted Creator workspace cwd through generic ProviderConfig `omp acp` argv. No user-global config/auth reads or writes; use auth already in the isolated profile or injected by the harness. Only installed live-provider output through public workflow admission proves live success; deterministic protocol processes prove races/failures/restarts. @@ -1226,14 +1226,14 @@ into Host start and binds the same verified Creator/canonical-workspace context used by admission. Malformed structural configuration fails closed. Config, PATH and registry candidates share one factory and manager health authority; no ambient-only registration or blanket-ready projection remains. Bounded -no-model probes and safe diagnostics are defined in [agent-host.md](agent-host.md) +no-model probes and safe diagnostics are defined in [agent-host.md](../agents/agent-host.md) §6–§8. The daemon binds one retained workspace authority to HTTP and orchestration. It recovers durable content intents before new writes and keeps admitted recovery alive across request/workflow cancellation. The target-content wire, pre-image OCC, stable revision and exceptional conflict boundary are defined -in [concurrency.md](concurrency.md) §9. +in [concurrency.md](../runtime/concurrency.md) §9. ### 20.2 V1.188 bounded same-run event replay diff --git a/.mstar/specs/local-api-surface-conventions.md b/.mstar/specs/archived/local-api-surface-conventions.md similarity index 85% rename from .mstar/specs/local-api-surface-conventions.md rename to .mstar/specs/archived/local-api-surface-conventions.md index 1b989bf95..f17f75068 100644 --- a/.mstar/specs/local-api-surface-conventions.md +++ b/.mstar/specs/archived/local-api-surface-conventions.md @@ -1,6 +1,6 @@ # Redirect stub -> **Renamed in V1.90.** This file has been renamed to **[daemon-api-surface-conventions.md](daemon-api-surface-conventions.md)**. +> **Renamed in V1.90.** This file has been renamed to **[daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md)**. > > The surface was renamed from "Local API" to "Daemon API" and the path prefix from `/v1/local/` to `/v1/daemon/`. All normative conventions continue to apply unchanged to the renamed surface. diff --git a/.mstar/specs/local-cloud-crate-architecture.md b/.mstar/specs/archived/local-cloud-crate-architecture.md similarity index 82% rename from .mstar/specs/local-cloud-crate-architecture.md rename to .mstar/specs/archived/local-cloud-crate-architecture.md index e89e35fe4..b5dc2c1d0 100644 --- a/.mstar/specs/local-cloud-crate-architecture.md +++ b/.mstar/specs/archived/local-cloud-crate-architecture.md @@ -4,11 +4,13 @@ | Attribute | Value | | --- | --- | -| **Status** | Active — V1.64 amendment: local Web UI workspace member + embedded asset edge | +| **Status** | **Historical crate-graph record (v1.193 P2).** The integrated daemon host and `nexus-daemon-runtime` crate were deleted; current topology authority is [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md). | | **Document class** | Master | -| **Scope** | Stable rules: local vs cloud product lines, crate responsibilities, contracts usage, dependency forbidden edges, current-vs-target wiring, Daemon API *classes* allowed/forbidden | -| **Scope model SSOT** | [entity-scope-model.md](./entity-scope-model.md) — authoritative for scope hierarchy, crate ownership, and `kb`/`knowledge` naming boundaries | -| **Related** | [entity-scope-model.md](./entity-scope-model.md), [local-runtime-boundary.md](./local-runtime-boundary.md), [daemon-runtime.md](./daemon-runtime.md), [cli-spec.md](./cli-spec.md), [schemas-directory-layout.md](./schemas-directory-layout.md), [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) | +| **Scope** | Historical local/cloud rules, crate responsibilities, contracts usage, dependency edges, current-vs-target wiring, and Daemon API classes; not the current workspace inventory or host topology. | +| **Scope model SSOT** | [entity-scope-model.md](../architecture/entity-scope-model.md) — authoritative for scope hierarchy, crate ownership, and `kb`/`knowledge` naming boundaries | +| **Related** | [entity-scope-model.md](../architecture/entity-scope-model.md), [local-runtime-boundary.md](../architecture/local-runtime-boundary.md), [daemon-runtime.md](daemon-runtime.md), [cli-spec.md](../cli/cli-spec.md), [schemas-directory-layout.md](../architecture/schemas-directory-layout.md), [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md) | + +> **Historical as of v1.193 P2.** Sections §1–§9 retain the earlier crate-graph and product-integration record; “current”, “target”, and daemon ownership below refer to that record, not today's implementation. The retained `/v1/daemon/*` wire families are served by the standalone TypeScript service, `apps/nexus-service`, over Rust core authority, not by `nexus42 daemon`. Current topology: [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md). Current crate inventory and responsibilities: root [`AGENTS.md`](../../../AGENTS.md) and each crate's `AGENTS.md`, with workspace membership in root `Cargo.toml`. **This file is not an implementation checklist.** Do not add migration batches, branch names, or “done by V1.21” task tables here — put those in the matching **iteration compass** and local plan documents (harness process artifacts, not tracked specs). @@ -18,6 +20,8 @@ ## 1. Two product lines (frozen) +> **Historical host assignment.** The `nexus42 daemon` integration surface and `nexus-daemon-runtime` isolation edge below describe the deleted host; the local/cloud product separation does not reinstate it. + | Line | Purpose | Integration surface | | --- | --- | --- | | **Local product** | Orchestration, agent-host, workspace, Creator + Creator memory, World-scoped narrative KB, User-scoped knowledge, narrative graph, Moment context assembly | `nexus42 daemon` → `/v1/daemon/*` | @@ -35,7 +39,7 @@ ## 2. Contracts boundary (frozen) -External wire shapes come from the **`nexus-contracts`** crate's generated modules under `src/generated/`, sourced from `schemas/` (layout: [schemas-directory-layout.md](./schemas-directory-layout.md)). Shared Rust-only DTOs live under `src/local/` per [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md). +External wire shapes come from the **`nexus-contracts`** crate's generated modules under `src/generated/`, sourced from `schemas/` (layout: [schemas-directory-layout.md](../architecture/schemas-directory-layout.md)). Shared Rust-only DTOs live under `src/local/` per [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md). | Rule | Detail | | --- | --- | @@ -51,7 +55,11 @@ External wire shapes come from the **`nexus-contracts`** crate's generated modul ## 3. Crate responsibility and scope ownership -This table follows [entity-scope-model.md §4](./entity-scope-model.md#4-crate-ownership-map). If older wording conflicts with that model, the entity scope model is authoritative. +> **Historical inventory.** Preserve this inventory and the 2026-05-22 Cargo snapshot in §4 as recorded, including the now-deleted daemon crate; neither is a current workspace list. + +Post-2026-05 workspace additions — `nexus-core`, `nexus-core-node`, `nexus-preset`, `nexus-provider-conformance`, `nexus-provider-ports`, and `nexus-storage-guard` — are indexed with their per-crate `AGENTS.md` roles in [rust-core-service-boundary.md §2](../architecture/rust-core-service-boundary.md#current-workspace-boundary-inventory); they are not backfilled into this frozen inventory. + +This table follows [entity-scope-model.md §4](../architecture/entity-scope-model.md#4-crate-ownership-map). If older wording conflicts with that model, the entity scope model is authoritative. ### 3.1 Foundation (types & paths) @@ -82,6 +90,8 @@ These crates are **not** split by the local/cloud program; they sit **under** al ### 3.2A Local Web UI app (V1.64) +> **Historical serving model (retired in v1.193 P2).** The `rust-embed`/daemon-router edge below is deleted, not a current build or serving instruction. Current browser/desktop host boundaries are in [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) and [desktop-shell.md](../surfaces/desktop-shell.md). + | App | Product line | Responsibility boundary | Cloud/platform dep? | | --- | --- | --- | --- | | **`apps/web`** | Local product | Browser SPA for Control Room + Setup. Consumes daemon `/v1/daemon/*` via `@42ch/nexus-contracts` generated TS types and a `NexusClient` transport boundary. Build output (`dist/`) is served by the daemon in release and proxied to the daemon in dev. | **No** direct platform/cloud dependency; no private `nexus-platform` imports or assumptions. | @@ -94,7 +104,7 @@ apps/web (Vite build → dist/) └─ nexus42 binary / nexus-daemon-runtime router static serving ``` -`rust-embed` is a build-time/static-asset edge only. It does not make the Web UI an owning Rust crate and does not permit the frontend to bypass the Daemon API. `tower-http::ServeDir`-style serving may expose the unauthenticated SPA shell, but data remains behind `/v1/daemon/*` auth boundaries (see [daemon-runtime.md](./daemon-runtime.md) §4.4). +`rust-embed` is a build-time/static-asset edge only. It does not make the Web UI an owning Rust crate and does not permit the frontend to bypass the Daemon API. `tower-http::ServeDir`-style serving may expose the unauthenticated SPA shell, but data remains behind `/v1/daemon/*` auth boundaries (see [daemon-runtime.md](daemon-runtime.md) §4.4). ### 3.3 Why `nexus-cloud-domain` (not `nexus-domain`) @@ -125,6 +135,8 @@ The legacy crate name `nexus-domain` is **not** retained after the split program ### 3.6 `nexus-moment-context-assembly` +> **Historical product status.** The daemon route/default-build claims below belong to the retired host; retained TS-service context routes and Rust owners are described in [rust-core-service-boundary.md §7.5](../architecture/rust-core-service-boundary.md#75-family-destinations-program-keys-not-extra-iterations). + - **Shipped local four-domain Moment path (V1.26+, SSOT V1.28):** `assemble_moment` depends on `nexus-creator-memory`, `nexus-narrative`, `nexus-knowledge`, and `nexus-contracts`. (The former `nexus-kb` crate was merged into `nexus-knowledge` in V1.139.) `nexus42 platform context assemble-moment` is the **single** local assembly command; it calls `assemble_moment` in-process with persistent narrative / World KB / User knowledge stores (SQLite User knowledge since V1.27). - **Stage0 / TwoStage on assemble-moment (V1.28):** `--max-tokens`, `--no-fragments`, `--hint`, and runtime/degradation routing are flags on `assemble-moment`, not a separate subcommand. - **Removed path:** `nexus42 platform context assemble-local` was removed in V1.28 (pre-release breaking change). @@ -148,7 +160,9 @@ cloud-stage = ["dep:nexus-cloud-sync"] --- -## 4. Currently wired Cargo graph (verified 2026-05-22) +## 4. Historical Cargo graph (snapshot verified 2026-05-22) + +> **Frozen historical snapshot.** The original table, diagram, and “current” claims below are preserved verbatim as the 2026-05-22 record, not a graph to build today; `nexus-daemon-runtime` and its embedded-SPA edge were deleted in v1.193 P2. This section describes the current `Cargo.toml` and `cargo tree` reality. It is intentionally separate from product integration gaps in §6 and the V1.24 audit compass. @@ -210,6 +224,8 @@ nexus-cloud-sync ──► nexus-cloud-domain, nexus-contracts, nexus-home-layou ## 5. V1.23 dependency wiring target (achieved for Cargo edges) +> **Historical V1.23 target and results.** “Current Cargo shape”, “already wired”, and daemon constraints below are statements at that milestone, not current runtime ownership. + The following graph was the normative V1.23 dependency target and is now the current Cargo shape for the alignment-sensitive edges. Remaining gaps are product integration gaps, not missing Cargo dependencies. ### 5.1 Target dependency shape @@ -267,6 +283,8 @@ nexus-moment-context-assembly (default four-domain library target) ## 6. Daemon API (principles) +> **Historical router authority.** `crates/nexus-daemon-runtime/src/api/mod.rs` below was deleted with its crate in v1.193 P2. Current retained route composition is [`apps/nexus-service/src/routes.ts`](../../../apps/nexus-service/src/routes.ts) and its family modules; domain/effect ownership is Rust core. The V1.24 gap list below remains a historical audit record, not a list of today's missing routes. + Authoritative route list for a given release lives in **`crates/nexus-daemon-runtime/src/api/mod.rs`** and the active **iteration compass**. **Always allowed (local product):** runtime health/status, workspace, local creator listing/active/logout, local references, work-scope KB file-index APIs, memory pending-review, presets, orchestration, and agent-host (+ internal tool execution). Future World KB / User knowledge / Moment context surfaces may be local-only, but must be explicitly registered and documented (DR-46); after KCA-002 B2, daemon context assembly is not an active Daemon API route. @@ -289,6 +307,8 @@ These are runtime/product gaps after Cargo alignment, not missing dependency edg ## 7. CLI integration (principles) +> **Historical CLI assignment.** The daemon-control row below records the deleted CLI/API integration; current CLI disposition is [rust-core-service-boundary.md §7.2](../architecture/rust-core-service-boundary.md#72-operator--service-lifecycle), with no TS-service launcher alias. + | Concern | Owner | | --- | --- | | Daemon control | Daemon API | @@ -302,6 +322,8 @@ These are runtime/product gaps after Cargo alignment, not missing dependency edg ## 8. Orchestration +> **Historical daemon-build policy.** No daemon build survives v1.193 P2; current execution/transport ownership is defined in [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md). + Built-in `sync.*` / `outbox.flush` capabilities on **daemon builds** MUST NOT call cloud-sync; stubs or explicit “cloud line disabled” results are acceptable until cloud orchestration is redesigned. Workspace file writes remain agent-mediated (agent-host internal tool execution); unchanged principle from preset-driven architecture. @@ -310,8 +332,10 @@ Workspace file writes remain agent-mediated (agent-host internal tool execution) ## 9. Cloud runtime policy +> **Historical host wording.** “Daemon hot path” below refers to the retired host, not a surviving process mode. + `runtime_mode`, `degradation`, and platform health probing belong to the **cloud line** (CLI / `cloud-stage` builds), not the daemon hot path. --- -*Long-term SSOT for local/cloud crate and Daemon API boundaries.* +*Historical local/cloud crate and Daemon API boundary record; current topology SSOT: [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md).* diff --git a/.mstar/specs/reading-chrome-profile-checklist.md b/.mstar/specs/archived/reading-chrome-profile-checklist.md similarity index 93% rename from .mstar/specs/reading-chrome-profile-checklist.md rename to .mstar/specs/archived/reading-chrome-profile-checklist.md index 4b43513bb..4c033fae8 100644 --- a/.mstar/specs/reading-chrome-profile-checklist.md +++ b/.mstar/specs/archived/reading-chrome-profile-checklist.md @@ -2,7 +2,8 @@ > **Version**: V1.91 — locked in P-1 Prepare. > **Status**: Historical shipped acceptance record. The behavioral bar and profile coverage below remain the V1.91 record; the named visual values (for example "Georgia serif", weight 700, literal tints) were superseded by later DESIGN revisions. This file is not a live value authority. -> **Active design authority**: repo-root [`DESIGN.md`](../../DESIGN.md) / [`DESIGN.dark.md`](../../DESIGN.dark.md) frontmatter `components.reading-chrome-*` tokens. The `## Reading Chrome` body section originally cited here no longer exists in either DESIGN file. +> **Document class**: Legacy scope +> **Active design authority**: repo-root [`DESIGN.md`](../../../DESIGN.md) / [`DESIGN.dark.md`](../../../DESIGN.dark.md) frontmatter `components.reading-chrome-*` tokens. The `## Reading Chrome` body section originally cited here no longer exists in either DESIGN file. > **Purpose**: Acceptance bar for P0 implementation of profile-specific reading chrome. > **Fallback rule**: unknown `work_profile` values render as `novel` chrome. diff --git a/.mstar/specs/cli-spec.md b/.mstar/specs/cli/cli-spec.md similarity index 95% rename from .mstar/specs/cli-spec.md rename to .mstar/specs/cli/cli-spec.md index 3bb31c957..e86e1d53a 100644 --- a/.mstar/specs/cli-spec.md +++ b/.mstar/specs/cli/cli-spec.md @@ -2,16 +2,16 @@ **Status**: Normative — V1.51 Shipped (T-A P0/P1/P2 KB CLI amendments folded into Master) **Document class**: Master -**V1.35 shipped supplements:** [cli-command-ia.md](cli-command-ia.md) (§6 IA rationale), [creator-centric-entry-model.md](creator-centric-entry-model.md) (§7 entry paths) +**V1.35 shipped supplements:** [cli-command-ia.md](../archived/cli-command-ia.md) (§6 IA rationale), [creator-centric-entry-model.md](../archived/creator-centric-entry-model.md) (§7 entry paths) **V1.40 Shipped amendments:** §6.2G `nexus42 creator world create --title`/`list`/`show` (mandatory world binding; `--name` is alias); §6.x `nexus42 creator kb queue-extract --chapter N` sugar for novel profile (N ≥ 1). **V1.41 Shipped amendments:** §6.2H `creator works` (list/status/use/pool); completion-lock + runtime lock (DF-60/61). Lineage via `--from-work` migrated to `creator works use` + `creator run ` in V1.45 (`creator run` was removed in v1.193 P2 — §6.2D is historical). **V1.44 Shipped amendments:** §6.2D `creator run audit-chapter` (DF-69): dual-mode review/extract, embedded `novel-manuscript-audit` preset, `--mode`/`--chapter`/`--volume`/`--json` flags; does NOT enter FL-E auto-chain driver (**the runner itself was removed in v1.193 P2**). -**V1.45 Shipped amendments:** §6.2D generic `creator run ` — see [creator-run-preset-entry.md](creator-run-preset-entry.md) (**Shipped Master**); legacy subcommand enum removed from clap surface (**the runner lost its CLI entry in v1.193 P2; the Master is the version history of that pre-retirement surface**). -**V1.46 Shipped amendment:** §6.2E FL-E stage subcommand block deleted (superseded by V1.45 generic preset runner — see changelog). Normative CLI IA: [creator-run-preset-entry.md](creator-run-preset-entry.md). +**V1.45 Shipped amendments:** §6.2D generic `creator run ` — see [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (**Shipped Master**); legacy subcommand enum removed from clap surface (**the runner lost its CLI entry in v1.193 P2; the Master is the version history of that pre-retirement surface**). +**V1.46 Shipped amendment:** §6.2E FL-E stage subcommand block deleted (superseded by V1.45 generic preset runner — see changelog). Normative CLI IA: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md). **V1.51 Shipped amendments:** §6.2K `creator world kb adopt` LLM metadata surfaces; `creator kb rescan --work ` cross-chapter reconciliation; `creator world kb pending --missing-only` (T-A P0/P1/P2). **V1.52 Shipped amendments:** §6.2G.1 `creator world kb adopt --auto` + §6.2G.2 Legacy `creator kb --scope world` alias + deprecation for World KB CLI surface consolidation (closes R-V150KBED-01); both sections promoted to Normative (V1.158). **(The `--scope world` alias itself was deleted in v1.193 P2 — §6.2G.2 is now a historical record.)** **V1.54 P0 Draft overlay:** §6.2M ACP host write-tool CLI mappings — 6 new mutation-capable `nexus.*` host tools map to `creator world kb edit/adopt`, `creator world configure`, `creator works cron set`, `creator findings resolve`, and `creator pool` entry management (DF-46). -**V1.64 P3 Draft overlay (retired in v1.193 P2):** §6.3 daemon Web UI serving — `daemon start` logged the Web UI URL; the `daemon ui`/`daemon web` convenience command and the §7.1 first-run step are deleted. See also [web-ui.md](./web-ui.md) §11 and [daemon-runtime.md](./daemon-runtime.md) §4.4 (historical host spec — its crate was deleted in v1.193 P2). +**V1.64 P3 Draft overlay (retired in v1.193 P2):** §6.3 daemon Web UI serving — `daemon start` logged the Web UI URL; the `daemon ui`/`daemon web` convenience command and the §7.1 first-run step are deleted. See also [web-ui.md](../surfaces/web-ui.md) §11 and [daemon-runtime.md](../archived/daemon-runtime.md) §4.4 (historical host spec — its crate was deleted in v1.193 P2). **V1.65 Prepare amendment:** outline and chapter-structure editing becomes UI-first through the bundled Web UI chapter-content Daemon API. CLI parity for existing creator/run/chapter workflows is retained; no shipped CLI command is removed or renamed by this UI-first slice. **V1.175 P1 amendment:** §6.2G.3-6 — reading / fork / inspector leaves (groups 3, 5, 6), strategy patch leaves (group 1), outline/timeline/chapter leaves (group 2), KB entity patch + memory closure + findings triage (groups 4, 7, 8). Thin daemon-HTTP leaves over existing routes (AR-83); no daemon route changes. **Retargeted in v1.193 P2:** the leaves survive as direct-core calls — see the delivered notes in §6.2G.3–G.6. **V1.182 P1 amendment:** §6.3B — hidden `nexus42 ops inspect [SESSION_ID] [--json]` operator group (BL-04): daemon-free read-only checkpoint projection with shared `resume_rules`; never triggers resume. @@ -27,7 +27,7 @@ The target removes `creator run`, `creator bootstrap`, `creator works intake|res Retain real local `creator demo-seed`, `creator world event-add`, chronology `set|show|advance`, Work/pool inspiration, holder-governed Character CRUD/bindings/knowledge/memory/ToM, reading and directives. Remove deprecated `creator kb --scope world`, World create `--name`, `system preset`, hidden top-level `sync`, and obsolete `preset validate --offline`; use canonical World KB, `--title`, `preset`, `platform sync`, and positional `preset validate `. No silent no-op aliases are retained. Graph/entity patch keeps its existing `--expected-version`; Character edits keep explicit revision CAS. -Ordinary CLI uses the shipped `cli` default cohort; optional `connect-host` is independent. The existing Connect runtime explicitly retains scoped compute/WASM with its shared module cache but no ACP/agent-host, scheduler startup, HTTP/SPA or Node. Core Model B/MCP libraries remain; the removed Model A child descriptor is not replaced with a TS launcher. See [rust-core-service-boundary.md](rust-core-service-boundary.md) §4.2 for the dependency and lifetime contract. +Ordinary CLI uses the shipped `cli` default cohort; optional `connect-host` is independent. The existing Connect runtime explicitly retains scoped compute/WASM with its shared module cache but no ACP/agent-host, scheduler startup, HTTP/SPA or Node. Core Model B/MCP libraries remain; the removed Model A child descriptor is not replaced with a TS launcher. See [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §4.2 for the dependency and lifetime contract. ## 0. 文档定位 @@ -61,7 +61,7 @@ Ordinary CLI uses the shipped `cli` default cohort; optional `connect-host` is i ### 0.1 品牌、CLI 名称与版本节奏 - **产品名**：对外统一为 **Nexus**。 -- **CLI 可执行名**：**`nexus42`**（与 **42ch / Creative Hub** 品牌同源；下文命令示例一律使用 `nexus42`）。**Retired (v1.193 P2):** 本地 daemon 的 single-binary runtime mode（`nexus42 daemon start` → hidden `daemon-run`）已删除；不引入第二个 CLI 产品二进制（`nexus-runtime` 仍是同一 `nexus42` crate 的独立 Connect-host 二进制，见 [daemon-runtime.md](./daemon-runtime.md) §4.6）；Electron/TS 持有长期运行的服务进程。 +- **CLI 可执行名**：**`nexus42`**（与 **42ch / Creative Hub** 品牌同源；下文命令示例一律使用 `nexus42`）。**Retired (v1.193 P2):** 本地 daemon 的 single-binary runtime mode（`nexus42 daemon start` → hidden `daemon-run`）已删除；不引入第二个 CLI 产品二进制（`nexus-runtime` 仍是同一 `nexus42` crate 的独立 Connect-host 二进制，见 [daemon-runtime.md](../archived/daemon-runtime.md) §4.6）；Electron/TS 持有长期运行的服务进程。 - **`v1-notes/ideas/` 与 `v1-notes/` 的扩展需求**：视为路线图输入。CLI 必须保证：**协议与 schema 的可扩展字段**、保留的 `/v1/daemon/*` wire 家族（由 TS 服务提供，见 §6.7）/ ACP 能力面的**演进位**、以及已写入合同的能力（如 **`research.*` 等 ACP 能力名**、context assembly、`manuscript_phase` 等）的**最小可用实现或安全默认（no-op）**，避免把后续实现空间钉死。 ### 0.2 V2 重定位（pre-release） @@ -201,7 +201,7 @@ CLI 不默认同步： - 顶层命令尽量面向用户意图，而不是内部模块 - 关键命令必须稳定、可脚本化 -**Command-surface lock (V1.35, superseded in v1.193 P2):** **Historical:** the V1.35 ordinary help advertised five groups: `creator` / `daemon` / `acp` / `platform` / `system`. **Delivered (v1.193 P2):** `daemon` is deleted; the visible lock is `creator` / `acp` / `platform` / `system` (plus feature-gated `connect`). Hidden retained groups are `preset`, `compute`, `capability`, `ops` and `desktop`; a leaf inside a retained group is removed when it has no complete direct core, cloud or Connect operation. Top-level `nexus42 sync` and `system preset` aliases are removed, together with the dormant stubs and compatibility spellings listed below. Authority for *which leaf stays* is the delivered v1.193 overlay and the retain/remove rules in [rust-core-service-boundary.md](rust-core-service-boundary.md) §7, not the historical lock sentence above. +**Command-surface lock (V1.35, superseded in v1.193 P2):** **Historical:** the V1.35 ordinary help advertised five groups: `creator` / `daemon` / `acp` / `platform` / `system`. **Delivered (v1.193 P2):** `daemon` is deleted; the visible lock is `creator` / `acp` / `platform` / `system` (plus feature-gated `connect`). Hidden retained groups are `preset`, `compute`, `capability`, `ops` and `desktop`; a leaf inside a retained group is removed when it has no complete direct core, cloud or Connect operation. Top-level `nexus42 sync` and `system preset` aliases are removed, together with the dormant stubs and compatibility spellings listed below. Authority for *which leaf stays* is the delivered v1.193 overlay and the retain/remove rules in [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §7, not the historical lock sentence above. > **Legacy (V1.16–V1.34)**：六组含独立 `sync` — superseded by cli-command-ia.md when V1.35 P2 ships. @@ -217,7 +217,7 @@ CLI 不默认同步： ### 6.0B V2 命令信息架构（权威） -V2 命令面按以下顶层执行（pre-release 允许破坏性调整）。**V1.35 SSOT**：[cli-command-ia.md](cli-command-ia.md)。 +V2 命令面按以下顶层执行（pre-release 允许破坏性调整）。**V1.35 SSOT**：[cli-command-ia.md](../archived/cli-command-ia.md)。 - `nexus42 creator`：**Creator 身份 hub** — Work（`works` 子命令组）、workspace、SOUL、memory、kb/knowledge、world（默认用户创意入口）。**v1.193 target:** `creator run` / `creator bootstrap` 执行入口删除；Work/World/Character 的直连 core 读写保留 - `nexus42 daemon`：**Retired (v1.193 P2)** — 整组删除（生命周期与编排运行控制、`schedule` 控制面），无 launcher / status / ui 别名 @@ -253,7 +253,7 @@ V2 命令面按以下顶层执行（pre-release 允许破坏性调整）。**V1. 与 **User** 会话并列，平台将 **Creator** 作为独立认证主体：**独立注册**（可无 User）、**统一** `creator_id` + **`creator_api_key`**（HTTPS，`Authorization: Bearer`）+ **`api_key_ref`**（落库引用 / ACP 侧，不明文存完整密钥）（见 nexus-platform `v1-spec/platform/auth-session-model-v1.md` §1.1、§2.2–§2.5）、再经 **Pairing** 可选绑定 User。HTTP 资源见 nexus-platform `v1-spec/platform/platform-api-v1.md` §1.1、§1.5、§3.0、§3、§3A。 - **HTTP 层（合同一致）**：**同一路由**的 JSON body / 成功响应 **不因**使用 User 还是 Creator 凭证而变；差别只在头。**User** 调用 Sync / Context / Publish 等 **Creator-context** 接口时须带 **`X-Creator-Id`**，且与 body 内 `creator_id`（若有）一致（`platform-api` §1.5、`auth-session-model` §4.0–§4.1）。**Creator** 仅带 **`Authorization: Bearer `** 即可解析 `creator_id`，**不要**求 `X-Creator-Id`（§4.2）。业务层始终按 **Creator 对世界与资源的权限**校验。 -- **独立注册**：对齐 **`POST /api/v1/creators/register`**；注册前可用 **`nexus42 acp probe`** 采集能力与传输元数据（[`registry-integration.md`](./registry-integration.md) §2.1）。 +- **独立注册**：对齐 **`POST /api/v1/creators/register`**；注册前可用 **`nexus42 acp probe`** 采集能力与传输元数据（[`registry-integration.md`](../agents/registry-integration.md) §2.1）。 ### 6.2B `nexus42 creator` 身份子命令（权威） @@ -350,7 +350,7 @@ V2 命令面按以下顶层执行（pre-release 允许破坏性调整）。**V1. | Retired command | Purpose it had | | --- | --- | | `nexus42 creator workspace clone ` | Hidden hard-deprecated World clone — World cloning was platform-only, so the leaf never had a local operation. `retired_creator_workspace_clone_is_unknown` (`apps/nexus42/tests/integration.rs`) asserts the leaf itself plus its `--help` / `--source` / `--dry-run` spellings as unknown, and pins `list` / `create` / `use` / `init` as the retained help surface | -| `nexus42 creator workspace link` / `unlink` | 绑定/解绑本地项目与平台 World — a callable-but-incomplete leaf in the pre-v1.193 overlay that lost its CLI entry in v1.193 P2 ([rust-core-service-boundary.md](./rust-core-service-boundary.md) §7.4) | +| `nexus42 creator workspace link` / `unlink` | 绑定/解绑本地项目与平台 World — a callable-but-incomplete leaf in the pre-v1.193 overlay that lost its CLI entry in v1.193 P2 ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §7.4) | | `nexus42 creator workspace status` | 当前 workspace 总览 — a callable-but-incomplete leaf in the pre-v1.193 overlay that lost its CLI entry in v1.193 P2 | 说明： @@ -384,7 +384,7 @@ V2 命令面按以下顶层执行（pre-release 允许破坏性调整）。**V1. **V1.40 P2 note (surface updated to the delivered form)**: To debug the World context block injected into `novel-writing` prompts, use the canonical World KB surface `nexus42 creator world kb list|show --world-id ` (the historical `creator kb --scope world` spelling is deleted — §6.2G.2). No new subcommand is needed; the prompt-time block is assembled by `nexus-moment-context-assembly` (`build_chapter_kb_block`) and passed as `world_kb_block` template var. -`creator kb` scope 约束（对齐 [`entity-scope-model.md`](./entity-scope-model.md) §5.3）： +`creator kb` scope 约束（对齐 [`entity-scope-model.md`](../architecture/entity-scope-model.md) §5.3）： - **`--scope work`（唯一 scope；V1.23 保留，V1.24 KCA-003 C2 强化为唯一已实现 scope）**：表示活跃 `creator_id` + 活跃 `workspace_slug` 下的 **CLI local work KB index**。**Delivered (v1.193 P2):** 实现直接读 `$HOME/.nexus42/creators//workspaces//...` 下的本地文件 / `index.json` 工作索引——原 daemon local API 优先路径（`/v1/daemon/kb/entries`）已随 daemon 删除，无 HTTP 回退。它是工作资料/文件索引，**不是** `nexus-kb` 的 World graph，**也不是** `nexus-knowledge` 的 User/global knowledge index。V1.24 的 daemon handler (`handlers/kb.rs`) 和 CLI (`creator kb`) 均已明确标注为 work-scope only。 - **`--scope world`（retired alias — deleted in v1.193 P2；historical V1.27+ shipped）**：曾要求可解析的 `world_id`（显式 flag 或当前 workspace binding）并路由到 `nexus-narrative` + `nexus-knowledge`，查询 World-scoped narrative KB assets（KnowledgeEntries、SourceAnchors、graph/query primitives），且不得回退到 work-scope 文件索引。**Delivered:** 该 scope 现在只通过 canonical `nexus42 creator world kb ...` 暴露（§6.2G.2）；`creator kb` 只服务 work-scope 文件索引。 @@ -398,7 +398,7 @@ V2 命令面按以下顶层执行（pre-release 允许破坏性调整）。**V1. ### 6.2E KB / knowledge 术语禁用简写 -在本规格及后续架构 / 实现文档中，`KB` 一词必须按 [`entity-scope-model.md`](./entity-scope-model.md) §5.4 限定语义后使用： +在本规格及后续架构 / 实现文档中，`KB` 一词必须按 [`entity-scope-model.md`](../architecture/entity-scope-model.md) §5.4 限定语义后使用： - **World KB** / **narrative KB**：指 `nexus-knowledge` 所有的 World-scoped narrative KB graph（KnowledgeEntries、SourceAnchors、graph insertion/query），由 `nexus-narrative` 协调 World/Timeline/Event 语境。 - **User knowledge** / **global knowledge index**：指 `nexus-knowledge` 所有的 User-scoped global knowledge/reference material。 @@ -436,7 +436,7 @@ Retired command set (historical): - 已删除的 daemon runtime 曾是本地 supervisor，不是 ACP Agent/Server。 - `daemon` 曾负责运行态控制，不承载 ACP 协议协商职责。 - **Was shipped:** `daemon schedule ...` was wired to the daemon orchestration schedules Daemon API (`/v1/daemon/orchestration/schedules/*`) via the deleted `commands/daemon/schedule.rs`. -- **Session control ownership (historical):** `daemon schedule ...` was the primary orchestration CLI surface. It exercised the full sessions control plane through schedule operations: `current_session_id` pointed at the active orchestration session, and schedule signals cascaded through the supervisor to the active session as described in [`creator-schedule-and-core-context.md`](./creator-schedule-and-core-context.md) §3.3. +- **Session control ownership (historical):** `daemon schedule ...` was the primary orchestration CLI surface. It exercised the full sessions control plane through schedule operations: `current_session_id` pointed at the active orchestration session, and schedule signals cascaded through the supervisor to the active session as described in [`creator-schedule-and-core-context.md`](../orchestration/creator-schedule-and-core-context.md) §3.3. - **Still removed:** `daemon orchestrate ...` was never a shipped compatibility surface. Do not document `daemon orchestrate run` in new plans or runbooks; the whole group is deleted, so no daemon orchestration CLI control surface exists. **V1.56 P1 amendment (retired with the group in v1.193 P2):** `daemon start` and `daemon restart` gained an optional `--cdn-url ` flag: @@ -483,7 +483,7 @@ A convenience subcommand `nexus42 daemon ui` (alias `nexus42 daemon web`) starte | `nexus42 daemon ui --port ` | Use a specific port (default: 8420) | | `nexus42 daemon web` | Alias for `nexus42 daemon ui` | -The static SPA shell (HTML/JS/CSS) was unauthenticated — it carried no data. All data flowed through the loopback Daemon API (`/v1/daemon/*`), which remained keyless on `localhost` per the V1.20 model; the Electron/TS host serves the SPA today. See [daemon-runtime.md](./daemon-runtime.md) §4.4 (historical host spec) and [web-ui.md](./web-ui.md) §4 for the historical serving model. +The static SPA shell (HTML/JS/CSS) was unauthenticated — it carried no data. All data flowed through the loopback Daemon API (`/v1/daemon/*`), which remained keyless on `localhost` per the V1.20 model; the Electron/TS host serves the SPA today. See [daemon-runtime.md](../archived/daemon-runtime.md) §4.4 (historical host spec) and [web-ui.md](../surfaces/web-ui.md) §4 for the historical serving model. **V1.65 authoring note:** chapter outline and structure editing is exposed first through the daemon-served Web UI (`/v1/daemon/works/{work_id}/chapters/*`). This @@ -502,7 +502,7 @@ The `daemon` command group **used to include** (all deleted in v1.193 P2): > **Historical record — removed in v1.193 P2.** The CLI no longer exposes any `creator run` entry (the `Run` leaf is gone from the `creator` clap group); the underlying preset/execution libraries remain. Nothing below is a current setup step. > -> **Authoritative surface (historical)**: [creator-run-preset-entry.md](./creator-run-preset-entry.md) (Shipped Master, V1.45). The detail below is kept for cli-spec continuity; on any divergence the Master wins. +> **Authoritative surface (historical)**: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (Shipped Master, V1.45). The detail below is kept for cli-spec continuity; on any divergence the Master wins. **V1.45 rewrite:** The bespoke subcommand dispatch (`start`, `continue`, `stage`, `resume`, `reconcile-chapters`, `audit-chapter`, `review-master`) is replaced by a single generic entry point: @@ -534,20 +534,20 @@ Presets may declare `cli_args` with name, type (`integer`/`string`/`boolean`), ` Rules: -- Only presets declaring `run_intents` including `work_init` may be used as the **first** run on a new Work (see [orchestration-engine.md](./orchestration-engine.md) §7.7). +- Only presets declaring `run_intents` including `work_init` may be used as the **first** run on a new Work (see [orchestration-engine.md](../orchestration/orchestration-engine.md) §7.7). - `creator run` created/updated schedules via the Daemon API; it did **not** replace `daemon schedule` for power users. (Both the runner and the whole `daemon` group were removed in v1.193 P2 — the retained scheduling surface is `creator works cron` declaration editing.) -- When `work_id` is omitted, resolve [novel-writing/work-pool.md](./novel-writing/work-pool.md) `active` row → `work_id`; else fail with remediation to `creator works use`. +- When `work_id` is omitted, resolve [novel-writing/work-pool.md](../novel-writing/work-pool.md) `active` row → `work_id`; else fail with remediation to `creator works use`. - FL-E presets are identified via `stage_for_preset()` reverse mapping; the runner calls `stage_advance` with `force: false` (stage ordering enforced). **V1.45 shipped:** Generic `RunCommand` struct replaces enum; `creator/mod.rs` uses `#[command(flatten)]` instead of `#[command(subcommand)]`. Legacy handler code preserved as `#[allow(dead_code)]` for P1/P2 migration. Old `start`/`continue`/`stage`/`resume`/`audit-chapter`/`review-master` subcommands are no longer exposed. ### 6.2E `nexus42 creator run stage` — Superseded by V1.45 generic preset runner (**the runner itself removed in v1.193 P2**) -> **Removed in V1.45; the V1.45 replacement was removed in v1.193 P2.** The FL-E `creator run stage list` / `stage advance` subcommands were deleted from the clap surface and replaced by the generic **`creator run `** runner, which itself lost its CLI entry in v1.193 P2. Stage-gate validation and Work stage PATCH then happened inside the preset runner before enqueue. Authoritative IA (historical): [creator-run-preset-entry.md](./creator-run-preset-entry.md) §4 (Execution flow). See changelog: V1.45 compass migration appendix. +> **Removed in V1.45; the V1.45 replacement was removed in v1.193 P2.** The FL-E `creator run stage list` / `stage advance` subcommands were deleted from the clap surface and replaced by the generic **`creator run `** runner, which itself lost its CLI entry in v1.193 P2. Stage-gate validation and Work stage PATCH then happened inside the preset runner before enqueue. Authoritative IA (historical): [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) §4 (Execution flow). See changelog: V1.45 compass migration appendix. ### 6.2G `nexus42 creator world` (V1.40 — DF-63 P0) -Normative World binding: [novel-writing/workflow-profile.md §3.5](./novel-writing/workflow-profile.md). +Normative World binding: [novel-writing/workflow-profile.md §3.5](../novel-writing/workflow-profile.md). | Command | Purpose | | --- | --- | @@ -567,7 +567,7 @@ Rules: **V1.51 T-A P0 amendment — `creator world kb adopt` surfaces LLM extraction metadata.** When a `pending` candidate was produced by the `nexus.llm.extract` pathway -(V1.51; see [llm-extract.md](llm-extract.md)), the adopt output surfaces two +(V1.51; see [llm-extract.md](../orchestration/llm-extract.md)), the adopt output surfaces two additional fields so the author can judge extraction quality before confirming: - `confidence`: the LLM self-reported confidence (`0.0`–`1.0`), read from @@ -599,7 +599,7 @@ be supplied; supplying both (or neither) fails closed with remediation. | `nexus42 creator kb rescan --work [--dry-run] [--json]` | V1.51 work-scoped rescan. Iterates **all** chapters in `Works//Stories/`, aggregates candidates by `canonical_name` across chapters, and reconciles so a recurring entity collapses to a single `pending` candidate carrying cross-chapter provenance (e.g. `source_chapters: [3,5,7]`). | Rules (build on §6.2G V1.40 rules; see also -[world-kb-runtime-architecture.md §5.5.1](world-kb-runtime-architecture.md)): +[world-kb-runtime-architecture.md §5.5.1](../architecture/world-kb-runtime-architecture.md)): - **Mutual exclusivity.** `--work ` and the positional `/` cannot be combined. `--work` resolves the Work by @@ -639,7 +639,7 @@ Rules (build on §6.2G V1.40 rules; see also When a `novel-writing` chapter finalizes, the supervisor writes an advisory missing-KB log under `Works//Logs/kb/missing/-ch.md` -(see [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §5.5). The +(see [novel-writing/quality-loop.md](../novel-writing/quality-loop.md) §5.5). The `--missing-only` flag switches `creator world kb pending` from listing DB `pending` candidates to scanning those log files for the requested World. @@ -672,13 +672,13 @@ Rules: | Command | Purpose | | --- | --- | | `nexus42 creator world kb adopt [--json]` | V1.50/V1.51 behavior: manually confirm a single pending candidate. | -| `nexus42 creator world kb adopt --auto [--json]` | V1.52 T-A P0: auto-promote all eligible pending candidates for the World (see [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §5.6). | +| `nexus42 creator world kb adopt --auto [--json]` | V1.52 T-A P0: auto-promote all eligible pending candidates for the World (see [novel-writing/quality-loop.md](../novel-writing/quality-loop.md) §5.6). | Rules: - `--auto` requires `--world-ref`; the clap contract enforces exactly one of positional `` or `--auto`. - Author gate: same `require_world_owner` check as manual adopt → `403 WORLD_KB_FORBIDDEN` on mismatch. -- Eligibility is defined in [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §5.6 (`confidence >= 0.95`, provenance-backed, `ValidationMode::Novel` clean, no duplicate canonical name). +- Eligibility is defined in [novel-writing/quality-loop.md](../novel-writing/quality-loop.md) §5.6 (`confidence >= 0.95`, provenance-backed, `ValidationMode::Novel` clean, no duplicate canonical name). - Each promotion is a separate transaction with a CAS version guard; failures are per-candidate and do not block other candidates. - Text output prints promoted and skipped counts; `--json` output includes `promoted_count`, `skipped_count`, `promoted[]`, and `skipped[]` with per-row `reason`. - Audit logs are written under `Works//Logs/kb/auto-promoted/-.md` when a workspace root is bound. @@ -947,7 +947,7 @@ List omission is selected at the core boundary and pushed below the SQL 501-row probe, never implemented as a CLI filter. The retained 500-item cap and `truncated` describe the selected set. HTTP/native inclusion and schema-description requirements are owned by -[Daemon API Surface Conventions §13](daemon-api-surface-conventions.md#13-world-structured-rule-lifecycle). +[Daemon API Surface Conventions §13](../runtime/daemon-api-surface-conventions.md#13-world-structured-rule-lifecycle). This amendment specifies the accepted target behavior; it does not claim implementation or verification has shipped. @@ -994,7 +994,7 @@ cohort, modeled on `nexus42 ops inspect` (§6.3B). ### 6.2I V1.185 P0 amendment — `nexus42 creator character` identity lifecycle (Normative) -Normative: [actor-product-model.md](./actor-product-model.md) §11 (developer maintenance contract). +Normative: [actor-product-model.md](../architecture/actor-product-model.md) §11 (developer maintenance contract). **Delivered (v1.193 P2): these are direct-core leaves.** V1.185 P0 shipped them as thin daemon-HTTP leaves over generated DTOs (`UpdateCharacterRequest`, @@ -1027,7 +1027,7 @@ Rules: ### 6.2I.1 V1.185 P1 amendment — `nexus42 creator character binding` WorldSheet maintenance (Normative) -Normative: [actor-product-model.md](./actor-product-model.md) §11.4. +Normative: [actor-product-model.md](../architecture/actor-product-model.md) §11.4. **Delivered (v1.193 P2): these are direct-core leaves.** V1.185 P1 shipped them as thin daemon-HTTP leaves over generated `CharacterBindingDetail` and @@ -1056,7 +1056,7 @@ Rules: ### 6.2I.2 V1.185 P2 amendment — `nexus42 creator character knowledge` authored-content maintenance (Normative) -Normative: [actor-product-model.md](./actor-product-model.md) §11.5. +Normative: [actor-product-model.md](../architecture/actor-product-model.md) §11.5. **Delivered (v1.193 P2): these are direct-core leaves.** V1.185 P2 shipped them as thin daemon-HTTP leaves over generated `KnowledgeEntryDetail`, @@ -1099,7 +1099,7 @@ Rules: > Retained Character surface: `create|list|show|edit|archive|restore`, > `binding`, `knowledge`, `memory`, `tom` (see §6.2I–§6.2I.2). -Normative: [actor-product-model.md](./actor-product-model.md) §11.6. +Normative: [actor-product-model.md](../architecture/actor-product-model.md) §11.6. Thin daemon-HTTP leaves over generated Agent Host session/operation DTOs plus the owner-only `CharacterOperationResult` outcome surface. Run output observation @@ -1135,7 +1135,7 @@ Rules: ### 6.2H `nexus42 creator works` — Work management and pool (V1.41 Draft — DF-60/61) -Normative: [novel-writing/multi-work-lifecycle.md](./novel-writing/multi-work-lifecycle.md), [novel-writing/work-pool.md](./novel-writing/work-pool.md). +Normative: [novel-writing/multi-work-lifecycle.md](../novel-writing/multi-work-lifecycle.md), [novel-writing/work-pool.md](../novel-writing/work-pool.md). **Tier:** Primary for multi-book operators; it complemented **`creator run`** for single-Work actions (the runner was removed in v1.193 P2 — the `creator works` surface below is the retained one). @@ -1180,7 +1180,7 @@ command refuses with remediation to `creator works use `. **OUT V1.41:** `creator work switch` / global switch mutex (grill-me 2026-06-10). -**Entry path pointer (no standalone quickstart in V1.41):** multi-book flow extends [creator-centric-entry-model.md](./creator-centric-entry-model.md) §3.1 step 7 — +**Entry path pointer (no standalone quickstart in V1.41):** multi-book flow extends [creator-centric-entry-model.md](../archived/creator-centric-entry-model.md) §3.1 step 7 — **Target (V1.41):** . @@ -1252,7 +1252,7 @@ completed-stages ledger, and the output never claims one. **Read-only / no-manual-resume boundary:** inspection **never** implies or triggers resume — re-drive is not a CLI operation, and the former daemon-boot re-drive is gone with that deleted host -([daemon-runtime.md](./daemon-runtime.md) §19 — historical host spec; its +([daemon-runtime.md](../archived/daemon-runtime.md) §19 — historical host spec; its crate was deleted in v1.193 P2). Rule 4's in-memory half (the engine runner presence at boot) is carried as the separate `runner_check` caveat, never folded into the verdict; driving a resume @@ -1293,7 +1293,7 @@ Implementation authorities: `apps/nexus42/src/commands/ops.rs`, 操作主体：`sync` 的 `creator_id` 与 `workspace_slug` 必须对应当前活跃上下文；HTTP 优先 `Authorization: Bearer `，User 代操时使用 `Authorization: Bearer ` + `X-Creator-Id`。 -**架构边界（长期）**：`sync` 属于 **cloud 产品线**，由 CLI 调用 **`nexus-cloud-sync`** 完成 platform HTTP；Daemon API **不得**承载 `/v1/daemon/sync/*` 或注册代理。见 [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md) §5–§6。 +**架构边界（长期）**：`sync` 属于 **cloud 产品线**，由 CLI 调用 **`nexus-cloud-sync`** 完成 platform HTTP；Daemon API **不得**承载 `/v1/daemon/sync/*` 或注册代理。见 [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) §5–§6。 ### 6.6 `nexus42 platform`（平台能力命令组） @@ -1327,7 +1327,7 @@ Implementation authorities: `apps/nexus42/src/commands/ops.rs`, ## 7. 首次使用路径 -V1.35 将首次使用拆为 **纯本地**（默认，`platform_integration = paused` 时）与 **挂载 Platform** 两条路径。Creator 中心化规则见 [creator-centric-entry-model.md](creator-centric-entry-model.md)。 +V1.35 将首次使用拆为 **纯本地**（默认，`platform_integration = paused` 时）与 **挂载 Platform** 两条路径。Creator 中心化规则见 [creator-centric-entry-model.md](../archived/creator-centric-entry-model.md)。 ### 7.1 纯本地路径（Local-first） @@ -1497,7 +1497,7 @@ daemon 可以允许部分能力降级，例如： Nexus runtime 在 ACP 上应扮演 ACP client 角色，至少支持： -- 从 ACP Registry 拉取或读取 agent manifest（默认远程索引与上游仓库见 [`registry-integration.md`](./registry-integration.md) §0.1） +- 从 ACP Registry 拉取或读取 agent manifest（默认远程索引与上游仓库见 [`registry-integration.md`](../agents/registry-integration.md) §0.1） - 根据协议版本和 capability 过滤可用 agent - 选择默认 agent - 通过本地 stdio 启动或连接 agent @@ -1551,7 +1551,7 @@ Nexus runtime 在 ACP 上应扮演 ACP client 角色，至少支持： 约束： -- 只允许操作工作区白名单路径；**默认**正文树根为 **`Works//Stories/`**（章节文件如 **`ch-.md`**）；**`work_ref`** 与 **`work_id`** 的映射以 **preset + 本地 DB `works` 表** 为准，不得仅靠目录名推断（见 [novel-writing/workflow-profile.md](./novel-writing/workflow-profile.md)） +- 只允许操作工作区白名单路径；**默认**正文树根为 **`Works//Stories/`**（章节文件如 **`ch-.md`**）；**`work_ref`** 与 **`work_id`** 的映射以 **preset + 本地 DB `works` 表** 为准，不得仅靠目录名推断（见 [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md)） - **研究型产出**默认在 **`{$workspace_dir}/.nexus42/references//`**（见 §6.6B）；历史布局 **`References//`** 仅作为兼容叙述，**不再**由 `init` 默认创建 - **`research.*`**（若暴露为 ACP 工具名）与 **`ReferenceSource`** 索引合同仍与 `manuscript.*` 分离，防止越权读写任意文件 - 当 `output_manuscript=false` 时，`manuscript.write` 不作为默认创作路径，但能力本身仍存在；平台托管与本地 Agent 的能力面保持一致 @@ -1579,14 +1579,14 @@ Nexus runtime 在 ACP 上应扮演 ACP client 角色，至少支持： 1. nexus-platform `v1-spec/adr/adr-014-local-fs-creator-workspace-layout-v1.md`（架构决策：目录、`workspace_slug`、`creator use` / `creator workspace` 双层指针） 2. nexus-platform `v1-spec/adr/adr-023-pre-release-cli-breaking-refactor-v1.md`、nexus-platform `v1-spec/adr/adr-024-preset-driven-workspace-acp-skills-v1.md`（CLI 面收窄、preset 产物与 ACP skills） 3. **本节** §0.2、§6.2B–§6.2C、§6.2C **C2**、**§12.2**（CLI 用户面与目录树） - 4. [`local-db-schema.md`](./local-db-schema.md) §0（`state.db` 路径与模块边界） + 4. [`local-db-schema.md`](../runtime/local-db-schema.md) §0（`state.db` 路径与模块边界） 5. nexus-platform `v1-spec/shared/domain/data-model-v1.md` §5.14（`WorkspaceBinding` 与本地不变量） ### 12.1 用户工作区（`/`） `` **默认不**包含固定业务子树；首次 `init` 只登记创作根与配置，**不**默认创建 `Stories/`、`References/`。用户可见目录由 **preset 产物策略** 在运行中创建。 -**`novel-writing` 预设（V1.36 normative）** — 小说正文布局见 [novel-writing/workflow-profile.md](./novel-writing/workflow-profile.md)： +**`novel-writing` 预设（V1.36 normative）** — 小说正文布局见 [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md)： ```text / @@ -1613,10 +1613,10 @@ Nexus runtime 在 ACP 上应扮演 ACP client 角色，至少支持： - **`Works//Stories/`** - 小说章节**正文**主存（sync 扫描根）；**`work_ref`** 与 **`work_id`** 以 **本地 DB `works` 表 + preset** 为准，**不得**仅靠目录名推断。 -- **章节状态真源**在本地 DB `state.db` 的 **`work_chapters` 表**（见 [novel-writing/workflow-profile.md §4.1](./novel-writing/workflow-profile.md)）。`work-status.md` 文件在 V1.36 **已移除**。 +- **章节状态真源**在本地 DB `state.db` 的 **`work_chapters` 表**（见 [novel-writing/workflow-profile.md §4.1](../novel-writing/workflow-profile.md)）。`work-status.md` 文件在 V1.36 **已移除**。 - **`Works//Outlines/`**、**`README.md`** - 规划与人类概要元数据；**不得**被 sync 模块当作章节正文。 -- **世界设定内容**跨作品（Work）共享，归 **World KB**（见 [entity-scope-model.md §5.4](./entity-scope-model.md)）。`Works//Worldbuilding/` 子树在 V1.36 **已移除**；通过 `work.world_id` 绑定到 World。 +- **世界设定内容**跨作品（Work）共享，归 **World KB**（见 [entity-scope-model.md §5.4](../architecture/entity-scope-model.md)）。`Works//Worldbuilding/` 子树在 V1.36 **已移除**；通过 `work.world_id` 绑定到 World。 - **已废弃（pre-1.0 移除）**：工作区根 **`Stories//`** — 无兼容 shim。 - **`.nexus42/references//`** - **研究 / 采风型**机读产出默认位置；`report.md` + 可选 `artifacts/`；与 **`ReferenceSource`** 索引合同衔接。 @@ -1629,11 +1629,11 @@ Nexus runtime 在 ACP 上应扮演 ACP client 角色，至少支持： | `--profile` | init preset | 布局规范 | 状态 | | --- | --- | --- | --- | -| `novel` (default) | `novel-project-init` (显式传入) | [novel-writing/workflow-profile.md](./novel-writing/workflow-profile.md) | Shipped V1.36 | -| `essay` | `essay-init` (自动派生) | [essay-profile.md](./essay-profile.md) | Shipped V1.52 | -| `game_bible` | `game-bible-init` (自动派生) | [game-bible-profile.md](./game-bible-profile.md) | Shipped V1.54 | +| `novel` (default) | `novel-project-init` (显式传入) | [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) | Shipped V1.36 | +| `essay` | `essay-init` (自动派生) | [essay-profile.md](../creator/essay-profile.md) | Shipped V1.52 | +| `game_bible` | `game-bible-init` (自动派生) | [game-bible-profile.md](../creator/game-bible-profile.md) | Shipped V1.54 | -V1.54 game-bible 布局（`works_profile: game_bible`）：`Works//Design/`（12 个 section 模板），`Logs/{design,review}/`，无 `Stories/`、`Outlines/` 或 `work_chapters`。详见 [game-bible-profile.md](./game-bible-profile.md) §3。`--profile game_bible` 自动选择 `--init-preset game-bible-init`；V1.54 不自动链式推进后续预设。 +V1.54 game-bible 布局（`works_profile: game_bible`）：`Works//Design/`（12 个 section 模板），`Logs/{design,review}/`，无 `Stories/`、`Outlines/` 或 `work_chapters`。详见 [game-bible-profile.md](../creator/game-bible-profile.md) §3。`--profile game_bible` 自动选择 `--init-preset game-bible-init`；V1.54 不自动链式推进后续预设。 ### 12.1C `novel-writing` preset sync module contract @@ -1642,7 +1642,7 @@ V1.54 game-bible 布局（`works_profile: game_bible`）：`Works//Des **Accepted inputs**： - Preset metadata：`preset_id=novel-writing`、版本、`workspace_slug`、`world_id`、`creator_id`、`work_id`、`work_ref`、`work_profile: novel`（来自本地 DB `works` 表，而非仅目录名）。 -- 正文产物：`Works//Stories/.md` 及 manifest / phase metadata（映射到 existing bundle fields such as `manuscript_phase`, source anchors, canonical hashes）。详见 [novel-writing/sync-contract.md](./novel-writing/sync-contract.md)。 +- 正文产物：`Works//Stories/.md` 及 manifest / phase metadata（映射到 existing bundle fields such as `manuscript_phase`, source anchors, canonical hashes）。详见 [novel-writing/sync-contract.md](../novel-writing/sync-contract.md)。 - 研究产物：`.nexus42/references//report.md` 与可选 `artifacts/`，只把合同允许的摘要、引用锚点、`ReferenceSource` / `MemoryItem` 摘录纳入结构化 sync。 - Session hints：ACP `recommended_skills[]` 解析结果与 agent session metadata（仅作为审计 / 可复现上下文，不作为全文上传许可）。 @@ -1871,9 +1871,9 @@ v1 至少应保证： ## V1.45 supersession (P-last promotion) -**Superseded by**: [creator-run-preset-entry.md](./creator-run-preset-entry.md) (Shipped Master V1.45). The §6.2D/E `creator run` preset-entry table, FL-E stage advance mapping, preset-id examples, and global flags on `creator run` are now part of the canonical Master body. +**Superseded by**: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (Shipped Master V1.45). The §6.2D/E `creator run` preset-entry table, FL-E stage advance mapping, preset-id examples, and global flags on `creator run` are now part of the canonical Master body. -> **Note on §6.2D/E body**: The §6.2D/E body now defers to the Shipped Master [creator-run-preset-entry.md](./creator-run-preset-entry.md) (V1.45) for the canonical `creator run` surface — see the authoritative-surface pointer at the top of §6.2D and the supersession note in §6.2E. The V1.33–V1.44 bespoke subcommand table was replaced by the generic dispatch entry in commit `4aa5aa53` (V1.45 P-last); the stale `creator run stage` section was deleted in V1.46 P1. Closes residual `R-V145B3-001`. +> **Note on §6.2D/E body**: The §6.2D/E body now defers to the Shipped Master [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (V1.45) for the canonical `creator run` surface — see the authoritative-surface pointer at the top of §6.2D and the supersession note in §6.2E. The V1.33–V1.44 bespoke subcommand table was replaced by the generic dispatch entry in commit `4aa5aa53` (V1.45 P-last); the stale `creator run stage` section was deleted in V1.46 P1. Closes residual `R-V145B3-001`. > > **v1.193 P2:** `creator run` and `creator run stage` have no CLI entry — the §6.2D/E bodies are historical records of the removed runner, and the V1.45 promotion above is the version history of that pre-retirement surface. diff --git a/.mstar/specs/compute-module-abi.md b/.mstar/specs/compute/compute-module-abi.md similarity index 95% rename from .mstar/specs/compute-module-abi.md rename to .mstar/specs/compute/compute-module-abi.md index 128814284..ed675703b 100644 --- a/.mstar/specs/compute-module-abi.md +++ b/.mstar/specs/compute/compute-module-abi.md @@ -6,10 +6,10 @@ | --- | --- | | **Status** | Normative — V1.62 Shipped | | **Document class** | Master | -| **Pillar (V1.122)** | **Computable** — this spec is the module-side ABI contract for the [Computable](../../STRATEGY.md) pillar (the WASM layer that makes worlds *react*). Computable is a product pillar distinct from the `Compute (Capability)` mechanism ([`CONCEPTS.md`](../../CONCEPTS.md)). Pillar framing: `pillar-framing.md`. | +| **Pillar (V1.122)** | **Computable** — this spec is the module-side ABI contract for the [Computable](../../../STRATEGY.md) pillar (the WASM layer that makes worlds *react*). Computable is a product pillar distinct from the `Compute (Capability)` mechanism ([`CONCEPTS.md`](../../../CONCEPTS.md)). Pillar framing: `pillar-framing.md`. | | **Scope** | V1 envelope ABI: `ComputeInput` / `ComputeOutput` wire contracts, module exports table, host import ABI, marshalling convention, `manifest.json` contract, sandbox cross-ref, versioning policy | | **Last updated** | 2026-06-23 — V1.62 Shipped; 2026-07-13 — V1.115 P2 clarified wire vs runtime-only split in §7.6 (no normative change); 2026-08-01 — V1.147 added §5.6 direct-lane invocation note (no ABI change) | -| **Related** | [wasm-host.md](./wasm-host.md), [schemas-directory-layout.md](./schemas-directory-layout.md) §3.5, [orchestration-engine.md](./orchestration-engine.md) §8 (narrative.compute), [entity-scope-model.md](./entity-scope-model.md) §5.5.9 | +| **Related** | [wasm-host.md](wasm-host.md), [schemas-directory-layout.md](../architecture/schemas-directory-layout.md) §3.5, [orchestration-engine.md](../orchestration/orchestration-engine.md) §8 (narrative.compute), [entity-scope-model.md](../architecture/entity-scope-model.md) §5.5.9 | This Master is normative for the V1 compute ABI — the interface contract between the `nexus-wasm-host` runtime and a WASM compute module. It consolidates the V1.61 @@ -104,7 +104,7 @@ Use `kb_read` / `narrative_query` only when a module needs to look up ## 4. `ComputeInput` envelope structure The `ComputeInput` envelope is defined in -[`schemas/daemon-api/compute/compute-input.schema.json`](../../schemas/daemon-api/compute/compute-input.schema.json). +[`schemas/daemon-api/compute/compute-input.schema.json`](../../../schemas/daemon-api/compute/compute-input.schema.json). It is the **single source of truth** for the input shape — the Rust `generated::local_api::compute::compute_input::ComputeInput` struct is derived from it via codegen. @@ -136,7 +136,7 @@ from it via codegen. | --- | --- | --- | --- | | `schema_version` | integer (`1`) | yes | Envelope version. Must be `1` for V1.x. | | `world_ref` | object | yes | World and timeline locator: `world_id` (WorldId), `branch_id` (fork branch), `timeline_head_event_id` (current timeline head). | -| `key_blocks` | array of `KnowledgeEntry` | yes | Snapshot of relevant KnowledgeEntries for this invocation. Each entry is the full wire `KnowledgeEntry` shape from spoke `knowledge-entry.schema.json` (referenced via `$ref`), including `body` (which carries `state` for computable entries — see [entity-scope-model.md](./entity-scope-model.md) §5.5.9). The host selects which entries to pass based on the module manifest (`required_key_block_types`) and the capability context. | +| `key_blocks` | array of `KnowledgeEntry` | yes | Snapshot of relevant KnowledgeEntries for this invocation. Each entry is the full wire `KnowledgeEntry` shape from spoke `knowledge-entry.schema.json` (referenced via `$ref`), including `body` (which carries `state` for computable entries — see [entity-scope-model.md](../architecture/entity-scope-model.md) §5.5.9). The host selects which entries to pass based on the module manifest (`required_key_block_types`) and the capability context. | | `narrative_state` | object | no | Narrative position context — `timeline_position`, `current_chapter`, `current_scene`. Freeform; the shape is module-declared. | | `invocation` | object | no | Module-defined freeform input parameters. The exact fields are declared in the module's `manifest.json` `schemas.invocation` (V1.62 P1). The host passes them through verbatim. This is the V1 envelope escape hatch for module-specific inputs (e.g., chosen targets, difficulty, dice seed). | @@ -151,7 +151,7 @@ non-computable entries may still appear in the snapshot for read-only reference. ## 5. `ComputeOutput` 4-part envelope The `ComputeOutput` envelope is defined in -[`schemas/daemon-api/compute/compute-output.schema.json`](../../schemas/daemon-api/compute/compute-output.schema.json). +[`schemas/daemon-api/compute/compute-output.schema.json`](../../../schemas/daemon-api/compute/compute-output.schema.json). The module's `compute` export must emit a JSON object with exactly four top-level keys. @@ -315,7 +315,7 @@ The module must ensure `out_ptr` does not overlap with the request data. Every compute module ships a `manifest.json` next to its `.wasm`. The manifest declares identity, the required input surface, the export names, and optional sandbox overrides. The exact structure is defined in -[`modules/README.md`](../../modules/README.md); this section is the normative +[`modules/README.md`](../../../modules/README.md); this section is the normative reference for the contract fields. ### 7.1 Required fields @@ -355,7 +355,7 @@ fragments for host-side validation. The block has four optional sub-objects: | `schemas.battle_report` | JSON Schema fragment | After invocation: `ComputeOutput.battle_report` is validated against this fragment if declared. | Validation failure produces `ComputeError::ManifestValidationFailed { path, detail }` -(see [wasm-host.md](./wasm-host.md) §8). +(see [wasm-host.md](wasm-host.md) §8). **Backward compatibility**: omitting the `schemas` block entirely disables validation — V1.61 modules continue to work unchanged. A module may declare any @@ -437,7 +437,7 @@ read-only through the daemon registry API: `ComputeModuleDetail`. These endpoints reuse the manifest fields defined above; they do not introduce -a parallel module DTO. See [`schemas/daemon-api/compute/`](../../schemas/daemon-api/compute/) +a parallel module DTO. See [`schemas/daemon-api/compute/`](../../../schemas/daemon-api/compute) for the generated wire contracts. ### 7.6 Wire vs runtime-only fields @@ -461,7 +461,7 @@ runtime to carry internal state that is not part of the module author contract. ## 8. Sandbox model cross-ref The host enforces three independent sandbox limits on every `compute()` call. -Full details are in [wasm-host.md](./wasm-host.md) §3–§5. Summary: +Full details are in [wasm-host.md](wasm-host.md) §3–§5. Summary: | Limit | Default | Manifest override | Error variant | | --- | --- | --- | --- | diff --git a/.mstar/specs/wasm-host.md b/.mstar/specs/compute/wasm-host.md similarity index 94% rename from .mstar/specs/wasm-host.md rename to .mstar/specs/compute/wasm-host.md index b45b21204..545201e21 100644 --- a/.mstar/specs/wasm-host.md +++ b/.mstar/specs/compute/wasm-host.md @@ -6,10 +6,10 @@ | --- | --- | | **Status** | Normative — V1.62 Shipped | | **Document class** | Master | -| **Pillar (V1.122)** | **Computable** — this spec is the host-runtime contract for the [Computable](../../STRATEGY.md) pillar (the WASM layer that makes worlds *react*). Computable is a product pillar distinct from the `Compute (Capability)` mechanism ([`CONCEPTS.md`](../../CONCEPTS.md)); this crate is the host side of the [`compute-module-abi.md`](./compute-module-abi.md) contract. Pillar framing: `pillar-framing.md`. | +| **Pillar (V1.122)** | **Computable** — this spec is the host-runtime contract for the [Computable](../../../STRATEGY.md) pillar (the WASM layer that makes worlds *react*). Computable is a product pillar distinct from the `Compute (Capability)` mechanism ([`CONCEPTS.md`](../../../CONCEPTS.md)); this crate is the host side of the [`compute-module-abi.md`](compute-module-abi.md) contract. Pillar framing: `pillar-framing.md`. | | **Scope** | `nexus-wasm-host` crate: wasmtime runtime, engine lifecycle, per-invocation sandbox, limits, wall-time watchdog, embedded module loading, user module discovery, error taxonomy, host function implementation | | **Last updated** | 2026-06-23 — V1.62 P2; 2026-08-01 — V1.147 added §2.3 direct-lane invocation note (no ABI change) | -| **Related** | [compute-module-abi.md](./compute-module-abi.md), [orchestration-engine.md](./orchestration-engine.md) §8 (narrative.compute), [entity-scope-model.md](./entity-scope-model.md) §5.5.9, [`crates/nexus-wasm-host/AGENTS.md`](../../crates/nexus-wasm-host/AGENTS.md) | +| **Related** | [compute-module-abi.md](compute-module-abi.md), [orchestration-engine.md](../orchestration/orchestration-engine.md) §8 (narrative.compute), [entity-scope-model.md](../architecture/entity-scope-model.md) §5.5.9, [`crates/nexus-wasm-host/AGENTS.md`](../../../crates/nexus-wasm-host/AGENTS.md) | This Master is normative for the `nexus-wasm-host` crate — the sandboxed WebAssembly runtime that hosts compute modules for the `narrative.compute` @@ -22,7 +22,7 @@ The `nexus-wasm-host` crate is the **runtime**; it does not wire itself into the daemon. Three callers invoke it — the `narrative.compute` capability (orchestration), the `ComputablePort` spoke adapter, and, since V1.147, the direct Control Room lane (`compute_runs` handler — see §2.3). Read -[compute-module-abi.md](./compute-module-abi.md) for the module-side contract +[compute-module-abi.md](compute-module-abi.md) for the module-side contract that this crate implements on the host side. --- @@ -265,7 +265,7 @@ This lets users override or patch shipped modules. ### 7.3 Registry API (V1.114 P2) `nexus-wasm-host` exposes the embedded module set as a read-only registry via -[`src/registry.rs`](../../crates/nexus-wasm-host/src/registry.rs) for the +[`src/registry.rs`](../../../crates/nexus-wasm-host/src/registry.rs) for the daemon runtime: - `list_modules()` → `Vec` — summary of every installed module. @@ -278,8 +278,8 @@ These functions back the daemon endpoints: Both endpoints reuse the existing `manifest.json` shape; the runtime maps the hand-written `ModuleManifest` struct to the generated wire type via a JSON -round-trip. See [`schemas/daemon-api/compute/`](../../schemas/daemon-api/compute/) -for the generated contracts and [`modules/README.md`](../../modules/README.md) +round-trip. See [`schemas/daemon-api/compute/`](../../../schemas/daemon-api/compute) +for the generated contracts and [`modules/README.md`](../../../modules/README.md) for the authoring guide. --- diff --git a/.mstar/specs/canonical-hash.md b/.mstar/specs/contracts/canonical-hash.md similarity index 95% rename from .mstar/specs/canonical-hash.md rename to .mstar/specs/contracts/canonical-hash.md index eef623a15..8f5c78173 100644 --- a/.mstar/specs/canonical-hash.md +++ b/.mstar/specs/contracts/canonical-hash.md @@ -49,6 +49,6 @@ sha256:23f370c5ec4797f194b9fbbdba556c4de1d7c18c60b14a64898b1919486969fe ## References - `crates/nexus-cloud-sync/src/canonical_hash.rs` -- [local-cloud-crate-architecture.md](./local-cloud-crate-architecture.md) §3.7 — `nexus-sync` → `nexus-cloud-sync` +- [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) §3.7 — `nexus-sync` → `nexus-cloud-sync` - `schemas/platform/sync/bundle.schema.json` - nexus-platform `v1-spec/shared/schema/bundle-envelope-schema-v1.md`, `v1-spec/cli-sync/sync-contract-v1.md`, `v1-spec/consistency/consistency-rules-v1.md` diff --git a/.mstar/specs/findings-lifecycle.md b/.mstar/specs/contracts/findings-lifecycle.md similarity index 87% rename from .mstar/specs/findings-lifecycle.md rename to .mstar/specs/contracts/findings-lifecycle.md index ee7a62e89..0b438195f 100644 --- a/.mstar/specs/findings-lifecycle.md +++ b/.mstar/specs/contracts/findings-lifecycle.md @@ -2,13 +2,13 @@ **Status**: Normative — V1.77 Phase 2b (promoted from `novel-writing/findings-lifecycle.md` stub) **Document class**: Master -**Scope**: Cross-profile findings lifecycle — 6-state status machine, `target_executor` routing semantics, and the UI remediation surface consuming the Daemon API PATCH route. Quality-loop produce side (review verdicts, finding creation, orchestration hooks) is owned by [novel-writing/quality-loop.md](novel-writing/quality-loop.md) §2 and is not duplicated here. +**Scope**: Cross-profile findings lifecycle — 6-state status machine, `target_executor` routing semantics, and the UI remediation surface consuming the Daemon API PATCH route. Quality-loop produce side (review verdicts, finding creation, orchestration hooks) is owned by [novel-writing/quality-loop.md](../novel-writing/quality-loop.md) §2 and is not duplicated here. **Coordinates with**: -- [novel-writing/quality-loop.md](novel-writing/quality-loop.md) — producer side (review verdicts, finding creation, orchestration hooks, retention/prune) -- [local-api-surface-conventions.md](local-api-surface-conventions.md) — findings PATCH surface conventions -- [web-ui.md](web-ui.md) — Control-Room findings view and V1.77 remediation surface -- [`crates/nexus-local-db/src/findings.rs`](../../crates/nexus-local-db/src/findings.rs) — DAO enforcement (canonical `is_valid_transition`, `VALID_STATUSES`, `enforce_status_transition`) -- [`crates/nexus-daemon-runtime/src/api/handlers/findings.rs`](../../crates/nexus-daemon-runtime/src/api/handlers/findings.rs) — PATCH handler error mapping +- [novel-writing/quality-loop.md](../novel-writing/quality-loop.md) — producer side (review verdicts, finding creation, orchestration hooks, retention/prune) +- [daemon-api-surface-conventions.md §11](../runtime/daemon-api-surface-conventions.md#11-findings-patch-route-v177--non-occ-resource-patch) — findings PATCH surface conventions +- [web-ui.md](../surfaces/web-ui.md) — Control-Room findings view and V1.77 remediation surface +- [`crates/nexus-local-db/src/findings.rs`](../../../crates/nexus-local-db/src/findings.rs) — DAO enforcement (canonical `is_valid_transition`, `VALID_STATUSES`, `enforce_status_transition`) +- [`crates/nexus-core/src/findings.rs`](../../../crates/nexus-core/src/findings.rs) — PATCH handler error mapping **Supersedes**: the former novel-writing findings-lifecycle overlay (folded into `quality-loop.md` §2, V1.49). @@ -18,7 +18,7 @@ The findings lifecycle is a cross-profile 6-state status machine that all Work profiles consume. The backend (V1.49+) enforces the lifecycle server-side on every `PATCH /v1/local/works/{work_id}/findings/{finding_id}`, rejecting illegal transitions with HTTP 422 `INVALID_TRANSITION`. The V1.77 UI promotion adds a remediation authoring surface that consumes this existing PATCH route. -This Master documents the lifecycle adjacency rules, `target_executor` routing semantics, and the UI remediation surface. The produce side — how findings are created (review verdicts, `from-review` hooks, orchestration-synthesized findings) — is owned by the quality-loop spec ([novel-writing/quality-loop.md](novel-writing/quality-loop.md) §2) and is not repeated here. +This Master documents the lifecycle adjacency rules, `target_executor` routing semantics, and the UI remediation surface. The produce side — how findings are created (review verdicts, `from-review` hooks, orchestration-synthesized findings) — is owned by the quality-loop spec ([novel-writing/quality-loop.md](../novel-writing/quality-loop.md) §2) and is not repeated here. --- @@ -116,5 +116,5 @@ Request body fields (all optional on the wire): ## 5. Non-goals (V1.77) - **No one-click orchestration re-trigger from a finding** — re-running a preset stays a deliberate canvas/CLI action. `target_executor` is an assignment hint, not an auto-trigger. -- **No findings producer changes** — this Master documents the *consumer* side (triage/remediation). Finding creation, review verdicts, and orchestration hooks are owned by [novel-writing/quality-loop.md](novel-writing/quality-loop.md). +- **No findings producer changes** — this Master documents the *consumer* side (triage/remediation). Finding creation, review verdicts, and orchestration hooks are owned by [novel-writing/quality-loop.md](../novel-writing/quality-loop.md). - **No create/delete from the UI** — the V1.77 lead surface is update-only. `createFinding`/`deleteFinding` remain CLI/producer-only for now; the web app can add them in a follow-up if UX demands in-UI finding creation. diff --git a/.mstar/specs/world-delta-propose-apply.md b/.mstar/specs/contracts/world-delta-propose-apply.md similarity index 97% rename from .mstar/specs/world-delta-propose-apply.md rename to .mstar/specs/contracts/world-delta-propose-apply.md index 5121bcdd8..df6a9623f 100644 --- a/.mstar/specs/world-delta-propose-apply.md +++ b/.mstar/specs/contracts/world-delta-propose-apply.md @@ -2,7 +2,7 @@ **Status**: Master (V1.60 P-last promotion) **Document class**: Feature line (promoted from Draft overlay V1.60 P0) -**Coordinates with**: [`acp-capability-set.md`](acp-capability-set.md) §4 + §8, [`capability-registry.md`](capability-registry.md), [`entity-scope-model.md`](entity-scope-model.md) §5, [`orchestration-engine.md`](orchestration-engine.md) §5 +**Coordinates with**: [`acp-capability-set.md`](../agents/acp-capability-set.md) §4 + §8, [`capability-registry.md`](../agents/capability-registry.md), [`entity-scope-model.md`](../architecture/entity-scope-model.md) §5, [`orchestration-engine.md`](../orchestration/orchestration-engine.md) §5 ## 0. Purpose and scope diff --git a/.mstar/specs/creator-challenge-solver.md b/.mstar/specs/creator/creator-challenge-solver.md similarity index 89% rename from .mstar/specs/creator-challenge-solver.md rename to .mstar/specs/creator/creator-challenge-solver.md index 92b3e9d88..54ebbe2f0 100644 --- a/.mstar/specs/creator-challenge-solver.md +++ b/.mstar/specs/creator/creator-challenge-solver.md @@ -5,8 +5,9 @@ **Created**: 2026-04-23 **平台侧对照**: nexus-platform `v1-spec/platform/creator-agent-registration-v1.md` §3–§4 **实现仓库**: `nexus`（CLI），**非** `nexus-platform` -**CLI Spec**: [`cli-spec.md`](./cli-spec.md) §6.2B -**集成边界**: [`local-cloud-crate-architecture.md`](./local-cloud-crate-architecture.md) §6 — registration via **`nexus-cloud-sync`** (CLI → platform HTTP), **not** Daemon API. +**CLI Spec**: [`cli-spec.md`](../cli/cli-spec.md) §6.2B +**集成边界**: [`local-cloud-crate-architecture.md`](../archived/local-cloud-crate-architecture.md) §6 — registration via **`nexus-cloud-sync`** (CLI → platform HTTP), **not** Daemon API. +**当前实现锚点**: solver 编排在 [`apps/nexus42/src/challenge/mod.rs`](../../../apps/nexus42/src/challenge/mod.rs)（`solve_challenge` / `solve_challenge_with_fallback`），由 [`apps/nexus42/src/commands/creator/mod.rs`](../../../apps/nexus42/src/commands/creator/mod.rs) 的 `register_creator` 导入并调用；[`crates/nexus-creator/src/creator.rs`](../../../crates/nexus-creator/src/creator.rs) 仅承载 Creator aggregate / local-identity 域逻辑，不是 Challenge solver 或注册流程编排的实现 owner。 > **权威说明**：本文档是 CLI 侧 Challenge 解题逻辑的**独立冻结规格**（原 V1.3 程序提取）。CLI 实现若有分歧，以本文档为准。平台侧 Challenge 生成与验证逻辑见 nexus-platform `v1-spec/platform/creator-agent-registration-v1.md`。 @@ -218,6 +219,8 @@ Answer: "47" ## 5. 实现模块 +**当前 Rust 实现位置**见文首锚点：`apps/nexus42/src/challenge` 拥有解题管线及 fallback 编排，`apps/nexus42/src/commands/creator/mod.rs` 拥有 register → solve → verify → store 调用流程。下表及 §4 的 TypeScript/`packages/cli` 路径保留为原冻结规格的历史建议，不是当前源码位置；冻结 CLI 注册契约不变。 + | 模块 | 文件（建议） | 职责 | |------|-------------|------| | `creator-register.ts` | `packages/cli/src/commands/creator/register.ts` | CLI 命令入口，编排 register→solve→verify | diff --git a/.mstar/specs/creator-memory-soul-lifecycle.md b/.mstar/specs/creator/creator-memory-soul-lifecycle.md similarity index 93% rename from .mstar/specs/creator-memory-soul-lifecycle.md rename to .mstar/specs/creator/creator-memory-soul-lifecycle.md index 0a8efd427..6b2b00dd5 100644 --- a/.mstar/specs/creator-memory-soul-lifecycle.md +++ b/.mstar/specs/creator/creator-memory-soul-lifecycle.md @@ -7,10 +7,10 @@ **Coordinates with**: - [creator-workflow.md](creator-workflow.md) §5.6 — SOUL visualization contract over memory fragments -- [web-ui.md](web-ui.md) §26–§27 — Creator SOUL Maturation (V1.81) + SOUL Completion per-World narrative (V1.82) -- [`schemas/daemon-api/memory/`](../../schemas/daemon-api/memory/) — wire contract schemas -- [on-demand-synthesis-read-path-invariant.md](../knowledge/architecture-patterns/on-demand-synthesis-read-path-invariant.md) — read-path LLM gating (applies per world) -- [fingerprint-cached-live-aggregate.md](../knowledge/architecture-patterns/fingerprint-cached-live-aggregate.md) — read-path cost (cache key per (creator, world)) +- [web-ui.md](../surfaces/web-ui.md) §26–§27 — Creator SOUL Maturation (V1.81) + SOUL Completion per-World narrative (V1.82) +- [`schemas/daemon-api/memory/`](../../../schemas/daemon-api/memory) — wire contract schemas +- [on-demand-synthesis-read-path-invariant.md](../../knowledge/architecture-patterns/on-demand-synthesis-read-path-invariant.md) — read-path LLM gating (applies per world) +- [fingerprint-cached-live-aggregate.md](../../knowledge/architecture-patterns/fingerprint-cached-live-aggregate.md) — read-path cost (cache key per (creator, world)) ## 1. Purpose diff --git a/.mstar/specs/creator-workflow.md b/.mstar/specs/creator/creator-workflow.md similarity index 63% rename from .mstar/specs/creator-workflow.md rename to .mstar/specs/creator/creator-workflow.md index 8d322d317..4ef59e469 100644 --- a/.mstar/specs/creator-workflow.md +++ b/.mstar/specs/creator/creator-workflow.md @@ -1,17 +1,28 @@ # Creator Workflow — Normative Specification **Status**: Shipped (V1.34 — 2026-06-05; V1.35 P4 partial; V1.39 — DF-53 full auto-chain + daemon continuity; **V1.40 Shipped** — DF-63 W5 `kb-extract` persistence via `novel-review-master sync_world_kb`: World-bound Works enqueue extract with `work.world_id`, `source_kind=work_chapter`, `source_locator={{preset.input.body_path}}`, `work_id`; worldless Works (legacy V1.39-and-earlier) skip World promotion; V1.79 additive SOUL visualization contract over memory fragments) +**Current authority**: Retained Work stage/field model only for workflow execution; the incomplete Creator runner and auto-chain/resume-chain entrances were removed in v1.193 P2-T1. Automatic progression and restart continuation below are historical shipped behavior, not current guarantees (§0). **Document class**: Feature line **Created**: 2026-06-04 -**Last updated**: 2026-07-01 — V1.79 SOUL visualization contract note -**Scope**: Staged creator journey on **Work** (`intake → research → produce → review → persist`), built on shipped `creator run` + `run_intents` +**Last updated**: 2026-09-29 — separate retained state from retired runner/auto-chain behavior +**Scope**: Staged Work model (`intake → research → produce → review → persist`) and retained observable fields; historical preset dispatch/auto-chain contract; V1.79 read-only SOUL visualization **Coordinates with**: - [work-experience-model.md](work-experience-model.md) — Work entity, intake, run_intents -- [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) — novel `produce` artifacts and completion (Draft V1.36) -- [cli-spec.md](cli-spec.md) — `creator run ` (see §6.2D) and `creator bootstrap` -- [orchestration-engine.md](orchestration-engine.md) — presets, schedules, capabilities -- [agent-nexus-tool-bridge.md](agent-nexus-tool-bridge.md) — Agent-initiated context/tools (parallel channel) +- [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) — novel `produce` artifacts and completion (Draft V1.36) +- [cli-spec.md](../cli/cli-spec.md) — retained `creator works` atomic operations; retired `creator run` / `creator bootstrap` history is not a current entry contract +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — presets, schedules, capabilities +- [agent-nexus-tool-bridge.md](../agents/agent-nexus-tool-bridge.md) — Agent-initiated context/tools (parallel channel) + +--- + +## 0. Current workflow boundary (v1.193 P2-T1) + +The stage vocabulary and stored Work state remain: `current_stage`, `stage_status`, `current_chapter`, `auto_chain_enabled`, `driver_schedule_id`, and `auto_chain_interrupted` are retained in [`crates/nexus-local-db/src/works.rs`](../../../crates/nexus-local-db/src/works.rs) (`WorkRecord`, `WORKS_COLUMNS`). Retained `creator works` commands expose Work state and atomic operations; **field persistence or visibility does not promise automatic stage dispatch, a live driver, or restart resume**. + +[`apps/nexus42/src/commands/creator/works/mod.rs`](../../../apps/nexus42/src/commands/creator/works/mod.rs) records the v1.193 P2-T1 removal of the incomplete Creator runner and `works intake` / `works resume-chain`. Its status output still reports `auto_chain_enabled`, `driver_schedule_id`, and interrupted state, but deliberately advertises no resume remediation command. The generic `creator run ` entry is also retired, with no replacement CLI preset-dispatch entrance; see [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) §0. + +**Reading boundary:** the execution rules, command journeys, automatic full-stage/chapter progression, and daemon restart continuation in §1–§7 are preserved as shipped history, not present-day scheduling instructions. The stage/field vocabulary and §5.6 SOUL read contract remain distinct from those retired execution claims. --- @@ -23,12 +34,14 @@ The Work loop shipped in V1.33 centered on Creative Brief Intake and `novel-writ intake → research → produce → review → persist ``` -without introducing a second scheduler or replacing World/KB SSOT. After V1.35 P4, `creator bootstrap` chains intake → produce by default (`--chain-novel-writing`, default true). **V1.39** ships full-stage `--auto-chain` (default **true**, opt-out `--no-auto-chain`): while the daemon is online, stages advance through `research → produce → review → persist` per chapter without a manual preset dispatch at each boundary. Daemon restart resumes from a Work continuation checkpoint (DF-68). +**Historical shipped behavior (retired v1.193 P2-T1):** the workflow reused the existing scheduler and World/KB SSOT. After V1.35 P4, `creator bootstrap` chained intake → produce by default (`--chain-novel-writing`, default true). **V1.39** shipped full-stage `--auto-chain` (default **true**, opt-out `--no-auto-chain`): while the daemon was online, stages advanced through `research → produce → review → persist` per chapter without a manual preset dispatch at each boundary. Daemon restart resumed from a Work continuation checkpoint (DF-68). These are not guarantees of the retained stage fields (§0). --- ## 2. Relationship to Work model +> The table records the shipped relationship. Its onboarding and preset-runner progression entries are historical; current CLI operations are the retained `creator works` families (§0). + | Concept | Work model (baseline) | Staged workflow (this spec) | | --- | --- | --- | | Work container | Shipped | Extended with `stage`, `stage_status` | @@ -52,6 +65,8 @@ without introducing a second scheduler or replacing World/KB SSOT. After V1.35 P ## 3. Stage model +> Stage identifiers and stored fields remain part of the Work model. The schedule-driven meanings, force-skip rules, and stage-gate command examples below describe the historical runner; they do not supply a current dispatch or resume entrance (§0). + ### 3.1 Stage identifiers (closed enum) | `stage` | Meaning | Typical preset(s) | `run_intents` | @@ -93,15 +108,15 @@ creator run [] # e.g. creator run research, creator run nov --- -## 4. Preset chain (normative mapping) +## 4. Preset chain (historical shipped mapping) | Stage | Preset ID | Notes | | --- | --- | --- | | `intake` | `creative-brief-intake` | Shipped V1.33 | | `research` | `research` | May append references to Work context | -| `produce` | `novel-writing` | Uses `creative_brief` + `inspiration_log`; novel profile writes to `Works//` per [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) | -| `review` | `novel-chapter-review` | V1.47 P0: renamed from `reflection-loop` (compass §0.1 #6). Persists ≥1 finding per review pass via the supervisor terminal hook; see [novel-writing/quality-loop.md §8](novel-writing/quality-loop.md#8-reflection-loop-output-contract-v147-draft). | -| `persist` | `kb-extract` (via queue) + CLI memory review | **V1.40 P3**: World-bound novel Works enqueue extract with `work.world_id`; worldless Works skip World promotion. See [novel-writing/workflow-profile.md §3.5.1.5](novel-writing/workflow-profile.md). | +| `produce` | `novel-writing` | Uses `creative_brief` + `inspiration_log`; novel profile writes to `Works//` per [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) | +| `review` | `novel-chapter-review` | V1.47 P0: renamed from `reflection-loop` (compass §0.1 #6). Persists ≥1 finding per review pass via the supervisor terminal hook; see [novel-writing/quality-loop.md §8](../novel-writing/quality-loop.md#8-reflection-loop-output-contract-v147-shipped). | +| `persist` | `kb-extract` (via queue) + CLI memory review | **V1.40 P3**: World-bound novel Works enqueue extract with `work.world_id`; worldless Works skip World promotion. See [novel-writing/workflow-profile.md §3.5.1.5](../novel-writing/workflow-profile.md). | P2 may add wiring presets or seeds only; **no** new conditional `next.kind`. @@ -109,6 +124,8 @@ P2 may add wiring presets or seeds only; **no** new conditional `next.kind`. ## 5. User journeys +> **Historical execution journeys:** §5.1–§5.5 retain the shipped CLI/auto-chain record, including command spellings removed or migrated since then. They are not runnable current instructions. §5.6 is the separate retained SOUL visualization contract. + ### 5.1 Happy path (explicit stages) ```text @@ -137,7 +154,7 @@ Does **not** advance `current_stage`; merges into `inspiration_log` and schedule `daemon schedule` remains valid; schedules created via `creator run ` **must** record `work_id` and stage id in schedule seed/metadata (wire key `fl_e_stage` in V1.34 implementation). -### 5.4 Daemon-attached auto-chain (V1.39 historical design) +### 5.4 Daemon-attached auto-chain (V1.39 shipped history; retired v1.193 P2-T1) When `auto_chain_enabled` on a Work (default true for new starts): @@ -148,15 +165,7 @@ When `auto_chain_enabled` on a Work (default true for new starts): `creator run resume ` recovers when auto-resume did not run or user disabled auto-chain. -The V1.39 list above is retained as historical workflow intent. Current -orchestration checkpoint/re-drive behavior is narrower and source-backed by -[`daemon-runtime.md`](daemon-runtime.md) §19: checkpoints persist position and -context rather than a completed-stage ledger; daemon boot re-drives only -non-terminal, readable, non-failed sessions with live converge/merge join -state and a reconstructed runner. `nexus42 ops inspect [SESSION_ID] [--json]` -is read-only and never triggers resume. The current Work auto-chain recovery -command is `nexus42 creator works resume-chain`, migrated from the historical -`creator run resume` spelling above. +**Retirement boundary:** the V1.39 list above is historical shipped behavior. Both the old `creator run resume` spelling and its later `creator works resume-chain` entrance are removed; no current Work restart-continuation command is claimed. The retained checkpoint fields are observable state only (§0), not evidence of a resumed chain. [daemon-runtime.md](../archived/daemon-runtime.md) is itself a retired-host record and does not restore this execution path. ### 5.5 Side-input lane (V1.39 extension) @@ -183,6 +192,8 @@ Wire contract: `schemas/daemon-api/memory/memory-fragment-info.schema.json` exte ## 6. Conflicts and non-goals +> Execution-related rows below are historical shipped constraints, including auto-chain, completion-lock tick suppression, multi-Work scheduling, and the former CLI IA. Retained state/atomic operations do not re-enable those execution entrances (§0). + | Topic | Rule | | --- | --- | | Work vs `creator kb --scope work` | Index entries may tag `work_id`; index does not define Work | @@ -190,17 +201,17 @@ Wire contract: `schemas/daemon-api/memory/memory-fragment-info.schema.json` exte | Conditional routing | **Not** used for stage selection (DF-56) | | `--auto-chain` | **V1.39 target (DF-53)**: default true for full FL-E chain + chapter outer loop; `--no-auto-chain` opt-out; manual `creator run ` dispatch still valid for power users | | Novel project init | Separate preset `novel-project-init` (DF-58); **not** part of `novel-writing` auto-chain | -| Novel completion | Work `status == completed` stops further `novel-writing`; V1.41 extends `mark_work_completed` per [novel-writing/multi-work-lifecycle.md](novel-writing/multi-work-lifecycle.md) (DF-60) | +| Novel completion | Work `status == completed` stops further `novel-writing`; V1.41 extends `mark_work_completed` per [novel-writing/multi-work-lifecycle.md](../novel-writing/multi-work-lifecycle.md) (DF-60) | | Completion-lock | While `.completion-lock.json` exists, auto-chain **must not** tick that Work; after release, `resume --reopen` may resume same `work_id` (V1.41 P0) | | Runtime lock | `works.runtime_lock_holder` blocks concurrent mutating CLI/API on same Work (V1.41 P0) | | Multi-Work concurrency | Multiple Works may auto-chain concurrently; pool `active` is CLI default only (DF-60/61) | -| Selection pool | `creator works pool` + `works use` via [novel-writing/work-pool.md](novel-writing/work-pool.md); not a Work profile (DF-61) | +| Selection pool | `creator works pool` + `works use` via [novel-writing/work-pool.md](../novel-writing/work-pool.md); not a Work profile (DF-61) | | CLI IA | `creator run` = single-Work actions; `creator works` = list/status/use/pool (V1.41) | | Platform cloud assemble | Not part of this workflow; see agent-nexus-tool-bridge `policy_blocked` | --- -## 7. Acceptance (spec-level) +## 7. Acceptance (historical spec-level) 1. Stage enum and preset mapping are stable in cli-spec and this document. 2. The preset runner rejects wrong stage order without `--force-gates` (stage gate validation inside `creator run `). @@ -211,8 +222,8 @@ Wire contract: `schemas/daemon-api/memory/memory-fragment-info.schema.json` exte ## V1.45 supersession (P-last promotion) -**Superseded by**: [creator-run-preset-entry.md](creator-run-preset-entry.md) (Shipped Master V1.45). FL-E CLI table is now part of the canonical Master body — see §3.3 (`research` / `novel-writing` / `reflection-loop` / `kb-extract` preset ids) and §2 three-plane IA. +**Historical supersession:** [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) shipped as the V1.45 Master and superseded the FL-E CLI table with preset-id grammar and three-plane IA. That runner was retired in v1.193 P2-T1; its historical promotion is not current dispatch authority. Current workflow scope is §0. --- -*Normative staged creator workflow. Shipped V1.34.* \ No newline at end of file +*Normative for retained Work stage/field vocabulary and the separate SOUL read contract; execution and auto-chain sections preserve V1.34–V1.45 shipped history, retired in v1.193 P2-T1 (§0).* \ No newline at end of file diff --git a/.mstar/specs/essay-profile.md b/.mstar/specs/creator/essay-profile.md similarity index 78% rename from .mstar/specs/essay-profile.md rename to .mstar/specs/creator/essay-profile.md index 90d0de159..d321d5a13 100644 --- a/.mstar/specs/essay-profile.md +++ b/.mstar/specs/creator/essay-profile.md @@ -3,16 +3,16 @@ **Status**: Shipped (V1.63) — essay profile production-ready: scaffold (ScaffoldTransaction), `essay-writing` preset (7-state chain), 4-dimension quality rubric (blocking with `--force-gates` override), completion detection, optional KB extraction. **Document class**: Feature line **Created**: 2026-06-19 -**Last updated**: 2026-06-24 (V1.63 Shipped — Draft → Shipped promotion). +**Last updated**: 2026-09-29 — authority aligned with V1.63 shipped status (Draft → Shipped promotion: 2026-06-24). **Scope**: `work_profile: essay` on generic **Work** — artifact layout under `Works//`, templates, stage chain, completion semantics **Coordinates with**: - [work-experience-model.md](work-experience-model.md) — generic Work entity - [creator-workflow.md](creator-workflow.md) — FL-E stage model -- [cli-spec.md](cli-spec.md) — creator entry and workspace layout -- [orchestration-engine.md](orchestration-engine.md) — preset execution model -- [entity-scope-model.md](entity-scope-model.md) — optional World/KB binding boundaries -- [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) — prior `work_profile: novel` Feature line pattern +- [cli-spec.md](../cli/cli-spec.md) — creator entry and workspace layout +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — preset execution model +- [entity-scope-model.md](../architecture/entity-scope-model.md) — optional World/KB binding boundaries +- [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) — prior `work_profile: novel` Feature line pattern --- @@ -131,7 +131,7 @@ Allowed context: - A single location KB context block when the essay is setting-focused. - No automatic World KB promotion by default. -The essay profile must not introduce a per-Work `Worldbuilding/` subtree. Cross-Work facts remain in World KB per [entity-scope-model.md](entity-scope-model.md). +The essay profile must not introduce a per-Work `Worldbuilding/` subtree. Cross-Work facts remain in World KB per [entity-scope-model.md](../architecture/entity-scope-model.md). --- @@ -163,9 +163,11 @@ AND works.intake_status == complete Completion does not enqueue a next chapter, next volume, or new Work. Reopening an essay Work follows the generic Work reopen path, not the novel completion-lock path unless a future plan explicitly generalizes that lock. +**Shipped implementation anchors:** [`202606190004_work_profile_essay.sql`](../../../crates/nexus-local-db/migrations/202606190004_work_profile_essay.sql) added `essay` to the stored profile constraint; [`crates/nexus-local-db/src/works.rs`](../../../crates/nexus-local-db/src/works.rs) provides `is_essay_profile`; [`crates/nexus-local-db/src/work_chapters.rs`](../../../crates/nexus-local-db/src/work_chapters.rs) provides `is_essay_complete` (intake complete + finalized draft, not novel chapter completion). [`crates/nexus-core/src/works.rs`](../../../crates/nexus-core/src/works.rs) invokes that completion check for essay Works and promotes `works.status` to `completed` on its writable path. + --- -## 9. Acceptance (V1.52 draft) +## 9. Acceptance (historical V1.52 draft) 1. Essay layout is distinct from novel layout (`Drafts/` not `Stories/`). 2. Stage chain is single-artifact and chapter-free. @@ -174,4 +176,4 @@ Completion does not enqueue a next chapter, next volume, or new Work. Reopening --- -*Draft V1.52 Feature line. Implementation authority is active only while V1.52 compass is active; P-last promotes or revises after T-A P2 evidence.* +*Shipped V1.63 Feature line — normative for the essay profile described here, including the completion contract and implementation anchors in §8. §9 preserves V1.52 draft acceptance as historical context; implementation authority is not conditional on the V1.52 compass remaining active.* diff --git a/.mstar/specs/game-bible-profile.md b/.mstar/specs/creator/game-bible-profile.md similarity index 97% rename from .mstar/specs/game-bible-profile.md rename to .mstar/specs/creator/game-bible-profile.md index 8c2a4e4e4..b37fc73ee 100644 --- a/.mstar/specs/game-bible-profile.md +++ b/.mstar/specs/creator/game-bible-profile.md @@ -8,12 +8,12 @@ **Coordinates with**: - [essay-profile.md](essay-profile.md) — first non-novel Feature line pattern (structural template) -- [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) — novel baseline (contrast reference) +- [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) — novel baseline (contrast reference) - [work-experience-model.md](work-experience-model.md) — generic Work entity - [creator-workflow.md](creator-workflow.md) — FL-E stage model -- [cli-spec.md](cli-spec.md) — creator entry and workspace layout -- [orchestration-engine.md](orchestration-engine.md) — preset execution model -- [entity-scope-model.md](entity-scope-model.md) — World/KB binding and BlockType taxonomy +- [cli-spec.md](../cli/cli-spec.md) — creator entry and workspace layout +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — preset execution model +- [entity-scope-model.md](../architecture/entity-scope-model.md) — World/KB binding and BlockType taxonomy - Prior Exploration: the non-novel profiles roadmap (targets since promoted to Feature line specs) --- @@ -274,7 +274,7 @@ When bound: - KB entries created from design facts use `game_bible_category` (see §7 KB Taxonomy). - Future V1.55+ `design-writing` preset may pull World KB context for consistency checks. -The game-bible profile must not introduce a per-Work `Worldbuilding/` subtree. Cross-Work facts remain in World KB per [entity-scope-model.md](entity-scope-model.md). +The game-bible profile must not introduce a per-Work `Worldbuilding/` subtree. Cross-Work facts remain in World KB per [entity-scope-model.md](../architecture/entity-scope-model.md). --- diff --git a/.mstar/specs/script-profile.md b/.mstar/specs/creator/script-profile.md similarity index 97% rename from .mstar/specs/script-profile.md rename to .mstar/specs/creator/script-profile.md index c10692b5f..e0727c769 100644 --- a/.mstar/specs/script-profile.md +++ b/.mstar/specs/creator/script-profile.md @@ -9,12 +9,12 @@ - [essay-profile.md](essay-profile.md) — first non-novel Feature line pattern (structural template) - [game-bible-profile.md](game-bible-profile.md) — second non-novel profile (Depth 3.5 Master — template for this spec) -- [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) — novel baseline (contrast reference) +- [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) — novel baseline (contrast reference) - [work-experience-model.md](work-experience-model.md) — generic Work entity - [creator-workflow.md](creator-workflow.md) — FL-E stage model -- [cli-spec.md](cli-spec.md) — creator entry and workspace layout -- [orchestration-engine.md](orchestration-engine.md) — preset execution model -- [entity-scope-model.md](entity-scope-model.md) — World/KB binding and BlockType taxonomy +- [cli-spec.md](../cli/cli-spec.md) — creator entry and workspace layout +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — preset execution model +- [entity-scope-model.md](../architecture/entity-scope-model.md) — World/KB binding and BlockType taxonomy - Prior Exploration: the non-novel profiles roadmap (targets since promoted to Feature line specs) --- @@ -220,7 +220,7 @@ When bound: - KB entries created from script facts use `script_category` (see §7 KB Taxonomy). - The `script-writing` preset pulls World KB context for character/location consistency on the `draft` stage. -The script profile must not introduce a per-Work `Worldbuilding/` subtree. Cross-Work facts remain in World KB per [entity-scope-model.md](entity-scope-model.md). +The script profile must not introduce a per-Work `Worldbuilding/` subtree. Cross-Work facts remain in World KB per [entity-scope-model.md](../architecture/entity-scope-model.md). --- diff --git a/.mstar/specs/work-experience-model.md b/.mstar/specs/creator/work-experience-model.md similarity index 80% rename from .mstar/specs/work-experience-model.md rename to .mstar/specs/creator/work-experience-model.md index 89f2cbed3..2c429acff 100644 --- a/.mstar/specs/work-experience-model.md +++ b/.mstar/specs/creator/work-experience-model.md @@ -7,11 +7,11 @@ **Scope**: Product-level **Work** container, user journey, Creative Brief Intake, preset run intents, and relationship to workspace / World / schedules **Coordinates with**: -- [cli-spec.md](cli-spec.md) — `creator run`, `system preset` -- [orchestration-engine.md](orchestration-engine.md) — presets, schedules, `llm_judge`, run_intents -- [creator-schedule-and-core-context.md](creator-schedule-and-core-context.md) — schedule + core_context -- [entity-scope-model.md](entity-scope-model.md) — Creator / World hierarchy -- [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) — `work_profile: novel` extension (Draft V1.36) +- [cli-spec.md](../cli/cli-spec.md) — `creator run`, `system preset` +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — presets, schedules, `llm_judge`, run_intents +- [creator-schedule-and-core-context.md](../orchestration/creator-schedule-and-core-context.md) — schedule + core_context +- [entity-scope-model.md](../architecture/entity-scope-model.md) — Creator / World hierarchy +- [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) — `work_profile: novel` extension (Draft V1.36) - [essay-profile.md](essay-profile.md) — `work_profile: essay` extension (Draft V1.52; shipped V1.63) --- @@ -34,7 +34,7 @@ Without Work, users must understand `daemon schedule`, preset IDs, seed strings, | Term | Meaning | Owning layer | | --- | --- | --- | | **Workspace** | Per-creator operational root (`workspace_slug`), `state.db`, filesystem layout | `nexus-home-layout`, CLI `creator workspace` | -| **Work** | A single **creative effort** with stable `work_id`, long-term goal, structured brief, optional World binding, inspiration log, linked runs | **V1.33** — `state.db` table + CLI `creator run` | +| **Work** | A single **creative effort** with stable `work_id`, long-term goal, structured brief, optional World binding, inspiration log, linked runs | Shipped V1.33; current persistence: `nexus-local-db` (`works` table/DAO); operations: `nexus-core` + CLI `creator works` (§3.3) | | **Work index** | CLI `creator kb --scope work` local file index | Daemon `/v1/local/kb/entries` — **not** Work | | **World** | Narrative universe (`world_id`) with timeline and World KB | `nexus-narrative`, `nexus-kb` | | **Creative brief** | Structured output of intake; required fields before `novel-writing` production states | Work.creative_brief (JSON) | @@ -78,6 +78,12 @@ Without Work, users must understand `daemon schedule`, preset IDs, seed strings, - **Not** in `/` user-visible tree (runtime metadata only). - **Not** duplicated in SOUL.md (SOUL remains creator identity; Work is project-scoped). +**Current implementation ownership** (the V1.33 shipped product history remains unchanged): + +- **Creator aggregate / local identity:** [`crates/nexus-creator/src/creator.rs`](../../../crates/nexus-creator/src/creator.rs) defines `Creator`, its identity/status, and user linkage. `nexus-creator` does **not** implement the Work store or Work operations. +- **Work persistence:** each `(creator_id, workspace_slug)` has its `state.db` Work store. `nexus-local-db` owns the `works` tables/migrations (starting with [`20260604_works_table.sql`](../../../crates/nexus-local-db/migrations/20260604_works_table.sql)) and the [`works.rs` DAO / `WorkRecord`](../../../crates/nexus-local-db/src/works.rs); chapter persistence is in [`work_chapters.rs`](../../../crates/nexus-local-db/src/work_chapters.rs). Work is not a nested field of the Creator aggregate. +- **Work operations / CLI:** [`crates/nexus-core/src/works.rs`](../../../crates/nexus-core/src/works.rs) owns the typed Work service operations used by the retained [`creator works` command families](../../../apps/nexus42/src/commands/creator/works/mod.rs), including selection/status/pool, inspiration, reopening, completion-lock, and chapter reconciliation. Historical `creator run` spellings in this spec are not current implementation owners or dispatch entrances; see [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) §0 for the v1.193 P2-T1 retirement. + ### 3.4 Invariants 1. A Work is **never** a workspace and **never** a World. @@ -160,7 +166,7 @@ Policy: only presets with `work_init` appear in the default bootstrap intake lis ### 6.1 Prerequisites -Same as [cli-spec.md](cli-spec.md) §7: workspace init, daemon start, ACP agent use, active creator. +Same as [cli-spec.md](../cli/cli-spec.md) §7: workspace init, daemon start, ACP agent use, active creator. ### 6.2 Start Work (`creator bootstrap`) @@ -227,7 +233,7 @@ Shows: intake status, linked schedules, last session state, world binding. ## 8. Quality gates (`llm_judge`) -V1.33 requires runtime alignment with [orchestration-engine.md](orchestration-engine.md): +V1.33 requires runtime alignment with [orchestration-engine.md](../orchestration/orchestration-engine.md): - `exit_when.kind: llm_judge` must invoke declared `judge_capability` (default `judge.llm`) with `template_file`. - Until **conditional routing** ships, NOGO results in `WaitForInput` on the **same** linear edge (user may `daemon schedule advance` or append context via `creator run continue`). @@ -284,4 +290,4 @@ FL-E reuses V1.33 `creator bootstrap` (composite onboarding) and `creator run

/` layout + chapter frontmatter | `workflow-profile.md` | | Per-Work cron staggering (3-role) | `workflow-profile.md` §11 | | Per-Work auto-chronology (opt-in) | `workflow-profile.md` §11.5 | -| Findings lifecycle + review chain | `quality-loop.md` §2 (6-state F6) | +| Cross-profile findings lifecycle, executor routing, UI remediation | [findings-lifecycle.md](../contracts/findings-lifecycle.md) (Master) | +| Novel findings produce side / review chain | `quality-loop.md` §2 | | F### / E### index files | `workflow-profile.md` §4.6 (5-col schema) | -| World KB promotion state machine | [entity-scope-model.md §5.5](../entity-scope-model.md#55-world-kb-promotion-state-machine-v150-normative) | +| World KB promotion state machine | [entity-scope-model.md §5.5](../architecture/entity-scope-model.md#55-world-kb-promotion-state-machine-v150-normative) | | Author happy path + remediation copy | `author-experience.md` | | On-demand chapter audit | `manuscript-audit.md` | | Multi-work completion + locks | `multi-work-lifecycle.md` | | Pool / default Work | `work-pool.md` | | Sync scan roots | `sync-contract.md` (layout SSOT: `workflow-profile.md` §3, §7) | -| Top-level CLI groups / preset dispatch | [cli-spec.md](../cli-spec.md), [creator-run-preset-entry.md](../creator-run-preset-entry.md) | +| Top-level CLI groups / preset dispatch | Current authority: [cli-spec.md §6.0B](../cli/cli-spec.md#60b-v2-命令信息架构权威). [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) is historical: generic runner retired v1.193 P2-T1; no replacement CLI preset-dispatch entrance. | --- diff --git a/.mstar/specs/novel-writing/author-experience.md b/.mstar/specs/novel-writing/author-experience.md index 67d084b48..14c0eb397 100644 --- a/.mstar/specs/novel-writing/author-experience.md +++ b/.mstar/specs/novel-writing/author-experience.md @@ -7,12 +7,12 @@ **Scope**: End-user **ongoing serial** happy path — normative CLI surfaces, remediation chains, and author visibility (spec-only SSOT; **no** `docs/novel-writing-quickstart.md` after P1) **Coordinates with**: -- [creator-run-preset-entry.md](../creator-run-preset-entry.md) — **Shipped Master V1.45** — CLI IA, preset ids, flags (remediation target for runtime copy) -- [creator-centric-entry-model.md](../creator-centric-entry-model.md) — §3.1 local bootstrap (≤7 steps) -- [cli-spec.md](../cli-spec.md) — §7 first-run UX principles +- [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) — **Shipped Master V1.45** — CLI IA, preset ids, flags (remediation target for runtime copy) +- [creator-centric-entry-model.md](../archived/creator-centric-entry-model.md) — §3.1 local bootstrap (≤7 steps) +- [cli-spec.md](../cli/cli-spec.md) — §7 first-run UX principles - [workflow-profile.md](workflow-profile.md) — artifact layout + completion §6 - [quality-loop.md](quality-loop.md) — findings + review visibility -- [creator-workflow.md](../creator-workflow.md) — FL-E stage names in narrative +- [creator-workflow.md](../creator/creator-workflow.md) — FL-E stage names in narrative --- @@ -37,13 +37,13 @@ V1.36–V1.45 implemented novel-writing **capabilities** across crates. V1.46 do | §4.1 `--json` contract | `findings[]` + optional `findings_stale` | P0 | | §5 Residual pointer | local process (not clone SSOT) | P-last | -**Invariant**: Every command in §3 must exist in [creator-run-preset-entry.md](../creator-run-preset-entry.md) or [cli-spec.md](../cli-spec.md) at ship time. +**Invariant**: Every command in §3 must exist in [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) or [cli-spec.md](../cli/cli-spec.md) at ship time. --- ## 3. Author path — ongoing serial (Part I) -> **CLI detail**: [creator-run-preset-entry.md](../creator-run-preset-entry.md). This section is the **narrative** happy path only. +> **CLI detail**: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md). This section is the **narrative** happy path only. ### 3.1 Prerequisites and bootstrap @@ -63,7 +63,7 @@ nexus42 creator bootstrap --idea "A solpac noir detective story in a floating ca # → Work created, init preset, intake → produce chain ``` -Gate/scaffold failures: remediation cites this spec §3.2 or [creator-run-preset-entry.md](../creator-run-preset-entry.md) bootstrap section — **not** a quickstart file. +Gate/scaffold failures: remediation cites this spec §3.2 or [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) bootstrap section — **not** a quickstart file. ### 3.3 First chapter and serial production @@ -165,7 +165,7 @@ JSON-path fetch by the slower of the two rather than their sum. When error/remediation conditions occur, user-visible output must include a **single-line next action** referencing: -- **CLI commands / preset ids** → [creator-run-preset-entry.md](../creator-run-preset-entry.md) +- **CLI commands / preset ids** → [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) - **Author narrative** → this document §3 | Condition | Minimum remediation | @@ -200,7 +200,7 @@ At V1.46 P-last: > **Status**: Shipped (V1.49 P2) — P2 overlay merged into Master. > **Plan**: -> **Cross-refs**: findings lifecycle → [quality-loop.md §2](quality-loop.md#2-findings-lifecycle) (6-state V1.49 P0); narrative indexes → [workflow-profile.md §4.6](workflow-profile.md#46-narrative-indexes--f-e-runtime-v149-p1) (V1.49 P1) +> **Cross-refs**: findings lifecycle → [quality-loop.md §2](quality-loop.md#2-findings-lifecycle) (6-state V1.49 P0); narrative indexes → [workflow-profile.md §4.6](workflow-profile.md#46-narrative-indexes--f--e-runtime-v149-p1) (V1.49 P1) ### 8.1 Intake re-trigger on existing Work (R-V147P1-01) diff --git a/.mstar/specs/novel-writing/manuscript-audit.md b/.mstar/specs/novel-writing/manuscript-audit.md index 268b5ca04..16f4deb5f 100644 --- a/.mstar/specs/novel-writing/manuscript-audit.md +++ b/.mstar/specs/novel-writing/manuscript-audit.md @@ -9,10 +9,10 @@ - [quality-loop.md](quality-loop.md) — findings lifecycle; review routing - [workflow-profile.md](workflow-profile.md) — chapter paths, `Logs/review/`, 五问 baseline -- [creator-workflow.md](../creator-workflow.md) — FL-E stages (audit is **out-of-band**) -- [cli-spec.md](../cli-spec.md) — `creator run audit-chapter` IA (P0 implement) -- [entity-scope-model.md](../entity-scope-model.md) — World-bound extract mode -- [world-kb-runtime-architecture.md](../world-kb-runtime-architecture.md) — `kb.extract_work` on-demand path +- [creator-workflow.md](../creator/creator-workflow.md) — FL-E stages (audit is **out-of-band**) +- [cli-spec.md](../cli/cli-spec.md) — `creator run audit-chapter` IA (P0 implement) +- [entity-scope-model.md](../architecture/entity-scope-model.md) — World-bound extract mode +- [world-kb-runtime-architecture.md](../architecture/world-kb-runtime-architecture.md) — `kb.extract_work` on-demand path **Tracker**: DF-69 @@ -140,4 +140,4 @@ At V1.44 P-last hygiene: ## V1.45 supersession (P-last promotion) -**Superseded by**: [creator-run-preset-entry.md](../creator-run-preset-entry.md) (Shipped Master V1.45). The split preset ids (`novel-manuscript-audit-review` / `novel-manuscript-audit-extract`), DEPRECATED parent dir deletion, and `cli_args` declaration are now part of the canonical Master body. +**Superseded by**: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (Shipped Master V1.45). The split preset ids (`novel-manuscript-audit-review` / `novel-manuscript-audit-extract`), DEPRECATED parent dir deletion, and `cli_args` declaration are now part of the canonical Master body. diff --git a/.mstar/specs/novel-writing/multi-work-lifecycle.md b/.mstar/specs/novel-writing/multi-work-lifecycle.md index 6980b8f9b..e7382009c 100644 --- a/.mstar/specs/novel-writing/multi-work-lifecycle.md +++ b/.mstar/specs/novel-writing/multi-work-lifecycle.md @@ -8,10 +8,10 @@ - [workflow-profile.md](workflow-profile.md) — §6 completion criteria - [work-pool.md](work-pool.md) — default Work pointer (`novel_pool_entries.status = active`) -- [creator-workflow.md](../creator-workflow.md) — auto-chain pause during completion-lock; runtime lock on mutating paths -- [cli-spec.md](../cli-spec.md) — `creator works`, `creator bootstrap --from-work`, resume reopen -- [work-experience-model.md](../work-experience-model.md) — Work is single-Work; pool `active` is CLI default only -- [agent-nexus-tool-bridge.md](../agent-nexus-tool-bridge.md) — `nexus.work.patch` obeys same locks +- [creator-workflow.md](../creator/creator-workflow.md) — auto-chain pause during completion-lock; runtime lock on mutating paths +- [cli-spec.md](../cli/cli-spec.md) — `creator works`, `creator bootstrap --from-work`, resume reopen +- [work-experience-model.md](../creator/work-experience-model.md) — Work is single-Work; pool `active` is CLI default only +- [agent-nexus-tool-bridge.md](../agents/agent-nexus-tool-bridge.md) — `nexus.work.patch` obeys same locks **V1.42 amend**: §4.2 production acquire gap — P0 @@ -144,7 +144,7 @@ Daemon API and `nexus.work.patch` **must** use the same acquire/release paths as ## 5. CLI surfaces (summary) -Full flags in [cli-spec.md](../cli-spec.md) §6.2D / §6.2H. +Full flags in [cli-spec.md](../cli/cli-spec.md) §6.2D / §6.2H. ### 5.1 `creator run ` — strategy execution diff --git a/.mstar/specs/novel-writing/quality-loop.md b/.mstar/specs/novel-writing/quality-loop.md index b4f003f19..90bcfca1c 100644 --- a/.mstar/specs/novel-writing/quality-loop.md +++ b/.mstar/specs/novel-writing/quality-loop.md @@ -3,14 +3,14 @@ **Status**: Normative — V1.51 Shipped (findings lifecycle F6 + KB closure overwrites/supersedes integrated) **Document class**: Feature line (quality-loop supplement) **Created**: 2026-06-09 -**Last updated**: 2026-06-19 (V1.51 P-last — findings lifecycle F6 marked Normative; no runtime change) +**Last updated**: 2026-09-29 (authority routing aligned with the cross-profile findings Master; V1.49 lifecycle history retained) **Scope**: Local-first quality loop for `work_profile: novel` — findings, review routing, rules, logs, 96h escalation, on-demand audit cross-refs **Coordinates with**: - [workflow-profile.md](workflow-profile.md) — layout, preset gates, completion (quality-loop detail in sibling spec) -- [creator-workflow.md](../creator-workflow.md) — FL-E `review` stage and auto-chain -- [orchestration-engine.md](../orchestration-engine.md) — presets, daemon scheduled tasks -- [cli-spec.md](../cli-spec.md) — status/banner surfaces +- [creator-workflow.md](../creator/creator-workflow.md) — FL-E `review` stage and auto-chain +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — presets, daemon scheduled tasks +- [cli-spec.md](../cli/cli-spec.md) — status/banner surfaces - [manuscript-audit.md](manuscript-audit.md) — DF-69 on-demand audit (V1.44 P0) - [author-experience.md](author-experience.md) — quickstart §5 cross-refs (V1.43 shipped) @@ -54,6 +54,8 @@ Auto-chain must not fork driver when routing spawns auxiliary schedules; at most ### 2.3 Extended status enum (V1.49 P0 — F6 lifecycle) +> **Authority (§2.3–§2.4 and executor routing):** The root [Findings Lifecycle — Cross-Profile Master](../contracts/findings-lifecycle.md) owns the cross-profile six-state lifecycle, `target_executor` routing semantics, and UI remediation surface. The V1.49 enum and transition graph below are retained as historical context, not a second normative lifecycle authority. This spec retains only novel-specific producer-side responsibilities: review verdicts, finding creation, orchestration hooks, produce-prompt selection, and retention/prune. + V1.49 P0 extends the V1.39 three-state model (`open` / `resolved` / `wont_fix`) to a 6-state lifecycle: | Status | Meaning | @@ -299,4 +301,4 @@ V1.48 closes the novel quality loop: durable findings enrich the writing prompt, ## V1.45 supersession (P-last promotion) -**Superseded by**: [creator-run-preset-entry.md](../creator-run-preset-entry.md) (Shipped Master V1.45). The `novel-review-master` preset id + enqueue-only semantics + audit preset ids are now part of the canonical Master body. +**Superseded by**: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (Shipped Master V1.45). The `novel-review-master` preset id + enqueue-only semantics + audit preset ids are now part of the canonical Master body. diff --git a/.mstar/specs/novel-writing/sync-contract.md b/.mstar/specs/novel-writing/sync-contract.md index d83c60cc8..8065b5fac 100644 --- a/.mstar/specs/novel-writing/sync-contract.md +++ b/.mstar/specs/novel-writing/sync-contract.md @@ -1,14 +1,24 @@ # Novel-Writing Sync Module Contract -**Status**: Normative (module contract) — **V1.36 layout migration pending** (P2 implement) +**Status**: Normative — shipped library contract (V1.36 Works layout); not an integrated cloud upload path **Document class**: Companion -**Scope**: Workspace scan rules for novel-writing sync module +**Scope**: Filesystem chapter discovery and in-memory bundle construction for novel-writing artifacts +**Implementation owner**: [`nexus-orchestration::sync_module`](../../../crates/nexus-orchestration/src/sync_module.rs), exported by [`lib.rs`](../../../crates/nexus-orchestration/src/lib.rs) +**Last verified**: 2026-09-29 — implementation and consumer search; no runtime change **Primary layout SSOT**: [workflow-profile.md](workflow-profile.md) §3, §7 **Supersedes**: workspace-root `Stories//` scan rules (pre-1.0; no compatibility shims) -## 1. Artifact Discovery +## 0. Current — Implementation status and boundary -The sync module scans the workspace for novel-writing artifacts when `work_profile == novel`: +**Reading boundary:** §§0–5 describe the current shipped library. §6 preserves the original V1.36 target contract as historical design text; its data shapes, DB filtering, idempotency expectations, and transport proposal are not claims of current implementation. + +The V1.36 layout migration is implemented in `crates/nexus-orchestration/src/sync_module.rs`: `discover_works` scans `Works//Stories/`, and `build_story_bundle` / `build_story_bundle_with_db` construct `StoryBundle`s. The [V1.36 layout contract tests](../../../crates/nexus-orchestration/tests/sync_module_works_layout.rs) exercise discovery, exclusions, ordering, removal of the workspace-root fallback, and bundle construction. This is a retained, exported library contract, not a retired module. + +The discovery type is `DiscoveredWork`, not the earlier design name `NovelWorkArtifacts`. Searches of `apps/nexus-service`, `crates/nexus-core`, `tooling/`, and `packages/` found no implementation or consumer of these sync symbols; the scanner is not owned by `nexus-narrative` or `nexus-cloud-sync`. The current application/cloud sources do not call the scanner or bundle builders. **Shipped here means the library implementation, not end-to-end chapter upload** (see §5). + +## 1. Current — Artifact Discovery + +`discover_works(workspace_dir)` discovers artifacts by filesystem layout only. It does not read `works` or filter `work_profile`; a caller is responsible for selecting novel Works. ### Primary scan directories @@ -17,14 +27,95 @@ The sync module scans the workspace for novel-writing artifacts when `work_profi ### Discovery rules +- Only `.md` files **directly under** `Works//Stories/` are sync chapter candidates +- Hidden Work directories and hidden chapter files (starting with `.`) are skipped +- `README.md`, `foreshadowing.md`, and `event-index.md` are skipped. `Outlines/**`, `Logs/**`, and `Rules/**` are not scanned. Discovery reads filenames only; optional `work_chapters` metadata enrichment happens during bundle construction (§2), not by parsing frontmatter. +- `Works//Worldbuilding/` subtree is **not present** in V1.36 (world content lives in World KB per [entity-scope-model.md §5.4](../architecture/entity-scope-model.md) + [workflow-profile.md §3.5](workflow-profile.md)) +- Workspace-root `Stories//` is **not** scanned (legacy; removed pre-1.0) +- Each non-hidden directory under `Works/` with a `Stories/` directory yields a `DiscoveredWork`, even when its chapter list is empty. Works and chapter filenames are sorted alphabetically. Missing/unreadable `Works/` yields no Works; a missing `Stories/` skips that Work, while an unreadable `Stories/` leaves its chapter list empty. + +### Output per work + +```rust +struct DiscoveredWork { + work_ref: String, // directory name under Works/ + chapters: Vec, // sorted chapter filenames under Stories/ +} +``` + +## 2. Current — Bundle Inputs and Optional DB Enrichment + +The caller supplies `workspace_dir`, `world_id`, `work_id`, and the `DiscoveredWork`. These helpers do not look up the Work row, verify its profile or world binding, or skip completed Works. + +- `build_story_bundle` reads the discovered files as UTF-8, skips unreadable files, and computes SHA-256 hashes. It returns `None` when no files can be read or the chapter count cannot fit in `u32`; an empty but readable file is still included. +- `build_story_bundle_with_db` optionally queries `work_chapters` by `work_id` for `chapter`, `status`, and `actual_word_count`. It matches rows to filenames by parsing the chapter number from `ch[-suffix].md`. +- Without a DB pool, or without a matching row, `status` and `actual_word_count` remain `None`. A DB query failure returns `None`, not an unenriched bundle. +- No outline aggregate, frontmatter status parsing, or configurable completed-Work filtering is implemented by this module. + +Legacy `world_stories.story_ref` + workspace-root `Stories/` paths are **not** normative after V1.36 P2. + +## 3. Current — Output Bundle Shape + +The helpers produce the following in-memory Rust types, owned by `sync_module.rs`. `StoryBundle` is not the schema-generated platform `Bundle` wire envelope (§5): + +```rust +struct StoryBundle { + world_id: String, // caller supplies an empty string for a worldless Work + work_id: String, + work_ref: String, + chapters: Vec, + chapter_count: u32, + synced_at: String, // ISO 8601 +} + +struct ChapterContent { + filename: String, + content_hash: String, // SHA-256 of content + content: String, + status: Option, // optional work_chapters enrichment + actual_word_count: Option, // optional work_chapters enrichment +} +``` + +## 4. Current — Hashing and Repeated Builds + +- Unchanged chapter bytes produce unchanged SHA-256 `content_hash` values. +- Every build reads files again and sets `synced_at` to the current RFC 3339 timestamp. There is no persisted hash cache or unchanged-bundle suppression; whole-bundle identity is not guaranteed across calls. +- Builders preserve the supplied chapter list order; `discover_works` supplies alphabetical filename order within `Works//Stories/`. + +## 5. Current — Platform Handoff Boundary + +- The module constructs local `StoryBundle`s containing full chapter text; it does not serialize a platform request or call HTTP. +- **Current cloud path:** [`nexus42 platform sync push`](../cli/cli-spec.md#142-默认模式) delegates to [`commands/sync/mod.rs`](../../../apps/nexus42/src/commands/sync/mod.rs), which constructs a schema-generated `Bundle` via `nexus-cloud-sync::delta_bundle::BundleBuilder` and passes it to `SyncClient::push_bundle`. It does not invoke this chapter scanner or accept its `StoryBundle`. +- **Historical target (DR-54):** connecting the chapter library to cloud transport was a separate proposal, not evidence of shipped upload integration. Default sync must not upload full manuscript text; an explicit publication path is distinct from structured sync ([CLI Master §14.2](../cli/cli-spec.md#142-默认模式)). +- **Legacy (pre–V1.21):** the `nexus-sync` crate and daemon `POST /v1/local/sync/push` path are retired; they are not alternate scanner owners (see [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) §5–§6). +- Platform wire types remain schema-generated contracts; the local `StoryBundle` and `ChapterContent` above are not generated DTOs. Platform publish (DF-59) remains outside this module contract. + +--- + +## 6. Historical V1.36 target contract (as specified) + +> **Historical only — not current implementation authority.** The following text preserves the original §§1–5 from commit `5cadd8e86`, with only heading depth/numbering changed to nest the record here. These were the V1.36 target shapes and expectations, not evidence that profile filtering, Work-row lookup, unchanged-bundle suppression, or chapter upload shipped. Current behavior and ownership are documented separately in §§0–5 above; the current Status header supersedes the original migration label. + +### 6.1 Artifact Discovery + +The sync module scans the workspace for novel-writing artifacts when `work_profile == novel`: + +#### Primary scan directories + +- `Works//Stories/` — Chapter正文 files (`*.md`) only +- `Works//Outlines/` — **Not** scanned as chapters (metadata/planning) + +#### Discovery rules + - Only `.md` files **directly under** `Works//Stories/` are sync chapter candidates - Hidden files (starting with `.`) are skipped - `README.md`, `Outlines/**`, `Logs/**` are **never** chapter candidates. Per-chapter metadata is derived from the **`work_chapters` table** in `state.db` (per [workflow-profile.md §4.1](workflow-profile.md)); the legacy `work-status.md` file is removed in V1.36. -- `Works//Worldbuilding/` subtree is **not present** in V1.36 (world content lives in World KB per [entity-scope-model.md §5.4](../entity-scope-model.md) + [workflow-profile.md §3.5](workflow-profile.md)) +- `Works//Worldbuilding/` subtree is **not present** in V1.36 (world content lives in World KB per [entity-scope-model.md §5.4](../architecture/entity-scope-model.md) + [workflow-profile.md §3.5](workflow-profile.md)) - Workspace-root `Stories//` is **not** scanned (legacy; removed pre-1.0) - Each `work_ref` directory under `Works/` represents one novel Work's artifact tree -### Output per work +#### Output per work ``` NovelWorkArtifacts { @@ -40,7 +131,7 @@ Chapter { } ``` -## 2. Sync Input (from local DB) +### 6.2 Sync Input (from local DB) The sync module reads from `works` table (and related world binding when present): @@ -53,7 +144,7 @@ The sync module reads from `works` table (and related world binding when present Legacy `world_stories.story_ref` + workspace-root `Stories/` paths are **not** normative after V1.36 P2. -## 3. Output Bundle Shape +### 6.3 Output Bundle Shape The sync module produces a `StoryBundle` (wire name unchanged for contract stability) per novel Work: @@ -74,16 +165,16 @@ struct ChapterContent { } ``` -## 4. Idempotency +### 6.4 Idempotency - Repeated sync of the same Work produces the same bundle (content-hash based) - If no chapter files have changed since last sync, the bundle is not regenerated - Chapter ordering is alphabetical by filename within `Works//Stories/` -## 5. Platform Handoff Boundary +### 6.5 Platform Handoff Boundary - The sync module produces `StoryBundle`s - **Target (long-term):** platform upload is handled by **`nexus-cloud-sync`** when the CLI runs `nexus42 sync push` (cloud product line). The module does **not** call platform HTTP directly. **Durable roadmap:** DR-54. -- **Legacy (pre–V1.21):** some builds still route upload through the `nexus-sync` crate and `POST /v1/local/sync/push` on the daemon; that path is **retired** per [local-cloud-crate-architecture.md](../local-cloud-crate-architecture.md) §5–§6. +- **Legacy (pre–V1.21):** some builds still route upload through the `nexus-sync` crate and `POST /v1/local/sync/push` on the daemon; that path is **retired** per [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) §5–§6. - Wire bundles use types from `@42ch/nexus-contracts` / `schemas/domain/` + `schemas/platform/sync/` (no duplicate DTOs) - **V1.36 scope**: structured sync only; platform publish (DF-59) is explicitly OUT diff --git a/.mstar/specs/novel-writing/work-pool.md b/.mstar/specs/novel-writing/work-pool.md index 7a5ddf143..78c719b51 100644 --- a/.mstar/specs/novel-writing/work-pool.md +++ b/.mstar/specs/novel-writing/work-pool.md @@ -7,9 +7,9 @@ **Coordinates with**: - [multi-work-lifecycle.md](multi-work-lifecycle.md) — completion clears active; `works use` sets default -- [work-experience-model.md](../work-experience-model.md) — pool is **not** a Work profile -- [cli-spec.md](../cli-spec.md) — `creator works` command group -- [local-db-schema.md](../local-db-schema.md) — table definitions +- [work-experience-model.md](../creator/work-experience-model.md) — pool is **not** a Work profile +- [cli-spec.md](../cli/cli-spec.md) — `creator works` command group +- [local-db-schema.md](../runtime/local-db-schema.md) — table definitions --- @@ -73,7 +73,7 @@ Each inspiration item has: ### 3.4 Why `Pool/Ideas/` not `Works/_pool/` -Inspiration items are **creator-scoped**, not Work-scoped. An idea can outlive any single Work and may inspire multiple Works over time. The pool directory lives at the workspace root level (alongside `Works/`), not nested under any Work. See [`work-experience-model.md`](../work-experience-model.md) — pool is not a Work profile. +Inspiration items are **creator-scoped**, not Work-scoped. An idea can outlive any single Work and may inspire multiple Works over time. The pool directory lives at the workspace root level (alongside `Works/`), not nested under any Work. See [`work-experience-model.md`](../creator/work-experience-model.md) — pool is not a Work profile. ### 3.2 Table `inspiration_items` (intent) @@ -104,7 +104,7 @@ Daemon API `set_pool_active` (and CLI `creator works use` / `pool promote --set- - Request body **`creator_id` must match** the authenticated/active creator context. - Mismatch → **403 Forbidden** (not silent demote on wrong creator). -- Cross-reference [cli-spec.md](../cli-spec.md) §6.2D. +- Cross-reference [cli-spec.md](../cli/cli-spec.md) §6.2D. --- diff --git a/.mstar/specs/novel-writing/workflow-profile.md b/.mstar/specs/novel-writing/workflow-profile.md index 812c3fa4e..3d0477ed8 100644 --- a/.mstar/specs/novel-writing/workflow-profile.md +++ b/.mstar/specs/novel-writing/workflow-profile.md @@ -7,12 +7,12 @@ **Scope**: `work_profile: novel` on generic **Work** — artifact layout under `Works//`, templates, chapter status, completion semantics, sync boundaries **Coordinates with**: -- [work-experience-model.md](../work-experience-model.md) — generic Work entity -- [creator-workflow.md](../creator-workflow.md) — FL-E `produce` stage -- [cli-spec.md](../cli-spec.md) — workspace layout §13.1 +- [work-experience-model.md](../creator/work-experience-model.md) — generic Work entity +- [creator-workflow.md](../creator/creator-workflow.md) — FL-E `produce` stage +- [cli-spec.md](../cli/cli-spec.md) — workspace layout §13.1 - [sync-contract.md](sync-contract.md) — chapter discovery -- [orchestration-engine.md](../orchestration-engine.md) — `novel-writing` preset -- [entity-scope-model.md](../entity-scope-model.md) — World entity + World KB (`work_profile: novel` binds Work to World; world content is cross-Work, lives in World KB, NOT in per-Work `Worldbuilding/` subtree) +- [orchestration-engine.md](../orchestration/orchestration-engine.md) — `novel-writing` preset +- [entity-scope-model.md](../architecture/entity-scope-model.md) — World entity + World KB (`work_profile: novel` binds Work to World; world content is cross-Work, lives in World KB, NOT in per-Work `Worldbuilding/` subtree) --- @@ -47,7 +47,7 @@ On `works` table / Work API (additive): | `work_ref` | string | yes | Filesystem directory name: `Works//` | | `total_planned_chapters` | integer | no | Target chapter count for completion (default TBD in init preset) | | `current_chapter` | integer | no | Latest chapter number in progress | -| `world_id` | string (FK) | yes for new V1.40 novel Works | Bind to a World (per [entity-scope-model.md](../entity-scope-model.md) §5.4). Required for V1.40 Work creation/init; legacy `NULL` is allowed only when reading V1.39-and-earlier worldless Works. `novel-project-init` grill-me asks whether to create a new World or bind an existing one (see §3.5). | +| `world_id` | string (FK) | yes for new V1.40 novel Works | Bind to a World (per [entity-scope-model.md](../architecture/entity-scope-model.md) §5.4). Required for V1.40 Work creation/init; legacy `NULL` is allowed only when reading V1.39-and-earlier worldless Works. `novel-project-init` grill-me asks whether to create a new World or bind an existing one (see §3.5). | | `novel_completion_status` | enum | no | `in_progress` \| `completed` (mirrors Work.status when terminal) | **Invariant**: `work_ref` is stable for the life of the Work; renaming directory without DB update is unsupported pre-1.0. @@ -102,7 +102,7 @@ Non-novel `work_profile` values may use different subtrees under `Works//` directory is **one event in a World's timeline**, not the canonical home of characters, locations, society, or rules. The canonical home is **World KB** (per [entity-scope-model.md](../entity-scope-model.md) §5.4 World entity + `nexus-kb` crate). +**Key principle**: worldbuilding content is **cross-Work**, not per-Work. A `Works//` directory is **one event in a World's timeline**, not the canonical home of characters, locations, society, or rules. The canonical home is **World KB** (per [entity-scope-model.md](../architecture/entity-scope-model.md) §5.4 World entity + `nexus-kb` crate). Therefore: @@ -111,7 +111,7 @@ Therefore: - **World-bound Work** (`world_id != NULL`): characters, locations, society, rules, events, timelines come from World KB. Chapter body may reference World KB items by id via `world_refs: [char_xxx, loc_yyy]` frontmatter; V1.40 validates per §3.5.1.4. - **Legacy worldless Work** (`world_id == NULL`, V1.39 and earlier only): no cross-Work continuity. Existing data remains readable/operable; V1.40 creation/init must not produce this state. - **`novel-project-init` asks the binding question** (grill-me). Two valid V1.40 options: bind to existing `world_id` (user picks from `nexus42 creator world list`) / create new World (calls `creator world create --title "..."`, narrative kind implicit). There is no V1.40 "stay worldless" creation option. -- **Work → World KB promotion** is the **long-term** path: as chapters finalize, `kb-extract` preset (existing, per [creator-workflow.md](../creator-workflow.md) `persist` stage) can extract entities / events / rules from chapter body into World KB items. V1.36 documents this path; enforcement is V1.37+. +- **Work → World KB promotion** is the **long-term** path: as chapters finalize, `kb-extract` preset (existing, per [creator-workflow.md](../creator/creator-workflow.md) `persist` stage) can extract entities / events / rules from chapter body into World KB items. V1.36 documents this path; enforcement is V1.37+. ### 3.5.1 World KB continuity implement contract (V1.37 P2 roadmap → V1.40 implement) @@ -126,7 +126,7 @@ nexus42 creator world create --title "Neon River" --description "Solarpunk noir → world_id: wld_ ``` -Note: `--kind narrative` is implicit (deferred to P1 taxonomy). `--title` is canonical; `--name` is an alias (see [cli-spec.md §6.2G](../cli-spec.md)). +Note: `--kind narrative` is implicit (deferred to P1 taxonomy). `--title` is canonical; `--name` is an alias (see [cli-spec.md §6.2G](../cli/cli-spec.md)). The init grill-me has exactly two valid V1.40 binding paths: @@ -345,7 +345,7 @@ Missing filesystem hints are still surfaced to the user (see §8.1), but a missi **V1.42 P1 (implement — grill-me locked):** 1. Backfill **implicit `volume = 1`** for all existing `work_chapters` rows (single-volume behavior unchanged). -2. Migrate PK to **`(work_id, volume, chapter)`** (see [local-db-schema.md](../local-db-schema.md) V1.42 amendment). +2. Migrate PK to **`(work_id, volume, chapter)`** (see [local-db-schema.md](../runtime/local-db-schema.md) V1.42 amendment). 3. Preserve row data (`status`, `outline_path`, `body_path`, `actual_word_count`, timestamps) through an idempotent migration. 4. New multi-volume Works declare volume count at init; chapter numbers may repeat across volumes. @@ -653,7 +653,7 @@ Works/ All template files live under `crates/nexus-orchestration/embedded-presets/novel-project-init/templates/` (P1 deliverable). The init preset's scaffold capability: 1. Reads each template from the embedded asset. -2. Substitutes preset input vars (`work_ref`, `title`, `world_id`, etc.) using `handlebars-rust` (per [orchestration-engine.md](../orchestration-engine.md) §7.3). +2. Substitutes preset input vars (`work_ref`, `title`, `world_id`, etc.) using `handlebars-rust` (per [orchestration-engine.md](../orchestration/orchestration-engine.md) §7.3). 3. Writes to `Works//...` at the path listed above. For V1.40 Works, `README.md` is rendered with a one-line `world_id: ` header and links to the World KB items the Work will reference most. Legacy worldless Works from V1.39 and earlier may retain README inline world setting notes, but V1.40 scaffold rendering does not create new worldless README variants. @@ -794,7 +794,7 @@ Sync **must not** upload full正文 by default (cli-spec §5.3 unchanged). | `creator bootstrap --idea "..."` | Default `work_profile: novel` when `--preset novel-writing` or default produce path; V1.40 creation/init must obtain a `world_id` via create-new or bind-existing before scaffold completes | | `creator bootstrap --idea "..." --world-id ` | Bind the new Work to an existing World (per §3.5); World KB is injected as context in `novel-writing` prompts | | `creator bootstrap --idea "..." --init-preset novel-project-init` | Run the `novel-project-init` grill-me (scaffold dirs + mandatory World binding question + `work_chapters` seed rows) before intake | -| `creator works status []` | **V1.41** — migrated from `creator run status`; reads `work_chapters`; shows `work_ref`, chapter list, completion; **V1.39** fields + completion/runtime lock per [cli-spec.md](../cli-spec.md) §6.2H | +| `creator works status []` | **V1.41** — migrated from `creator run status`; reads `work_chapters`; shows `work_ref`, chapter list, completion; **V1.39** fields + completion/runtime lock per [cli-spec.md](../cli/cli-spec.md) §6.2H | | `creator works list` | **V1.41** — migrated from `creator run list` | | `creator run resume ` | **V1.39** — resume checkpointed auto-chain after daemon restart | | `creator run continue --note "..."` | Appends inspiration; does not advance chapter index | diff --git a/.mstar/specs/creator-schedule-and-core-context.md b/.mstar/specs/orchestration/creator-schedule-and-core-context.md similarity index 96% rename from .mstar/specs/creator-schedule-and-core-context.md rename to .mstar/specs/orchestration/creator-schedule-and-core-context.md index 2c25a8a02..3b6713de4 100644 --- a/.mstar/specs/creator-schedule-and-core-context.md +++ b/.mstar/specs/orchestration/creator-schedule-and-core-context.md @@ -8,7 +8,7 @@ - [orchestration-engine.md](orchestration-engine.md) — Task/Capability/Session primitives this spec builds on - program-level scope is historical (not clone SSOT) -- [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) — confirms Schedule / core_context types are **local** (not wire) +- [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md) — confirms Schedule / core_context types are **local** (not wire) **Answers for open questions originally parked in `orchestration-engine.md` §11**: OQ-1, OQ-2, OQ-3, OQ-4, OQ-5 are resolved here (see §2 "Confirmed Decisions"). OQ-6 is scoped for V1.4; OQ-7/OQ-8 remain V1.5+. @@ -57,9 +57,9 @@ From the 2026-04-17 brainstorming and its follow-up (item 3 of the 2026-04-17 PM - **`core_context` is immutable-versioned** — every derivation step produces a new `core_context_version` row; the Schedule holds a pointer to the current version; history is user-queryable. - **`iterated_experience` in V1.4 is "preset `context_update` hook only"** (Q1=D answer, 2026-04-17) — the derivation trace enum **reserves** `kind: "llm_summarize"` but V1.4 does not emit that kind; **V1.5 implemented** a `context.summarize` capability (`crates/nexus-orchestration/src/capability/builtins/context_summarize.rs`) that writes this kind without schema migration. - **Seed → first `core_context` semantics governed by preset** (Q2=C answer, 2026-04-17) — preset YAML declares the initial-action behaviour; V1.4 built-in presets default to "seed content becomes `core_context` v0 verbatim"; a future preset may declare a one-shot LLM expansion step and the engine will execute it. **Durable roadmap:** DR-17. -- **Trigger model**: V1.4 supported on-demand triggers (`schedule start`, auto-advance, `timer.wait_until`). **V1.5 WS-D added wall-clock / cron triggers** via a hand-rolled clock poller in `crates/nexus-orchestration/src/scheduler/` using `cron` + `chrono-tz` (see [`crate-selection-best-practices.md`](../knowledge/crate-selection-best-practices.md) §2.7 for the four hard constraints this implementation satisfies). -- **Schedule and core_context types are local** — per [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) §2, platform never observes these; they live as hand-coded Rust in `crates/nexus-contracts/src/local/schedule/` (or the appropriate local submodule). -- **Auto-chain side-input (V1.39)** — inspiration append (`creator run continue --note`, agent `nexus.work.patch`) and research KB writes during an active FL-E driver schedule produce new `core_context` versions or external KB artifacts but **must not** create a second active stage driver or cancel the current one. The running session completes the current state on the prior snapshot; enriched context is visible at the **next** state transition. See [creator-workflow.md](creator-workflow.md) §5.5. +- **Trigger model**: V1.4 supported on-demand triggers (`schedule start`, auto-advance, `timer.wait_until`). **V1.5 WS-D added wall-clock / cron triggers** via a hand-rolled clock poller in `crates/nexus-orchestration/src/scheduler/` using `cron` + `chrono-tz` (see [`crate-selection-best-practices.md`](../../knowledge/crate-selection-best-practices.md) §2.7 for the four hard constraints this implementation satisfies). +- **Schedule and core_context types are local** — per [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md) §2, platform never observes these; they live as hand-coded Rust in `crates/nexus-contracts/src/local/schedule/` (or the appropriate local submodule). +- **Auto-chain side-input (V1.39)** — inspiration append (`creator run continue --note`, agent `nexus.work.patch`) and research KB writes during an active FL-E driver schedule produce new `core_context` versions or external KB artifacts but **must not** create a second active stage driver or cancel the current one. The running session completes the current state on the prior snapshot; enriched context is visible at the **next** state transition. See [creator-workflow.md](../creator/creator-workflow.md) §5.5. ## 3. Data Model @@ -384,7 +384,7 @@ Returns a human-readable summary of the creator's Schedule timeline (past N days ## 9. HTTP Surface (`/v1/local/orchestration/schedules/*`) -Following the pattern established in [acp-client-tech-spec.md](acp-client-tech-spec.md) §4.3 (orchestration control endpoints), the new endpoints: +Following the pattern established in [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) §4.3 (orchestration control endpoints), the new endpoints: | Method | Path | Purpose | | ------ | --------------------------------------------------------------------- | ----------------------------------------------------------- | @@ -397,7 +397,7 @@ Following the pattern established in [acp-client-tech-spec.md](acp-client-tech-s | GET | `/v1/local/orchestration/schedules/{schedule_id}/core-context-history`| Full derivation trace (meta by default, content with flag) | | DELETE | `/v1/local/orchestration/schedules/{schedule_id}` | Remove Schedule (if terminal) | -Per [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) §2, these request/response types are **local** (platform never observes them). Request/response Rust types live in `crates/nexus-contracts/src/local/schedule/http.rs` — hand-written, no JSON Schema file. +Per [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md) §2, these request/response types are **local** (platform never observes them). Request/response Rust types live in `crates/nexus-contracts/src/local/schedule/http.rs` — hand-written, no JSON Schema file. ## 10. SQLite Schema Additions @@ -563,8 +563,8 @@ Schedule and core_context Rust types in `crates/nexus-contracts/src/local/schedu Internal: - [orchestration-engine.md](orchestration-engine.md) — engine primitives; §11 OQ list now answered here -- [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) — confirms Schedule types are local -- [acp-client-tech-spec.md](acp-client-tech-spec.md) §4.3 — orchestration HTTP surface pattern +- [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md) — confirms Schedule types are local +- [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) §4.3 — orchestration HTTP surface pattern - `daemon-lifecycle-api.md` — supervisor start/stop coupled to `Running`/`Stopping` External: diff --git a/.mstar/specs/llm-extract.md b/.mstar/specs/orchestration/llm-extract.md similarity index 83% rename from .mstar/specs/llm-extract.md rename to .mstar/specs/orchestration/llm-extract.md index fb4df7149..d806b070c 100644 --- a/.mstar/specs/llm-extract.md +++ b/.mstar/specs/orchestration/llm-extract.md @@ -7,8 +7,8 @@ | **Status** | Normative — V1.51 Shipped (T-A P0). The `nexus.llm.extract` capability, `LlmExtractTask`, and the `kb_extract_jobs` payload extension landed together; review-time extraction in `novel-review-master` swapped from the V1.50 heuristic to this LLM pathway (closes `R-V150KBED-01`). | | **Document class** | Master | | **Scope** | `nexus.llm.extract` capability contract; `LlmExtractTask` lifecycle; `kb_extract_jobs.proposed_payload` LLM extension; Host-mediated prompt execution; integration with `novel-review-master` review-time extraction | -| **Last updated** | 2026-09-08 — V1.186 Host prompt cutover; status confirmed Normative | -| **Related** | [orchestration-engine.md](./orchestration-engine.md) §4.4.1 (`LlmJudgeTask` sibling), [entity-scope-model.md](./entity-scope-model.md) §5.5 (World KB promotion), [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md) §5.5, [cli-spec.md](./cli-spec.md) §6.2G, [local-db-schema.md](./local-db-schema.md) §4.1.2 | +| **Last updated** | 2026-09-29 — task/review-path boundary clarified; production preset `llm_extract` routing remains unshipped | +| **Related** | [orchestration-engine.md](orchestration-engine.md) §4.4.1 (`LlmJudgeTask` sibling), [entity-scope-model.md](../architecture/entity-scope-model.md) §5.5 (World KB promotion), [world-kb-runtime-architecture.md](../architecture/world-kb-runtime-architecture.md) §5.5, [cli-spec.md](../cli/cli-spec.md) §6.2G, [local-db-schema.md](../runtime/local-db-schema.md) §4.1.2 | This Master is normative for the `nexus.llm.extract` capability surface. It is a sibling to `judge.llm`: both call the injected `PromptExecutor`, whose daemon @@ -131,21 +131,38 @@ review-time hook is non-blocking. ```text 1. Render `template` content against the orchestration context (handlebars). -2. Build capability input: { prompt: , chapter_prose, _creator_id, _session_id }. -3. Resolve `nexus.llm.extract` (or configured capability name) via CapabilityRegistry. -4. Invoke capability; parse output.candidates into Vec. -5. Typed prompt unavailability → return an empty `Vec` so the caller may choose its documented heuristic fallback. +2. Read chapter prose, trusted identity/target/source, and work profile from context. +3. Invoke the shared `quality_loop::run_llm_extract` pathway, resolving `nexus.llm.extract` (or the configured capability name) via CapabilityRegistry. +4. Return LlmExtractOutcome::Candidates { candidates, relationships } on success. +5. Return WorkerUnavailable or Refused(reason) distinctly; the review-time caller alone decides fallback or zero writes. ``` -`LlmExtractTask` is the unit the orchestrator routes a `kind: llm_extract` exit -condition / enter action to (acceptance criterion §4.1). It does NOT persist -candidates itself — persistence is the caller's responsibility (the review-time -hook), keeping the task pure and hermetically testable. +**Shipped scope:** hermetic `llm_extract_task_*` tests exercise `LlmExtractTask`; +the production review-time extraction hook in +`crates/nexus-orchestration/src/quality_loop.rs` exercises the same shared +`run_llm_extract` pathway via `extract_via_llm`, not a preset-kind dispatcher. +The hook supplies its review prompt; the task supplies a rendered template. +Both reuse the same capability invocation and candidate parsing. The task does +NOT persist candidates itself — the review-time caller owns `kb_extract_jobs` +and relationship persistence (§3, §5). -**Public surface:** +**Unshipped/deferred:** routing a preset `kind: llm_extract` exit condition or +enter action to this task is NOT implemented. The explicit +`crates/nexus-orchestration/src/tasks/mod.rs` note (`R-V152TA-S003`) says there +is no production preset routing and applies +`#[cfg_attr(not(test), allow(dead_code))]`; §7 must not be read as proof that +this routing shipped. + +**Task API (not a preset grammar):** - `LlmExtractTask::new(template, capability_name, registry) -> Self` -- `LlmExtractTask::evaluate(&self, context) -> Result, GraphError>` +- `pub(crate) async LlmExtractTask::evaluate(&self, context) -> Result` + +`template` is stored at construction and rendered against `context` during +`evaluate`; there is no separate `evaluate(template, context)` overload. +`LlmExtractOutcome` distinguishes `Candidates { candidates, relationships }`, +`WorkerUnavailable`, and `Refused(reason)`, rather than returning a bare +`Vec` or treating an empty successful result as unavailability. `KbCandidate` is defined in `nexus-orchestration::quality_loop` and is shared between the heuristic fallback and the LLM pathway so callers treat both @@ -291,7 +308,7 @@ excluding `needs_review` rows; `?include_suggested=true` surfaces them. | Acceptance criterion (plan §4) | Where satisfied | | --- | --- | -| §4.1 `nexus.llm.extract` registered; `kind: llm_extract` routes to `LlmExtractTask` | §1, `capability/mod.rs`, `tasks/mod.rs` | +| §4.1 `nexus.llm.extract` registered; proposed `kind: llm_extract` routing | Registration shipped (§1, `capability/mod.rs`); production preset routing is **unshipped/deferred** (`tasks/mod.rs` `R-V152TA-S003`, §2) | | §4.2 `LlmExtractTask` hermetic tests (golden → golden, mock `PromptExecutor`) | `tasks/mod.rs` `llm_extract_task_*` tests | | §4.3 `novel-review-master` uses llm_extract; E2E asserts payload carries 4 LLM keys | §5, `tests/novel_review_master.rs` | | §4.4 adopt shows confidence + source_quote | cli-spec §6.2G, `creator_world_kb_adopt.rs` | diff --git a/.mstar/specs/orchestration-engine.md b/.mstar/specs/orchestration/orchestration-engine.md similarity index 93% rename from .mstar/specs/orchestration-engine.md rename to .mstar/specs/orchestration/orchestration-engine.md index 7766a9006..645b2a0c9 100644 --- a/.mstar/specs/orchestration-engine.md +++ b/.mstar/specs/orchestration/orchestration-engine.md @@ -2,15 +2,16 @@ **Status**: Shipped (V1.4–V1.188 — orchestration engine SSOT, preset loader, Host-mediated prompts, capability registry, recoverable workspace execution and settle-once cancellation). **V1.62**: §5.2 `narrative.compute` + §8.4 `combat-engine`. **V1.179 P2**: DR-06 bounded joins. **V1.186–V1.188**: §15 durable execution completeness and reliability. **Document class**: Master -**Pillar (V1.122)**: **Harness** — this spec is the control-strategy engine contract for the [Harness](../../STRATEGY.md) pillar (orchestration engine + agent host + capability registry + presets). Harness is the "how an author harnesses AI agents to execute creative work" pillar; the user-visible Strategy/Strategies → **Harness** product rename shipped V1.156 P3; internal identifiers remain `strategy`/`preset` (architect LOCKED). +**Pillar (V1.122)**: **Harness** — this spec is the control-strategy engine contract for the [Harness](../../../STRATEGY.md) pillar (orchestration engine + agent host + capability registry + presets). Harness is the "how an author harnesses AI agents to execute creative work" pillar; the user-visible Strategy/Strategies → **Harness** product rename shipped V1.156 P3; internal identifiers remain `strategy`/`preset` (architect LOCKED). **Author**: @project-manager (brainstorm consolidation) / to be co-authored by @architect before first implement -**Date**: 2026-04-17; **Last updated**: 2026-09-12 — V1.188 workspace and cancellation/replay contracts -**Scope**: daemon runtime, `crates/nexus-acp-host`, `crates/nexus-orchestration`, `nexus42` CLI, and preset bundle format. +**Date**: 2026-04-17; **Last updated**: 2026-09-29 — scope clarified after v1.193 P2 daemon retirement; V1.188 workspace and cancellation/replay contracts retained +**Scope**: Retained orchestration/preset contracts in `crates/nexus-orchestration` and `crates/nexus-preset`, their `crates/nexus-acp-host` boundary, and preset bundle format under the ordinary direct-core `cli` cohort. +**Historical host scope (v1.193 P2 supersession)**: The original “daemon runtime … `nexus42` CLI” scope and daemon-owned execution/lifecycle/schedule wording below describe the retired integrated host. They do not restore the daemon group or a CLI preset runner. The libraries remain; current CLI entry authority is [cli-spec.md](../cli/cli-spec.md) §6.0B + its delivered v1.193 P2 overlay (`apps/nexus42/src/cli.rs`; retained crate/cohort edges in `apps/nexus42/Cargo.toml`). **Supersedes**: — (new topic) **Coordinates with**: -- [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md) — crate owners for sync/memory capabilities (§5.2 target names; legacy `nexus-sync` / `nexus-domain` until V1.21) -- [acp-client-tech-spec.md](acp-client-tech-spec.md) — ACP transport/provider contract and `nexus-acp-host` crate spec +- [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) — crate owners for sync/memory capabilities (§5.2 target names; legacy `nexus-sync` / `nexus-domain` until V1.21) +- [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) — ACP transport/provider contract and `nexus-acp-host` crate spec - TD-9 closed: full 6-state HSM lifecycle (status moves from "gap" to "closed") **Non-goals** (explicit): @@ -37,7 +38,7 @@ 8. [Preset Loader (YAML → graph-flow Graph)](#8-preset-loader-yaml--graph-flow-graph) 9. [System Schedule vs Creator Schedule](#9-system-schedule-vs-creator-schedule) 10. [Migration Phases and Task Breakdown](#10-migration-phases-and-task-breakdown) -11. [Open Questions (deferred to B-track)](#11-open-questions-deferred-to-b-track) +11. [Open Questions (deferred to B-track)](#11-open-questions--reconciliation-status-was-deferred-to-b-track) 12. [Coordinated Work Tracks and Knowledge Doc Revisions](#12-coordinated-work-tracks-and-knowledge-doc-revisions) 13. [Risks and Mitigations](#13-risks-and-mitigations) 14. [References](#14-references) @@ -69,7 +70,7 @@ Users need to express creator workflows as configurable, prompt-driven strategie 3. daemon runtime owns orchestration, lifecycle HSM, and the existing `HostFacade` integration. 4. `nexus42` retains interactive `acp run` and schedule commands; the obsolete secondary ACP subcommand is removed. 5. First built-in preset: `_system.maintenance` (mandatory) and one user-facing sample `novel-writing`. -6. Knowledge docs revised: [acp-client-tech-spec.md](acp-client-tech-spec.md). +6. Knowledge docs revised: [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md). ### 1.4 Effort (agent-oriented) @@ -87,6 +88,8 @@ Per [effort-estimation.md](https://github.com/btspoony/mstar-harness/blob/main/d ## 2. Scope and Responsibility Split +The runtime/preset contracts remain authoritative for the retained crates above. References to the daemon runtime, its lifecycle HSM, and daemon-era `nexus42` schedule/execution entries are historical composition context, not the current CLI execution surface. + ### 2.1 In scope (this document is authoritative for) - Runtime architecture of the orchestration engine and capability registry. @@ -95,7 +98,7 @@ Per [effort-estimation.md](https://github.com/btspoony/mstar-harness/blob/main/d - Preset bundle filesystem layout, YAML manifest schema, prompt reference semantics, loader mapping rules. - Adapter layer over `graph-flow`: trait boundary, SQLite `SessionStorage` impl contract, `Task` impls for the standard node kinds. - Built-in capabilities catalog (first release). -- How the orchestration engine consumes and is consumed by `statig` daemon lifecycle. +- Historical host integration: how the orchestration engine consumed and was consumed by the `statig` daemon lifecycle (retired host, not a current CLI requirement). - Migration phases and their ordering constraints. ### 2.2 Out of scope @@ -107,11 +110,11 @@ Per [effort-estimation.md](https://github.com/btspoony/mstar-harness/blob/main/d | Seed-prompt → stable core-context derivation & versioning | B-track | | Preset distribution / registry / signing | Future (V1.5+) | | Wire schemas vs local types boundary refactor | §4 WS5 | -| ACP SDK migration (e.g. to `sacp` v1.0) | Governed by [acp-client-tech-spec.md](acp-client-tech-spec.md) §1.2 adapter-layer policy | +| ACP SDK migration (e.g. to `sacp` v1.0) | Governed by [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) §1.2 adapter-layer policy | ### 2.3 Non-goals (explicit) -- **Not an ACP protocol server promotion**: daemon runtime coordinates the existing Host provider plane; it does not expose ACP as a new public server protocol. See [acp-client-tech-spec.md](acp-client-tech-spec.md) §2.3. +- **Not an ACP protocol server promotion**: daemon runtime coordinates the existing Host provider plane; it does not expose ACP as a new public server protocol. See [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) §2.3. - **Not a LangChain-style in-memory pipeline**: all engine execution is **durable** and **resumable across daemon restart**; in-memory-only pipelines are explicitly rejected. - **Not a replacement for interactive `nexus42 agent run`**: that path stays direct stdio CLI-to-agent; orchestration does not route through it. @@ -150,7 +153,7 @@ Per [effort-estimation.md](https://github.com/btspoony/mstar-harness/blob/main/d | `crates/nexus-orchestration` | New | No | graph-flow adapter, capability trait, preset loader, SQLite `SessionStorage` | | `crates/nexus-daemon-runtime` | Ext. | No | Orchestration engine host, lifecycle HSM, `HostFacade` prompt executor, HTTP trigger/query | | `apps/nexus42` | Ext. | Yes (via host) | Interactive `acp run` and schedule command groups | -| `crates/nexus-contracts`, `nexus-creator`, `nexus-cloud-domain`, … | Ext. | No | Application crates per [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md); legacy monolith `nexus-domain` retired after V1.21 | +| `crates/nexus-contracts`, `nexus-creator`, `nexus-cloud-domain`, … | Ext. | No | Application crates per [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md); legacy monolith `nexus-domain` retired after V1.21 | ### 3.3 Data flow for one strategy tick @@ -175,7 +178,7 @@ Per [effort-estimation.md](https://github.com/btspoony/mstar-harness/blob/main/d ## 4. Orchestration Engine (graph-flow integration) -> **Crate selection cross-reference**: `graph-flow = "=0.8.0"` pinning (default-features disabled — no `postgres`, no `rig`), `sqlx` adoption for the shared pool, and the general dependency conventions are now governed by [`crate-selection-best-practices.md`](../knowledge/crate-selection-best-practices.md) (see §1 conventions + §2.1/§2.2/§2.3 decisions). This section remains the design SSOT for *how* those crates are integrated; it defers crate-identity and versioning policy to the best-practices document. +> **Crate selection cross-reference**: `graph-flow = "=0.8.0"` pinning (default-features disabled — no `postgres`, no `rig`), `sqlx` adoption for the shared pool, and the general dependency conventions are now governed by [`crate-selection-best-practices.md`](../../knowledge/crate-selection-best-practices.md) (see §1 conventions + §2.1/§2.2/§2.3 decisions). This section remains the design SSOT for *how* those crates are integrated; it defers crate-identity and versioning policy to the best-practices document. ### 4.1 Library adoption decision @@ -221,7 +224,7 @@ impl graph_flow::SessionStorage for SqliteSessionStorage { } ``` -**Pool ownership (post-WS8)**: `nexus-local-db` exposes `Arc` as the single workspace pool for `state.db` after V1.4 **WS8** unifies the DB engine on `sqlx` (; decision SSOT: [`crate-selection-best-practices.md`](../knowledge/crate-selection-best-practices.md) §2.3 + §3.3). `SqliteSessionStorage` takes that `Arc` at construction time; no separate connection or separate `.db` file. The `orchestration_sessions` table lands as one more `.sql` migration file under `crates/nexus-local-db/migrations/`, authored in WS2 Task 3 **after** WS8 T1–T2. +**Pool ownership (post-WS8)**: `nexus-local-db` exposes `Arc` as the single workspace pool for `state.db` after V1.4 **WS8** unifies the DB engine on `sqlx` (; decision SSOT: [`crate-selection-best-practices.md`](../../knowledge/crate-selection-best-practices.md) §2.3 + §3.3). `SqliteSessionStorage` takes that `Arc` at construction time; no separate connection or separate `.db` file. The `orchestration_sessions` table lands as one more `.sql` migration file under `crates/nexus-local-db/migrations/`, authored in WS2 Task 3 **after** WS8 T1–T2. Schema (new table in the unified `state.db` owned by `nexus-local-db`; schema migration file added under `crates/nexus-local-db/migrations/`): @@ -293,7 +296,7 @@ All impls live in `crates/nexus-orchestration/src/tasks/`. Task implementations ## 5. Capability Registry -> **Crate selection cross-reference**: Capability implementations MAY depend on third-party crates (e.g. `notify` for file-watch capabilities, `jsonwebtoken` for auth-related capabilities). Any new crate introduced here follows [`crate-selection-best-practices.md`](../knowledge/crate-selection-best-practices.md) §1 (conventions) — in particular §1.5 (PM introduction gate) and §1.3 (feature flag whitelist). +> **Crate selection cross-reference**: Capability implementations MAY depend on third-party crates (e.g. `notify` for file-watch capabilities, `jsonwebtoken` for auth-related capabilities). Any new crate introduced here follows [`crate-selection-best-practices.md`](../../knowledge/crate-selection-best-practices.md) §1 (conventions) — in particular §1.5 (PM introduction gate) and §1.3 (feature flag whitelist). ### 5.1 `Capability` trait @@ -344,9 +347,9 @@ All capabilities below are registered at daemon runtime startup. Adding a new ca ### 5.3 Capability input/output schemas -Each capability ships its `input_schema` and `output_schema` as constants (JSON Schema draft 2020-12) in Rust. **These schemas are local** (per [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md)) and live under `crates/nexus-contracts/src/local/orchestration/` (or adjacent module), **not** under `schemas/` — they are not wire contracts. +Each capability ships its `input_schema` and `output_schema` as constants (JSON Schema draft 2020-12) in Rust. **These schemas are local** (per [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md)) and live under `crates/nexus-contracts/src/local/orchestration/` (or adjacent module), **not** under `schemas/` — they are not wire contracts. -> **Daemon builds:** `sync.*` MUST NOT call `nexus-cloud-sync` on the daemon hot path; see [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md) §7. `outbox.flush` / `outbox.compact` (V1.59) are local-only pool-backed capabilities that operate directly on `outbox_entries` via `nexus-local-db` — they do not depend on `nexus-cloud-sync`. +> **Daemon builds:** `sync.*` MUST NOT call `nexus-cloud-sync` on the daemon hot path; see [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) §7. `outbox.flush` / `outbox.compact` (V1.59) are local-only pool-backed capabilities that operate directly on `outbox_entries` via `nexus-local-db` — they do not depend on `nexus-cloud-sync`. ### 5.4 Capability errors @@ -380,7 +383,7 @@ The dual-outbox architecture identified in TD-8 (`dual-outbox-architecture.md`) **Flush/compact invocation path**: - `outbox.flush` (`OutboxFlush`, pool-backed): drains pending (`staged`/`ready`) entries by marking them `acked`. Input: optional `limit`. Output: `{ flushed: N }`. - `outbox.compact` (`OutboxCompact`, pool-backed): deletes `acked` entries older than a configurable retention window (default 7 days). Input: optional `retentionDays`. Output: `{ removed: N, retained: M }`. -- Both capabilities are local-only (platform paused). Full semantics and test vectors are defined in the Master spec [outbox-consolidation.md](outbox-consolidation.md) (Normative). +- Both capabilities are local-only (platform paused). Full semantics and test vectors are defined in the Master spec [outbox-consolidation.md](../runtime/outbox-consolidation.md) (Normative). **Pool injection**: both capabilities receive `sqlx::SqlitePool` through `with_pool()` constructors, following the same pattern as `kb.extract_work`, `novel.project_scaffold`, and other pool-backed capabilities. The `with_builtins_and_pool()` and `with_runtime_deps()` registry factories inject the pool. @@ -691,7 +694,7 @@ All shipped presets use **linear** `next` transitions unless noted; conditional ### 7.8 Preset `run_intents` (V1.33) -Presets declare **how** they may be started from [work-experience-model.md](work-experience-model.md) and `creator run`: +Presets declare **how** they may be started from [work-experience-model.md](../creator/work-experience-model.md) and `creator run`: ```yaml preset: @@ -711,7 +714,7 @@ Loader rules (V1.33): - `creator bootstrap` filters intake presets where `work_init ∈ run_intents`. - `creator run continue` filters presets where `work_continue ∈ run_intents`. -Normative classification table: [work-experience-model.md](work-experience-model.md) §5.2. +Normative classification table: [work-experience-model.md](../creator/work-experience-model.md) §5.2. ### 7.9 Preset `gates` (V1.36 — Implemented) @@ -779,16 +782,16 @@ preset: | Constraint | Scope | Enforced at | Authoritative spec | | --- | --- | --- | --- | -| `run_intents` (V1.33) | Coarse: which `creator run` subcommand surfaces the preset | CLI dispatch time | §7.8, [work-experience-model.md](work-experience-model.md) §5 | +| `run_intents` (V1.33) | Coarse: which `creator run` subcommand surfaces the preset | CLI dispatch time | §7.8, [work-experience-model.md](../creator/work-experience-model.md) §5 | | `requires_capabilities` (V1.4) | Capability availability at engine startup | Loader | §7.2 | | `gates` (V1.36) | Per-invocation preconditions (Work fields, filesystem, prior-preset) | Enqueue time | §7.9 | -| `stage` gates (V1.34) | FL-E linear stage ordering (`intake → research → produce → review → persist`) | `creator run ` (preset runner validates before enqueue) | [creator-workflow.md](creator-workflow.md) §3.3 | +| `stage` gates (V1.34) | FL-E linear stage ordering (`intake → research → produce → review → persist`) | `creator run ` (preset runner validates before enqueue) | [creator-workflow.md](../creator/creator-workflow.md) §3.3 | Gates are **additive** to `run_intents` and `stage` gates; they do not replace either. A preset can declare any combination. Profile-specific gate sets (e.g. novel profile's `Works//` requirement) live in the profile overlay spec, not in this Master. #### 7.9.4 Worked example: novel-writing -Full gate set for `novel-writing` is documented in [novel-writing/workflow-profile.md §5.3](./novel-writing/workflow-profile.md). The Master here defines the mechanism; the Draft overlay defines the values. +Full gate set for `novel-writing` is documented in [novel-writing/workflow-profile.md §5.3](../novel-writing/workflow-profile.md). The Master here defines the mechanism; the Draft overlay defines the values. --- @@ -906,8 +909,8 @@ at daemon boot. `CapabilityError` and a `TimelineEvent` with `event_type: "compute_error"` is appended to the timeline. The daemon does not crash on compute failure. -**Related:** [compute-module-abi.md](./compute-module-abi.md) (module ABI contract), -[wasm-host.md](./wasm-host.md) (host runtime), [entity-scope-model.md](./entity-scope-model.md) +**Related:** [compute-module-abi.md](../compute/compute-module-abi.md) (module ABI contract), +[wasm-host.md](../compute/wasm-host.md) (host runtime), [entity-scope-model.md](../architecture/entity-scope-model.md) §5.5.9 (computable-flag semantics). #### 8.4.2 `combat-engine` preset @@ -946,8 +949,8 @@ included in the preset sync test suite. The preset is **not** embedded in the binary in V1.62 — it is a filesystem-loaded preset under `crates/nexus-orchestration/embedded-presets/combat-engine/`. -**Related:** [compute-module-abi.md](./compute-module-abi.md) §7.4 (basic-combat -manifest example), [wasm-host.md](./wasm-host.md) (sandbox limits applied during +**Related:** [compute-module-abi.md](../compute/compute-module-abi.md) §7.4 (basic-combat +manifest example), [wasm-host.md](../compute/wasm-host.md) (sandbox limits applied during `compute`). --- @@ -1072,7 +1075,7 @@ Compass WS5 (`schemas/` boundary refactor) is fully parallel and has no dependen ### 10.5 Phase 4 — statig daemon lifecycle (S+; 1 agent session; parallel with Phase 2) -Owned by the daemon lifecycle state machine (6-state; see [daemon-runtime.md](daemon-runtime.md) §10); A-track just consumes it. Entry/exit actions, event catalogue, and the HTTP surface migration live with the lifecycle owner (status field exposes real 6-state values). +Owned by the daemon lifecycle state machine (6-state; see [daemon-runtime.md](../archived/daemon-runtime.md) §10); A-track just consumes it. Entry/exit actions, event catalogue, and the HTTP surface migration live with the lifecycle owner (status field exposes real 6-state values). **Integration point with engine**: HSM `Running.entry` calls `engine.start()`; `Stopping.entry` cancels active runs through the shared token/Host finalization path before `engine.shutdown(grace_ms)`. `Degraded` reflects sustained failures of retained subsystems such as sync, ACP registry, and the Agent Host. @@ -1080,7 +1083,7 @@ Owned by the daemon lifecycle state machine (6-state; see [daemon-runtime.md](da In the same change window as each phase: -- Phase 1 → commit [acp-client-tech-spec.md](acp-client-tech-spec.md) §11 (crate layout). +- Phase 1 → commit [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) §11 (crate layout). - Phase 2 → commit §4.3 (Daemon API additions) in the same spec. - Phase 4 → commit the lifecycle doc updates. - Phase 3 → this document updated: move sections to "Delivered" once implemented. @@ -1120,7 +1123,7 @@ If you landed on this section looking for the `schemas/` refactor scope, open th | v1 (preserved, now carries superseded-by pointer) | v2 (new; authoritative) | | ------------------------------------------------- | --------------------------------------------------------------- | -| `acp-client-tech-spec-legacy.md` (archived) | [acp-client-tech-spec.md](acp-client-tech-spec.md) | +| `acp-client-tech-spec-legacy.md` (archived) | [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) | **Retired 2026-04-17** (historical): the v1 lifecycle/ACP companion specs were retired. This orchestration-engine spec remains **active** (structure paths in §3–§8 may lag implementation; semantics remain authoritative). @@ -1147,7 +1150,7 @@ If you landed on this section looking for the `schemas/` refactor scope, open th Internal: -- [acp-client-tech-spec.md](acp-client-tech-spec.md) — companion ACP transport, provider, and Host ownership specification +- [acp-client-tech-spec.md](../agents/acp-client-tech-spec.md) — companion ACP transport, provider, and Host ownership specification - `local-db-refactor.md` — `nexus-local-db` ownership rules for the new `orchestration_sessions` table. See `local-db-refactor.md §4` for pool sharing model. - `acp-client-tech-spec-legacy.md` — archived; do not rely on directly (see Superseded header) @@ -1161,13 +1164,13 @@ External (stable, public): --- -*End of specification. The companion documents ([acp-client-tech-spec.md](acp-client-tech-spec.md), [creator-schedule-and-core-context.md](creator-schedule-and-core-context.md), [daemon-runtime.md](daemon-runtime.md)) fill in details that would otherwise clutter this document; read them together when extending orchestration.* +*End of specification. The companion documents ([acp-client-tech-spec.md](../agents/acp-client-tech-spec.md), [creator-schedule-and-core-context.md](creator-schedule-and-core-context.md), [daemon-runtime.md](../archived/daemon-runtime.md)) fill in details that would otherwise clutter this document; read them together when extending orchestration.* --- ## V1.45 supersession (P-last promotion) -**Superseded by**: [creator-run-preset-entry.md](creator-run-preset-entry.md) (Shipped Master V1.45). The `run_intents` dispatch via generic `creator run ` and `--force-gates --reason` semantics are now part of the canonical Master body. +**Superseded by**: [creator-run-preset-entry.md](../archived/creator-run-preset-entry.md) (Shipped Master V1.45). The `run_intents` dispatch via generic `creator run ` and `--force-gates --reason` semantics are now part of the canonical Master body. @@ -1176,7 +1179,7 @@ External (stable, public): **Status:** Shipped V1.186, amended by verified V1.188 workspace and settlement behavior below. This is the durable Master execution contract; legacy records retain explicit conservative handling rather than fabricated historical success. 1. **Authoritative status.** Reuse `orchestration_sessions.status TEXT` for `running` | `paused` | `waiting_for_input` | `completed` | `failed` | `cancelled` | `interrupted`. Add versioned execution metadata, a revision fence and a frozen run descriptor with a new append-only migration. Transition checkpoint/context/status/metadata atomically; graph position saves MUST NOT overwrite terminal/wait status or a newer revision. Legacy rows without authoritative metadata remain explicitly legacy/unverified unless existing evidence supports conservative reconciliation; do not fabricate historical completion. Public inspect after daemon restart MUST agree, including terminals without a live runner. -2. **One Host plane.** Choose in-process graph/capability execution through an injected Host-independent `PromptExecutor`, implemented in the daemon over existing `HostFacade`. Migrate graph `acp_prompt` and all prompt-backed consumers: `acp.prompt`, `judge.llm`, `context.summarize`, `nexus.llm.extract`; retire every secondary prompt-success branch after callers migrate. Success requires normalized agent output and `HostEvent::OpFinished` with `FinishReason::EndTurn`; refusal, limits, stream EOF and partial output are not successful completion. Host session/process ownership and generic ACP configuration are defined in [agent-host.md](agent-host.md) §4. No second LLM runtime or native RPC adapter. +2. **One Host plane.** Choose in-process graph/capability execution through an injected Host-independent `PromptExecutor`, implemented in the daemon over existing `HostFacade`. Migrate graph `acp_prompt` and all prompt-backed consumers: `acp.prompt`, `judge.llm`, `context.summarize`, `nexus.llm.extract`; retire every secondary prompt-success branch after callers migrate. Success requires normalized agent output and `HostEvent::OpFinished` with `FinishReason::EndTurn`; refusal, limits, stream EOF and partial output are not successful completion. Host session/process ownership and generic ACP configuration are defined in [agent-host.md](../agents/agent-host.md) §4. No second LLM runtime or native RPC adapter. 3. **Public driver.** One daemon coordinator owns single-flight bounded driving for session POST, creator run and schedule admission; the graph-flow engine and existing step loop remain the execution backend. Schedule admission atomically associates a durable session before enqueue; seed/input/preset/provider bindings are frozen before eligibility. Explicit `execution_policy` distinguishes `legacy_inert`, `driven_v1`, and `system_inert`; dates or a Running label are not opt-in. Historical never-started rows MUST NOT execute on boot/tick/cron; only an explicit authorized public start opts that row in. Schedule terminal settlement and existing auto-chain insertion are idempotent by the owned terminal run. 4. **Human wait.** A fresh UUID `wait_id` identifies each manual-wait arrival and persists through restart with the root/child task cursor. Authorized matching continuation consumes it by revision CAS; missing token is `422 invalid_input`, stale/consumed token `409 workflow_wait_conflict`, incompatible state `409 workflow_state_conflict` in the existing error envelope. Other advance/resume/force-transition routes MUST NOT bypass the same human gate. Supported child waits inherit trusted creator/root-preset/parent/graph identity and durable checkpoints; parent-only status without a reconstructible child cursor is insufficient. Never auto-resume WaitingForInput children; multiple waits are exposed one at a time without approving siblings. 5. **Cancel.** Persist a cancel fence before new steps, request out-of-band provider cancellation where supported, then wait boundedly for owned session cleanup. Persist cancelled only when owned work has stopped; unconfirmed cleanup is interrupted with an actionable reason, never false successful cancellation. Terminal-v-cancel and continue-v-cancel races are revision-linearized. Cancel MUST NOT claim rollback of effects already committed outside Nexus. @@ -1185,9 +1188,9 @@ External (stable, public): ### 15.1 V1.188 workspace execution and settlement -- `workspace.open` and `workspace.commit` consume shared contract DTOs through an injected `WorkspaceExecutor`; the daemon binds the same durable authority as HTTP workspace routes. Missing binding fails explicitly. Target bytes, pre-image OCC, stable revision, retained intent recovery and external visibility limits are normative in [concurrency.md](concurrency.md) §9. +- `workspace.open` and `workspace.commit` consume shared contract DTOs through an injected `WorkspaceExecutor`; the daemon binds the same durable authority as HTTP workspace routes. Missing binding fails explicitly. Target bytes, pre-image OCC, stable revision, retained intent recovery and external visibility limits are normative in [concurrency.md](../runtime/concurrency.md) §9. - `settle_run` returns `Applied(durable record)` or `Observed(durable winner)` under the existing revision/graph/checkpoint fences. Observing another winner is not proof that this caller cleaned up its resources. Existing Completed/Failed/Cancelled outcomes remain unchanged; persisted `driver_failed` is not relabelled Cancelled. - Once cancel admission wins, step-in-flight and prompt Dispatching/Active fences reject later work. Failed-step cleanup retains its original revision/graph/attempt/process witness rather than rebasing onto a newer owner. Ordinary cancel uses its bounded eight-attempt retry. - Unconfirmed cleanup remains actionable Interrupted, even when a convenience `is_terminal` helper includes it. A retry can publish the later confirmed outcome. HTTP/CLI/inspect/events project the same durable winner; restart cannot resurrect cancelled work. - An admitted workspace intent completes or rolls back through its retained workspace owner. Cancellation prevents subsequent steps without aborting files midway; the coordinator does not create a second workspace recovery state machine. -- Run-bound Host events and durable run-state projections use bounded same-run SSE replay, not a second workflow clock or durable activity journal. Admission, authorization, gaps and retention are defined in [daemon-runtime.md](daemon-runtime.md) §20.2. +- Run-bound Host events and durable run-state projections use bounded same-run SSE replay, not a second workflow clock or durable activity journal. Admission, authorization, gaps and retention are defined in [daemon-runtime.md](../archived/daemon-runtime.md) §20.2. diff --git a/.mstar/specs/preset-conditional-routing.md b/.mstar/specs/orchestration/preset-conditional-routing.md similarity index 92% rename from .mstar/specs/preset-conditional-routing.md rename to .mstar/specs/orchestration/preset-conditional-routing.md index 773154e49..132ab95a3 100644 --- a/.mstar/specs/preset-conditional-routing.md +++ b/.mstar/specs/orchestration/preset-conditional-routing.md @@ -3,23 +3,23 @@ **Status**: Shipped (V1.42 P2 — 2026-06-12; `llm_judge` GO/NOGO → two `next` edges; V1.52 T-B P0 — 2026-06-19; N-way labeled routing; V1.52 T-B P1 — 2026-06-19; multi-branch merge semantics; V1.56 P2 — 2026-06-22; arbitrary stage conditional + expression routing + converge nodes; V1.56 P3 — 2026-06-22; registry.refresh conditional edges + workspace branch inputs; **V1.179 P2 — 2026-08-27; DR-06 bounded joins** — `timeout_ms` / `on_timeout` on `merge:`/`converge:` states (additive fields; normative §3.3.3)) **Document class**: Feature line (conditional routing — minimal slice → N-way labeled → merge semantics → full expression routing → data-source integration) **Created**: 2026-06-06 -**Last updated**: 2026-09-04 (V1.179 P2: DR-06 bounded joins shipped, §3.3.3) +**Last updated**: 2026-09-29 (authority clarified; V1.179 P2 DR-06 bounded joins remain shipped, §3.3.3) **Tracker**: DF-56 (conditional routing / branching engine) **Scope**: Preset `next.kind: conditional` loader + runtime evaluator (shipped) **Coordinates with**: -- [orchestration-engine.md](orchestration-engine.md) §7.5 — current linear-only contract; this doc is the future normative target when conditional routing ships -- [creator-workflow.md](creator-workflow.md) — linear creator workflow stages (shipped V1.34); conditional routing layers beneath, does not replace FL-E enum in the first ship slice +- [orchestration-engine.md](orchestration-engine.md) §7.5 — delegates conditional-routing semantics to this file as the shipped normative SSOT, including DR-06 bounded joins (V1.179 P2); it is not a linear-only contract awaiting a future shipment +- [creator-workflow.md](../creator/creator-workflow.md) — linear creator workflow stages (shipped V1.34); conditional routing layers beneath, does not replace FL-E enum in the first ship slice -This file is the long-term SSOT. +This file is the shipped normative SSOT for conditional routing. DR-06 bounded-join validation is implemented in `crates/nexus-preset/src/loader.rs`, runtime deadlines/rerouting in `crates/nexus-orchestration/src/tasks/mod.rs`, and deterministic coverage in `crates/nexus-orchestration/tests/join_timeout_e2e.rs`. Pre-shipment rationale and release snapshots below are explicitly historical, not pending implementation gates. --- ## 1. Purpose -Authors need presets that branch on runtime signals (judge outcome, tool result, user input) without spawning separate schedules or a manual `creator run ` dispatch. +Authors need presets that branch on runtime signals (judge outcome, tool result, user input) without spawning separate schedules or manual dispatch (historically `creator run `; that CLI runner was retired in v1.193 P2). -**V1.42 P2 shipped minimal slice** (2026-06-11): +**Historical V1.42 P2 minimal-slice snapshot** (2026-06-11; later shipped semantics are in §3): - `llm_judge` states with `next: { go: , nogo: }` now accepted by loader. - Graph wires a conditional edge using `_judge_result` from context. @@ -27,7 +27,7 @@ Authors need presets that branch on runtime signals (judge outcome, tool result, - Only valid on `exit_when: { kind: llm_judge }` states. Full expression-based conditional routing remains post-V1.42 (see §3.6.3). - -Pre-V1.42 state: +Historical pre-V1.42 state: - Preset loader rejected `next.kind: conditional` with `ConditionalNotYetSupported`. - Shipped creator workflow uses linear stage enum + explicit `creator run ` dispatch (DF-53 auto-chain still open). @@ -35,7 +35,9 @@ Pre-V1.42 state: --- -## 2. Current state (V1.42 P2 shipped) +## 2. Historical state (V1.42 P2 shipped snapshot) + +This table records the initial slice, not today's loader limits or CLI surface. Expression routing shipped in V1.56 (§3.3); `creator run` was retired in v1.193 P2. | Area | State | | --- | --- | @@ -47,9 +49,9 @@ Pre-V1.42 state: --- -## 3. Target semantics (future normative) +## 3. Shipped normative semantics -When Status advances to **Draft** or **Normative**, orchestration-engine §7.5 defers to this document for the full conditional `next` schema. +Orchestration-engine §7.5 delegates the full conditional `next` schema and merge/converge semantics to this section. N-way routing, expression routing, and DR-06 bounded joins are shipped; the release labels below identify their provenance, not future targets. ### 3.1 N-way labeled routing (V1.52 T-B P0 — Normative) @@ -358,7 +360,9 @@ The runtime scans compiled expression ASTs for `registry_refresh` and `workspace --- -## 4. Design axes (unlocked — future grill required) +## 4. Historical design axes (pre-shipment exploration) + +§4–§7 preserve the pre-shipment V1.35 exploration, dependencies, proposed sequencing, and non-goals. They do not override shipped §3 or define current CLI entries; `creator run` was retired in v1.193 P2. | Axis | Options | Recommendation (exploration) | | --- | --- | --- | @@ -370,7 +374,7 @@ The runtime scans compiled expression ASTs for `registry_refresh` and `workspace --- -## 5. Dependencies before implement +## 5. Historical dependencies before implementation 1. Close or cap V1.33 **critical** residuals (security/auth on memory, judge.llm correctness). 2. DF-47 production caller wiring (agent tool path stable). @@ -379,7 +383,7 @@ The runtime scans compiled expression ASTs for `registry_refresh` and `workspace --- -## 6. Suggested future iteration shape (non-binding) +## 6. Historical proposed iteration shape (non-binding) | Phase | Deliverable | | --- | --- | @@ -393,7 +397,7 @@ The runtime scans compiled expression ASTs for `registry_refresh` and `workspace --- -## 7. Explicit non-goals +## 7. Historical explicit non-goals (V1.35 exploration) | Scope | Rule | | --- | --- | @@ -413,7 +417,7 @@ The runtime scans compiled expression ASTs for `registry_refresh` and `workspace --- -## 9. Change control +## 9. Historical change control (promotion record) | Event | Action | | --- | --- | diff --git a/.mstar/specs/registry-integration.md b/.mstar/specs/registry-integration.md deleted file mode 100644 index f4cc89c3b..000000000 --- a/.mstar/specs/registry-integration.md +++ /dev/null @@ -1,185 +0,0 @@ -# Nexus ACP Registry Integration - -**Status**: Normative -**Document class**: Master - -## 0. Document position - -This document specifies how **Nexus CLI runtime (ACP Client)** integrates with **ACP Registry** for agent discovery, selection, caching, and transport choice. - -Related docs: nexus-platform `v1-spec/architecture.md` §6.4–6.5, [`cli-spec.md`](./cli-spec.md) §6.8、§11。 - -### 0.1 Upstream registry (canonical source) - -The **Agent Client Protocol registry** is maintained upstream as open data and tooling: agent listings, distribution metadata, and JSON schemas live in the community project **`agentclientprotocol/registry`**, with a published **HTTPS index** for clients to fetch. Nexus does not host that authority. - -- **Concrete URLs, GitHub repo, and schema links** (only allowed external HTTP index for `v1-spec`): the **ACP Registry** / **分发用索引** rows in §0.1 below. -- **Default remote canonical source**: implementations SHOULD use the upstream **registry index JSON** as the default for §3.1 item 1 unless a workspace override or enterprise mirror is configured. Entry shape and fields MUST follow upstream **`FORMAT.md`** and **`registry.schema.json` / `agent.schema.json`** as versioned by that repo; Nexus MAY pin a specific index version or ETag once the fetch contract is stable. - -Authentication expectations for listed agents (e.g. `authMethods` in handshake) are defined upstream; see that repo’s **`AUTHENTICATION.md`** via the same references index. - ---- - -## 1. Goals - -- Treat Registry as the ecosystem layer for compatible agents. -- Make agent resolution deterministic, auditable, and offline-tolerant where possible. -- Keep **stdio** as V1.0 default for local agents; position remote transports as optional/future. - ---- - -## 2. Roles and non-roles - -### 2.1 Nexus runtime responsibilities - -- Fetch or read Registry manifests and local mirrors. -- Validate agent entries against ACP protocol version, transport support, and Nexus capability requirements. -- Persist a local selection. -- Spawn/connect the selected ACP Agent as the ACP server side of the session from Nexus client perspective. -- Support capability probing for **Creator registration** and pairing flows when a local agent is being promoted into a platform-known Creator. - -### 2.2 Explicit non-responsibilities - -- Publishing Nexus daemon as an agent discoverable by third-party ACP clients. -- Acting as Registry hosting authority. - ---- - -## 3. Manifest sources and fetch rules - -### 3.1 Source priority - -1. Remote canonical Registry (HTTPS) -2. Workspace override -3. User cache -4. Local static mirror - -### 3.2 Fetch behavior - -- Use ETag / If-Modified-Since when available. -- Failures must not crash daemon; enter degraded mode. -- Verify manifest signatures/checksums when Registry provides them. - -### 3.3 Offline behavior - -- If remote fetch fails, runtime uses last good cached manifest if within TTL. -- If no cache exists, runtime requires local override or manual agent configuration. - ---- - -## 4. Cache policy - -### 4.1 What is cached - -- Registry manifest files -- Agent package metadata -- Small artifacts such as icons/descriptions - -### 4.2 TTL and freshness - -| Artifact | Default TTL | Notes | -| --- | --- | --- | -| Manifest index | 24h | refresh in background | -| Agent version list | 24h | pin overrides TTL | -| Downloaded agent package | explicit | only if Registry supports binary distribution | - -Runtime may serve stale cache immediately while async refresh proceeds. - -### 4.3 Cache invalidation triggers - -- User runs `nexus42 acp registry refresh` -- TTL expiry + next online event -- Workspace config changes -- Doctor detects checksum mismatch vs pinned agent - -### 4.4 Storage location - -- Under `$HOME/.nexus42/cache/registry/` (or a workspace-keyed subtree still under `$HOME/.nexus42/cache/`) - ---- - -## 5. Selection and filtering rules - -### 5.1 Hard filters - -- ACP protocol version outside supported window -- Transport unsupported for current OS / runtime mode -- Missing required Nexus capabilities for selected profile -- Platform policy flags - -### 5.2 Soft scoring - -Prefer, in order: - -1. User pinned agent -2. Workspace default -3. Highest compatible version within same major line -4. Local stdio agents over remote agents -5. Recent successful agent - -### 5.3 Explicit user binding - -- `nexus42 acp agent use` writes pin record under `$HOME/.nexus42/` or workspace-linked config (not ad-hoc under `/` without user intent) -- `nexus42 acp registry inspect` shows why an agent passed/failed filters - -### 5.4 Fallback path - -If Registry resolution fails: - -- Allow manual agent command in config -- Doctor prints actionable fix steps - ---- - -## 6. Transports: stdio vs remote - -### 6.1 V1.0 default: JSON-RPC over stdio - -- Nexus client spawns agent subprocess and speaks JSON-RPC over stdin/stdout. -- Process supervision and restart/backoff are owned by daemon. -- Logs should go to stderr with a structured policy, not stdout framing. - -### 6.2 Future-compatible: HTTP / WebSocket - -- Supported only when explicitly enabled by user policy. -- Require TLS and policy gating. - -### 6.3 Transport selection algorithm - -1. If pinned agent specifies transport, honor it if allowed. -2. Else prefer `stdio` local launch when manifest provides launch spec. -3. Else use remote endpoint if permitted. -4. Else fail with explicit configuration error. - ---- - -## 7. CLI commands - -Minimum recommended: - -- `nexus42 acp registry list` -- `nexus42 acp registry inspect ` -- `nexus42 acp registry refresh` -- `nexus42 acp agent use ` -- `nexus42 acp probe` - -`nexus42 acp probe` should be reusable by creator registration flows to capture declared capabilities and transport metadata before the platform issues creator credentials. - ---- - -## 8. Security considerations - -- **Supply chain**: prefer signed manifests when available. -- **Typosquatting**: show publisher identity prominently. -- **Remote agents**: higher risk; default-off or strict allowlist in v1. -- **Privacy**: Registry fetch leaks coarse usage timing; provide optional offline mode. - ---- - -## 9. Open items - -> **Durable roadmap:** the open items below (pin upstream schema compat, enterprise mirror, binary distribution) are DR-55. - -- Pin field-level compatibility to upstream **`registry.schema.json` / `agent.schema.json`** revisions as they ship in the **`agentclientprotocol/registry`** project (repo URL and default index in §0.1 below). -- Enterprise mirror documentation and trust roots. -- Binary agent distribution vs path-only local agents. diff --git a/.mstar/specs/chapter-content-local-api.md b/.mstar/specs/runtime/chapter-content-local-api.md similarity index 90% rename from .mstar/specs/chapter-content-local-api.md rename to .mstar/specs/runtime/chapter-content-local-api.md index d8097ea34..b55912538 100644 --- a/.mstar/specs/chapter-content-local-api.md +++ b/.mstar/specs/runtime/chapter-content-local-api.md @@ -5,8 +5,8 @@ | **Status** | Shipped — V1.65 chapter surface; V1.75 retired whole-document outline PUT in favor of the canvas patch route | | **Document class** | Feature line | | **Scope** | Chapter list/detail, outline read, structure PATCH, and body read-only Daemon API contracts under `/v1/daemon/works/{work_id}/chapters/*` | -| **Coordinates with** | [daemon-api-surface-conventions.md](./daemon-api-surface-conventions.md), [daemon-runtime.md](./daemon-runtime.md), [schemas-directory-layout.md](./schemas-directory-layout.md), [web-ui.md](./web-ui.md), repo-root [`DESIGN.md`](../../DESIGN.md) | -| **Implementation owner** | `nexus-daemon-runtime` chapter/canvas handlers; Web UI consumes only through `NexusClient` | +| **Coordinates with** | [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md), [daemon-runtime.md](../archived/daemon-runtime.md), [schemas-directory-layout.md](../architecture/schemas-directory-layout.md), [web-ui.md](../surfaces/web-ui.md), repo-root [`DESIGN.md`](../../../DESIGN.md) | +| **Implementation owner** | `crates/nexus-core/src/content.rs` (chapter content/metadata service) + `crates/nexus-core/src/outline.rs` (outline/structure operations), exposed through `crates/nexus-core-node/src/domain.rs`; metadata persistence: `crates/nexus-local-db/src/work_chapters.rs`. Web UI consumes only through `NexusClient`. | --- @@ -21,7 +21,7 @@ does not override the shipped source or schema tree. The surface is intentionally split: - **Structure and outline are writable** in V1.65. -- **Body markdown is read-only** — the AI owns prose writing via orchestration through the host-tool path; there is **no manual body editor** (the body-editor direction was rejected 2026-06-26 — Nexus is an AI-autonomous executor; see [canvas-strategy-surface.md](canvas-strategy-surface.md)). Any future human body interaction is a V1.68 canvas concern (structured/node-granular, no-raw-file-editing), not a per-chapter manual write route. +- **Body markdown is read-only** — the AI owns prose writing via orchestration through the host-tool path; there is **no manual body editor** (the body-editor direction was rejected 2026-06-26 — Nexus is an AI-autonomous executor; see [canvas-strategy-surface.md](../surfaces/canvas-strategy-surface.md)). Any future human body interaction is a V1.68 canvas concern (structured/node-granular, no-raw-file-editing), not a per-chapter manual write route. - All routes stay under the Daemon API and are consumed through the frontend `NexusClient` interface; no browser-only filesystem assumptions are part of the contract. ## 2. Existing implementation facts this contract builds on @@ -30,7 +30,7 @@ The surface is intentionally split: - `seed_chapters` initializes `outline_path` as `Works/{work_ref}/Outlines/chapters/chNN-outline.md` and `body_path` as `Works/{work_ref}/Stories/chNN-{slug}.md`. - `work_chapters::update_paths` and `update_status` update DB metadata with `updated_at`. - `work_chapters::sync_frontmatter_status` demonstrates the filesystem write pattern P0 must mirror for outline writes: sibling temp file, flush, atomic rename, and best-effort temp cleanup on failure. -- `host_tool_handlers.rs` body read path applies a W-002-style path guard around a DB-sourced `body_path`: resolve inside the workspace root, reject traversal, and fail closed when the resolved path escapes the workspace. +- `crates/nexus-core/src/content.rs` owns the body-read guard: `chapter_body` reads the DB-sourced `body_path` through `read_guarded_file` and `resolve_guarded_path_async` / `resolve_guarded_path`, canonicalizing under the workspace root and failing closed when the resolved path escapes it. ## 3. Endpoint summary @@ -41,7 +41,7 @@ All endpoints use the Daemon API error convention: non-2xx responses are emitted | `GET` | `/v1/daemon/works/{work_id}/chapters` | Cursor-paginated chapter summaries | No | No | | `GET` | `/v1/daemon/works/{work_id}/chapters/{n}` | Chapter detail including paths | No | No | | `GET` | `/v1/daemon/works/{work_id}/chapters/{n}/outline` | Read outline markdown | No | No | -| ~~`PUT`~~ | ~~`/v1/local/works/{work_id}/chapters/{n}/outline`~~ | **Removed in V1.75** (historical route spelling; canvas pivot). Outline prose writes now go through `POST /v1/daemon/works/{work_id}/chapters/{chapter_id}/patch` with `set.content` + `base_revision` (`outline_revision` CAS). See [canvas-strategy-surface.md](canvas-strategy-surface.md) §3.5. | — | — | +| ~~`PUT`~~ | ~~`/v1/local/works/{work_id}/chapters/{n}/outline`~~ | **Removed in V1.75** (historical route spelling; canvas pivot). Outline prose writes now go through `POST /v1/daemon/works/{work_id}/chapters/{chapter_id}/patch` with `set.content` + `base_revision` (`outline_revision` CAS). See [canvas-strategy-surface.md](../surfaces/canvas-strategy-surface.md) §3.5. | — | — | | `PATCH` | `/v1/daemon/works/{work_id}/chapters/{n}` | Structure metadata update | No | Yes | | `GET` | `/v1/daemon/works/{work_id}/chapters/{n}/body` | Read body markdown | No | No | @@ -203,7 +203,7 @@ Rules: ### 5.4 `PUT /v1/local/works/{work_id}/chapters/{n}/outline` — removed in V1.75 -**Removed in V1.75** (canvas-pivot). The historical V1.65 whole-document outline PUT route, its `put-chapter-outline-request` DTO, and schema file were retired; outline prose writes now go through the canvas patch route `POST /v1/daemon/works/{work_id}/chapters/{chapter_id}/patch` with `set.content` + `base_revision` (`outline_revision` CAS). The atomic-write / RuntimeLockGuard / body-ownership invariants that this section used to describe are re-anchored to that PATCH content path in [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) §6.2 and §7 (V1.75 amendment); see also [canvas-strategy-surface.md](canvas-strategy-surface.md) §3.5. The outline *read* (`GET …/outline`, §5.3) is unchanged. +**Removed in V1.75** (canvas-pivot). The historical V1.65 whole-document outline PUT route, its `put-chapter-outline-request` DTO, and schema file were retired; outline prose writes now go through the canvas patch route `POST /v1/daemon/works/{work_id}/chapters/{chapter_id}/patch` with `set.content` + `base_revision` (`outline_revision` CAS). The atomic-write / RuntimeLockGuard / body-ownership invariants that this section used to describe are re-anchored to that PATCH content path in [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) §6.2 and §7 (V1.75 amendment); see also [canvas-strategy-surface.md](../surfaces/canvas-strategy-surface.md) §3.5. The outline *read* (`GET …/outline`, §5.3) is unchanged. ### 5.5 `PATCH /v1/daemon/works/{work_id}/chapters/{n}` @@ -312,7 +312,7 @@ Algorithm: 5. For a missing target that is expected to be creatable, canonicalize the nearest existing parent or normalize the joined path and require the resulting absolute path to remain under the workspace root. Do not allow `..` traversal to escape before creation. 6. Reject escape with a typed validation error; do not attempt to create parent directories outside the workspace. -This mirrors the W-002 defense-in-depth guard in `host_tool_handlers.rs` around line 2006, adapted for outline writes where the target may not exist yet. +This uses the W-002 defense-in-depth authority in `crates/nexus-core/src/content.rs` (`resolve_guarded_path` / `resolve_guarded_path_async`), including guarded resolution for outline writes where the target may not exist yet. ## 8. Tauri-ready frontend boundary diff --git a/.mstar/specs/concurrency.md b/.mstar/specs/runtime/concurrency.md similarity index 96% rename from .mstar/specs/concurrency.md rename to .mstar/specs/runtime/concurrency.md index 185ad2f2b..909510e04 100644 --- a/.mstar/specs/concurrency.md +++ b/.mstar/specs/runtime/concurrency.md @@ -6,11 +6,11 @@ **Scope**: Multi-writer concurrency control for the local-first daemon + CLI model — advisory file lock + heartbeat + zombie detection + CLI integration. **Coordinates with**: -- [novel-writing/multi-work-lifecycle.md](novel-writing/multi-work-lifecycle.md) — §4-§5 DB-level `runtime_lock_holder` +- [novel-writing/multi-work-lifecycle.md](../novel-writing/multi-work-lifecycle.md) — §4-§5 DB-level `runtime_lock_holder` - `cron-staggering.md` — §4 daemon cron evaluator (archived; folded into workflow-profile.md §11) -- [novel-writing/workflow-profile.md](novel-writing/workflow-profile.md) — completion locking -- [cli-spec.md](cli-spec.md) — `creator works cron set`, `creator run`, `creator world kb adopt` -- [daemon-runtime.md](daemon-runtime.md) — daemon tick / cron supervisor +- [novel-writing/workflow-profile.md](../novel-writing/workflow-profile.md) — completion locking +- [cli-spec.md](../cli/cli-spec.md) — `creator works cron set`, `creator run`, `creator world kb adopt` +- [daemon-runtime.md](../archived/daemon-runtime.md) — daemon tick / cron supervisor --- @@ -181,10 +181,9 @@ The holder must refresh the `expires_at_ms` field in the lock file every **30 se ### 5.2 Write Protocol -The heartbeat task: -1. Seeks to the start of the `.lock` file. -2. Writes `::` where `expires_at_ms = now_ms + 60_000`. -3. Flushes. +The heartbeat task refreshes metadata via the `.lock` **path**, not by seeking or writing the file descriptor that holds `flock`: +1. Builds `::` where `expires_at_ms = now_ms + 60_000`. +2. Calls `write_lock_metadata_to_path` in `crates/nexus-local-db/src/file_lock.rs`, which uses `std::fs::write` to overwrite the path's contents. It does not explicitly flush the held lock descriptor. If the write fails (e.g., disk full), the heartbeat task logs at `error!` and continues retrying. The lock validity window is 60 s — a single missed heartbeat is tolerated. diff --git a/.mstar/specs/daemon-api-surface-conventions.md b/.mstar/specs/runtime/daemon-api-surface-conventions.md similarity index 98% rename from .mstar/specs/daemon-api-surface-conventions.md rename to .mstar/specs/runtime/daemon-api-surface-conventions.md index d6fcdc202..bbc5b6a07 100644 --- a/.mstar/specs/daemon-api-surface-conventions.md +++ b/.mstar/specs/runtime/daemon-api-surface-conventions.md @@ -5,7 +5,7 @@ | **Status** | Normative — V1.77 amendment (§11 findings PATCH route as a non-OCC resource PATCH; last-writer-wins, no revision/version, no conflict modal; cross-profile consumption). Prior: V1.74 amendment (§7.6 World KB relationship patch route extending the V1.73 World KB route pattern; additive relationship DTOs; per-row OCC with `expected_version`/`version` against `kb_relationships.revision`), V1.73 amendment (§7 World KB canvas structured patch/read routes extending the V1.71/V1.72 patch-route convention; additive World KB DTOs; per-row OCC with `expected_version`/`version`), V1.72 amendment (§7 outline/timeline structured patch routes extending the V1.71 patch-route convention; additive outline DTOs; `@42ch/nexus-contracts` 0.7.0 → 0.8.0 by default), V1.71 amendment (§7 structured patch-route convention for canvas-like surfaces; Strategy β patch routes; `@42ch/nexus-contracts` 0.6.0 → 0.7.0 by default), V1.67 amendment (§3.2 casing ratification + §4 `items` enforcement + §5 sort-param contract; `@42ch/nexus-contracts` 0.5.0 → 0.6.0), V1.64 cursor/error/`items` conventions + V1.65 chapter-content file-backed route rules. | | **Document class** | Master | | **Scope** | Cross-resource Daemon API response/query conventions for schemas under `schemas/daemon-api/` and handlers under `nexus-daemon-runtime` | -| **Coordinates with** | [schemas-directory-layout.md](./schemas-directory-layout.md), [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md), [daemon-runtime.md](./daemon-runtime.md), [findings-lifecycle.md](./findings-lifecycle.md) | +| **Coordinates with** | [schemas-directory-layout.md](../architecture/schemas-directory-layout.md), [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md), [daemon-runtime.md](../archived/daemon-runtime.md), [findings-lifecycle.md](../contracts/findings-lifecycle.md) | | **Evidence** | `surface-audit.md` | --- @@ -194,7 +194,7 @@ V1.67 implements server-side sort on: works (`updated_at`/`title`/`status`/`inta V1.65 introduces the chapter-content Daemon API surface under `/v1/daemon/works/{work_id}/chapters/*`; detailed field contracts live in -[chapter-content-local-api.md](./chapter-content-local-api.md). This section is +[chapter-content-local-api.md](chapter-content-local-api.md). This section is the normative cross-surface convention for any Daemon API route that exposes chapter outline/body files through DB-sourced paths. @@ -224,7 +224,7 @@ write route is **removed in V1.75** (canvas-pivot). Outline prose writes now go through the canvas patch route `POST /v1/daemon/works/{work_id}/chapters/{chapter_id}/patch` with `set.content` + `base_revision` (`outline_revision` CAS) — see §7 (V1.75 amendment) and -[canvas-strategy-surface.md](canvas-strategy-surface.md) §3.5. The atomic-write +[canvas-strategy-surface.md](../surfaces/canvas-strategy-surface.md) §3.5. The atomic-write invariants that this section historically attached to the removed PUT are still normative; they are re-anchored to the PATCH content path below and enforced by `crates/nexus-daemon-runtime/src/api/handlers/outline.rs::apply_chapter_patch` @@ -532,7 +532,7 @@ V1.66 desktop-shell convention: ```text GET http://127.0.0.1:/v1/daemon/runtime/health ``` - (NOT stdout parsing — see [daemon-runtime.md](daemon-runtime.md) §12.2). + (NOT stdout parsing — see [daemon-runtime.md](../archived/daemon-runtime.md) §12.2). 5. Clients MUST treat health-probe failure as transport/lifecycle failure, not as a schema mismatch. 6. **V1.66 does not introduce a dynamic port handshake endpoint or daemon-lifecycle Daemon API schema** (`wire_contracts_changed: false`). @@ -588,7 +588,7 @@ This is the correct shape for a simple CRUD PATCH on a non-OCC resource. Future - **Handler**: `update_finding_handler` in `crates/nexus-daemon-runtime/src/api/handlers/findings.rs:380-451`. - **DAO enforcement**: `update_finding` in `crates/nexus-local-db/src/findings.rs:927-1042` (enum validation + transition enforcement + dynamic SET clause builder). - **`wire_contracts_changed`**: `FALSE` for V1.77 — the route, schema, codegen, and handler are unchanged. Only consumer-side consumption is additive. -- **Spec cross-reference**: [findings-lifecycle.md](./findings-lifecycle.md) — the 6-state lifecycle, `target_executor` routing, and UI remediation surface. +- **Spec cross-reference**: [findings-lifecycle.md](../contracts/findings-lifecycle.md) — the 6-state lifecycle, `target_executor` routing, and UI remediation surface. ## 12. V1.114 compute registry and KB state read routes @@ -602,7 +602,7 @@ V1.114 adds two read-only surfaces to the Daemon API inventory. | Read a module's full manifest | `GET /v1/daemon/compute/modules/{module_id}` | `ModuleDetail` | Both endpoints reuse the existing `manifest.json` shape from -[compute-module-abi.md](./compute-module-abi.md) §7; they do not introduce a +[compute-module-abi.md](../compute/compute-module-abi.md) §7; they do not introduce a parallel module DTO. `ListModulesResponse` follows the §2 cursor-list convention (`items`, `has_more`). diff --git a/.mstar/specs/embedding-readiness.md b/.mstar/specs/runtime/embedding-readiness.md similarity index 94% rename from .mstar/specs/embedding-readiness.md rename to .mstar/specs/runtime/embedding-readiness.md index a2f64a214..5806edb0b 100644 --- a/.mstar/specs/embedding-readiness.md +++ b/.mstar/specs/runtime/embedding-readiness.md @@ -3,7 +3,7 @@ > **Status:** Normative — V1.181 P0 (readiness-contract form; posture user-locked 2026-09-02 grill-me). Promoted from the iteration-package draft in the v1.181 package (historical provenance; iteration packages are local process artifacts, not tracked at HEAD). Review-chain locks (product-manager → architect, 2026-09-02) are recorded inline as **Lock** notes. > **Document class:** Master > **Scope:** the embedding identity tuple, the fail-closed derived-index protocol, the `EmbeddingProvider` trait seam, the `NoEmbeddings` OSS posture, and the platform injection contract. Governs the `crates/nexus-embedding/` contract crate. **No OSS embedding execution.** -> **Coordinates with:** [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md), [world-kb-runtime-architecture.md](world-kb-runtime-architecture.md), [spoke-adapter-architecture.md](spoke-adapter-architecture.md) +> **Coordinates with:** [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md), [world-kb-runtime-architecture.md](../architecture/world-kb-runtime-architecture.md), [spoke-adapter-architecture.md](../architecture/spoke-adapter-architecture.md) ## 0. Document Position @@ -119,4 +119,4 @@ No additional consumer is in scope. CLI, daemon, and MCA paths must not call `em ## 8. Roadmap close (product) -When this contract ships, [`harness` RN-OGA-3](../projects/harness/roadmap.md) is closeable: Done-definition (identity invalidates index; mismatch fail-closed; lexical fallback explicit) is satisfied in contract form. [`harness` DF-78](../projects/harness/roadmap.md) stays open; annotate its gate to "RN-OGA-3 contract locked v1.181". Runtime trigger moves with DF-78 to the platform era. +When this contract ships, [`harness` RN-OGA-3](../../projects/harness/roadmap.md) is closeable: Done-definition (identity invalidates index; mismatch fail-closed; lexical fallback explicit) is satisfied in contract form. [`harness` DF-78](../../projects/harness/roadmap.md) stays open; annotate its gate to "RN-OGA-3 contract locked v1.181". Runtime trigger moves with DF-78 to the platform era. diff --git a/.mstar/specs/local-db-schema.md b/.mstar/specs/runtime/local-db-schema.md similarity index 93% rename from .mstar/specs/local-db-schema.md rename to .mstar/specs/runtime/local-db-schema.md index cc6184623..f90113521 100644 --- a/.mstar/specs/local-db-schema.md +++ b/.mstar/specs/runtime/local-db-schema.md @@ -3,14 +3,14 @@ **Status**: Normative **Document class**: Master **V1.40 Shipped amendments:** §4.1.2 `kb_key_blocks` validation intent — application-layer validation in `nexus-kb::validation` module (ValidationMode::Novel enforces `body.attributes.novel_category`); `narrative_worlds` rows via `creator world create` (V1.40 P0); `kb_extract_jobs` artifact locator columns (`source_kind`, `source_locator`, `profile_hint`, `work_id`) added V1.40 P3. -**V1.42 Draft amendment:** `work_chapters` PK migration — composite primary key `(work_id, volume, chapter)` with `volume INTEGER NOT NULL DEFAULT 1`; backfill existing rows `volume = 1`; drop legacy `(work_id, chapter)` PK. Normative detail: [novel-writing/workflow-profile.md §4.5.4](novel-writing/workflow-profile.md). -**V1.139 architect §5.2 amendment:** §4.1.2 `kb_key_blocks` — `extensions_nexus_json TEXT` column (additive migration) for spoke `extensions.nexus` round-trip preservation. Existing columns (`world_id`, `created_from_command_id`, `source_work_id`, `source_chapter`, `source_provenance_kind`) retained for query efficiency. Full contract: [`spoke-adapter-architecture.md`](spoke-adapter-architecture.md) §2.3. +**V1.42 Draft amendment:** `work_chapters` PK migration — composite primary key `(work_id, volume, chapter)` with `volume INTEGER NOT NULL DEFAULT 1`; backfill existing rows `volume = 1`; drop legacy `(work_id, chapter)` PK. Normative detail: [novel-writing/workflow-profile.md §4.5.4](../novel-writing/workflow-profile.md). +**V1.139 architect §5.2 amendment:** §4.1.2 `kb_key_blocks` — `extensions_nexus_json TEXT` column (additive migration) for spoke `extensions.nexus` round-trip preservation. Existing columns (`world_id`, `created_from_command_id`, `source_work_id`, `source_chapter`, `source_provenance_kind`) retained for query efficiency. Full contract: [`spoke-adapter-architecture.md`](../architecture/spoke-adapter-architecture.md) §2.3. **Last updated**: 2026-09-19 — v1.191 P1: holder registry, native governance columns and knowledge revisions (schema 23 → 24). -**v1.191 P1 amendment (shipped):** [holder-governance.md §§2–6](holder-governance.md#2-registry-identity-stability-and-lifecycle) owns the workspace holder registry (`knowledge_holders`), the native KE governance columns (`holder_entry_id` / `disclosure` on `kb_key_blocks`), the World/Character `knowledge_revision` columns, the isolated import quarantine (`knowledge_import_quarantine`), the guarded offline migration and rollback. The ordered migration `20260918000001_holder_registry.sql` raises the schema version 23 → 24; the legacy `creator_only` column and the `extensions.nexus.creator_only` key are removed from every runtime path and refused on input. Actor narrative ownership remains the existing three-container model; no fake World lore rows or parallel holder database are introduced. +**v1.191 P1 amendment (shipped):** [holder-governance.md §§2–6](../architecture/holder-governance.md#2-registry-identity-stability-and-lifecycle) owns the workspace holder registry (`knowledge_holders`), the native KE governance columns (`holder_entry_id` / `disclosure` on `kb_key_blocks`), the World/Character `knowledge_revision` columns, the isolated import quarantine (`knowledge_import_quarantine`), the guarded offline migration and rollback. The ordered migration `20260918000001_holder_registry.sql` raises the schema version 23 → 24; the legacy `creator_only` column and the `extensions.nexus.creator_only` key are removed from every runtime path and refused on input. Actor narrative ownership remains the existing three-container model; no fake World lore rows or parallel holder database are introduced. ## 0. 文档定位 -本稿是 [`cli-spec.md`](./cli-spec.md) 与 nexus-platform `v1-spec/architecture.md` 的实现下钻，定义 **Nexus 本地 SQLite（`state.db`）** 的职责边界、模块拆分与演进策略。 +本稿是 [`cli-spec.md`](../cli/cli-spec.md) 与 nexus-platform `v1-spec/architecture.md` 的实现下钻，定义 **Nexus 本地 SQLite（`state.db`）** 的职责边界、模块拆分与演进策略。 **磁盘路径 SSOT**（`state.db` 落在 `$HOME/.nexus42/creators//workspaces//` 等）：nexus-platform `v1-spec/adr/adr-014-local-fs-creator-workspace-layout-v1.md`。 @@ -258,11 +258,11 @@ Column notes: **V1.139 architect §5.2 amendment — `extensions_nexus_json` column:** -The `extensions_nexus_json TEXT` column is additive (V1.139 migration adds it via `ALTER TABLE`). It stores the full `extensions.nexus` JSON payload from spoke `KnowledgeEntry.extensions.nexus` for round-trip preservation of unknown keys. Known nexus-local fields (`world_id`, `created_from_command_id`, `source_work_id`, `source_chapter`, `source_provenance_kind`) are kept as typed SQLite columns — this preserves query efficiency (e.g., `list_by_world` filters on the indexed `world_id` column without JSON extraction). The `nexus-spoke-adapter` constructs `extensions.nexus` from typed columns + `extensions_nexus_json` (merged) when reading, and extracts known fields into typed columns + serializes the full `extensions.nexus` into `extensions_nexus_json` when writing. See [`spoke-adapter-architecture.md`](spoke-adapter-architecture.md) §2.3 for the full storage contract. +The `extensions_nexus_json TEXT` column is additive (V1.139 migration adds it via `ALTER TABLE`). It stores the full `extensions.nexus` JSON payload from spoke `KnowledgeEntry.extensions.nexus` for round-trip preservation of unknown keys. Known nexus-local fields (`world_id`, `created_from_command_id`, `source_work_id`, `source_chapter`, `source_provenance_kind`) are kept as typed SQLite columns — this preserves query efficiency (e.g., `list_by_world` filters on the indexed `world_id` column without JSON extraction). The `nexus-spoke-adapter` constructs `extensions.nexus` from typed columns + `extensions_nexus_json` (merged) when reading, and extracts known fields into typed columns + serializes the full `extensions.nexus` into `extensions_nexus_json` when writing. See [`spoke-adapter-architecture.md`](../architecture/spoke-adapter-architecture.md) §2.3 for the full storage contract. #### 4.1.4 `works` lifecycle lock columns (V1.41 Draft — DF-60) -Additive columns on existing `works` table. Normative: [novel-writing/multi-work-lifecycle.md](novel-writing/multi-work-lifecycle.md). +Additive columns on existing `works` table. Normative: [novel-writing/multi-work-lifecycle.md](../novel-writing/multi-work-lifecycle.md). | Column | Type | Required | Notes | | --- | --- | --- | --- | @@ -274,7 +274,7 @@ Additive columns on existing `works` table. Normative: [novel-writing/multi-work #### 4.1.5 Novel work pool tables (V1.41 Draft — DF-61) -Creator-scoped; not Work rows. Normative: [novel-writing/work-pool.md](novel-writing/work-pool.md). Validation rules for KB taxonomy: see [nexus-knowledge::world_kb::validation](../../crates/nexus-knowledge/src/world_kb/validation.rs) (World KB — separate concern). +Creator-scoped; not Work rows. Normative: [novel-writing/work-pool.md](../novel-writing/work-pool.md). Validation rules for KB taxonomy: see [nexus-knowledge::world_kb::validation](../../../crates/nexus-knowledge/src/world_kb/validation.rs) (World KB — separate concern). **`novel_pool_entries`** @@ -468,7 +468,7 @@ V1 要求从“文本比较两个实现”升级到“验证共享模块契约 ## 10. 与 v1 其他规格的对齐 -- 与 [`cli-spec.md`](./cli-spec.md) 对齐： +- 与 [`cli-spec.md`](../cli/cli-spec.md) 对齐： - 本地 runtime 由 CLI/daemon 驱动，但底层本地 DB 能力应模块化复用。 - 与 nexus-platform `v1-spec/shared/schema/codegen-strategy-v1.md` 对齐： - wire contract 仍由 JSON Schema 真源驱动，本稿不改变该事实。 diff --git a/.mstar/specs/outbox-consolidation.md b/.mstar/specs/runtime/outbox-consolidation.md similarity index 97% rename from .mstar/specs/outbox-consolidation.md rename to .mstar/specs/runtime/outbox-consolidation.md index ce59583ca..554daee13 100644 --- a/.mstar/specs/outbox-consolidation.md +++ b/.mstar/specs/runtime/outbox-consolidation.md @@ -6,8 +6,8 @@ **Date**: 2026-06-22 **Scope**: Consolidation of dual-outbox architecture into a single unified outbox schema in `nexus-local-db`. Defines single-writer rule, schema ownership boundary, migration path, and flush/compact semantics. **Coordinates with**: -- [orchestration-engine.md](orchestration-engine.md) §5.2 (capability roster — `outbox.flush` / `outbox.compact` rows move from Deferred wiring → Shipped) -- [daemon-runtime.md](daemon-runtime.md) §11 (flush/compact invocation path) +- [orchestration-engine.md](../orchestration/orchestration-engine.md) §5.2 (capability roster — `outbox.flush` / `outbox.compact` rows move from Deferred wiring → Shipped) +- [daemon-runtime.md](../archived/daemon-runtime.md) §11 (flush/compact invocation path) --- diff --git a/.mstar/specs/reference-knowledge.md b/.mstar/specs/runtime/reference-knowledge.md similarity index 73% rename from .mstar/specs/reference-knowledge.md rename to .mstar/specs/runtime/reference-knowledge.md index 98df1afad..a9d4f5a7a 100644 --- a/.mstar/specs/reference-knowledge.md +++ b/.mstar/specs/runtime/reference-knowledge.md @@ -5,7 +5,7 @@ **Created**: 2026-06-22 (Draft at P1) **Promoted to Master**: 2026-06-22 (V1.58 P-last) **Scope**: Reference body externalization — refreshable scan pipeline for DF-44 -**Coordinates with**: [acp-capability-set.md](acp-capability-set.md) §4, [capability-registry.md](capability-registry.md) §2.8, [daemon-runtime.md](daemon-runtime.md) §10, [entity-scope-model.md](entity-scope-model.md) +**Coordinates with**: [acp-capability-set.md](../agents/acp-capability-set.md) §4, [capability-registry.md](../agents/capability-registry.md) §2.8, [daemon-runtime.md](../archived/daemon-runtime.md) §10, [entity-scope-model.md](../architecture/entity-scope-model.md) --- @@ -14,7 +14,7 @@ This Draft spec defines the `nexus.reference.refresh` capability and the reference body refreshable scan pipeline introduced in V1.58 P1 (DF-44). It covers the refresh policy model, DB schema for refresh tracking, -capability admission contracts, and the daemon-side refresh-scheduler hook. +capability admission contracts, and the refresh-scheduler hook. The static registration of reference sources was shipped in V1.26. V1.58 P1 adds the refreshable pipeline core (capability + DB migration + @@ -28,9 +28,10 @@ scheduler). V1.58 P3 adds the CLI subcommand and cross-cut E2E tests. - DB schema for refresh tracking: `reference_sources.last_refreshed_at`, `refresh_policy`, `refresh_status` columns and supporting indexes. - `nexus.reference.refresh` capability: admission, handler binding, output shape. -- Daemon-side refresh-scheduler hook: periodic stale-source scan + dispatch. +- Refresh-scheduler hook (retained implementation, §3): periodic stale-source scan + dispatch. - Integration points: `capability::Registry` (orchestration), - daemon runtime (periodic task). + `crates/nexus-core/src/execution/schedules/refresh.rs` (retained scheduler, + unwired — §3). Non-goals: CLI subcommand (`nexus42 reference refresh`) deferred to P3; cross-cut E2E tests deferred to P3; `entity-scope-model.md` unchanged @@ -63,8 +64,28 @@ The refresh lifecycle status (`refresh_status`) tracks the current state: ## 3. Refresh scheduler contract -The daemon-side refresh-scheduler hook (`crates/nexus-daemon-runtime/src/refresh_scheduler.rs`) -is a periodic `tokio::spawn` task: +The refresh-scheduler implementation in `crates/nexus-core/src/execution/schedules/refresh.rs` +exposes `spawn_refresh_scheduler` (which spawns a periodic `tokio` task when +called) and `run_one_refresh_tick` (one sweep tick). The capability is owned by +`crates/nexus-orchestration/src/capability/builtins/reference_refresh.rs`; +tool registration and creator-context wiring live in +`crates/nexus-core/src/execution/capabilities.rs`. + +**Retained implementation, not a running service.** These are the current code +homes, but no current boot path spawns the scheduler: `spawn_refresh_scheduler` +has zero call sites in `crates/` and `apps/` (the daemon boot path that spawned +it was deleted with the v1.193 P2 host removal). Nor does any production caller +invoke `nexus.reference.refresh`; only +`crates/nexus-orchestration/tests/cross_reference_refresh_e2e.rs` exercises the +capability. Registered reference sources therefore do **not** refresh +automatically today; periodic refresh is unwired pending an explicit +boot/composition decision. + +**V1.58 historical host:** the scheduler formerly lived in +`crates/nexus-daemon-runtime/src/refresh_scheduler.rs`, and the former +`crates/nexus-daemon-runtime/src/boot.rs` §4e spawned it at daemon startup. +Those deleted host paths describe the V1.58 composition, not current boot wiring. +The retained scheduler contract is: - **Cadence**: Configurable interval (default 3600s = 1 hour). Overridable via `NEXUS_DAEMON_REFRESH_SCHEDULER_INTERVAL_SECS` env var. @@ -117,14 +138,14 @@ Indexes: - `idx_reference_sources_refresh_status` — index on `refresh_status` for quick filtering. -DAO methods added to `crates/nexus-local-db/src/reference_source.rs`: +Current tracking DAO owner: `crates/nexus-local-db/src/reference_source.rs` (refresh lifecycle methods introduced with the V1.58 migration above): - `set_refresh_policy(source_id, policy)` — change the refresh policy. - `mark_refreshing(source_id)` — set `refresh_status = 'refreshing'`. - `mark_refreshed(source_id, new_body_hash)` — set `last_refreshed_at`, `refresh_status = 'fresh'`, `content_hash`. - `mark_refresh_error(source_id, error_msg)` — set `refresh_status = 'error'`. -- `find_stale_sources(now, stale_threshold_seconds, limit)` — find sources +- `find_stale_sources(pool, limit, stale_threshold_seconds)` — find sources due for refresh. --- @@ -144,8 +165,8 @@ DAO methods added to `crates/nexus-local-db/src/reference_source.rs`: - URL must be non-empty (else `error` status, not a capability error — the handler returns an error status in the output JSON). - Network timeout returns `TransientExternal` capability error. -- **Pool dependency**: Without a pool, returns `WorkerUnavailable`. In production - the refresh scheduler constructs the capability with its own pool. +- **Pool dependency**: Without a pool, returns `WorkerUnavailable`. The retained + scheduler constructs the capability with its own pool when spawned (§3). ### Sibling capability IDs (deferred) @@ -161,17 +182,17 @@ deferred to P3 if the user-facing surface (CLI) requires them. P1 ships only - **`crates/nexus-orchestration/src/capability/builtins/reference_refresh.rs`**: Capability handler struct + `Capability` trait impl. -- **`crates/nexus-orchestration/src/capability/mod.rs`**: - `CapabilityRegistry` constructors (`with_builtins`, `with_builtins_and_pool`, - `with_runtime_deps`) all include `ReferenceRefresh`. -- **`crates/nexus-daemon-runtime/src/refresh_scheduler.rs`**: - Periodic task that queries stale sources and dispatches refresh. -- **`crates/nexus-daemon-runtime/src/boot.rs`**: - §4e spawns the refresh scheduler at daemon startup. +- **`crates/nexus-core/src/execution/capabilities.rs`**: + Registers `nexus.reference.refresh` in the core tool table and wires the pool + and active creator context before delegating to `ReferenceRefresh`. +- **`crates/nexus-core/src/execution/schedules/refresh.rs`**: + Owns `spawn_refresh_scheduler` and `run_one_refresh_tick`; queries stale + sources and dispatches refresh. The former V1.58 daemon boot composition is + historical (§3), not a current startup anchor. - **`crates/nexus-local-db/src/reference_source.rs`**: Refresh lifecycle DAOs (`set_refresh_policy`, `mark_refreshing`, `mark_refreshed`, `mark_refresh_error`, `find_stale_sources`). -- **`crates/nexus-local-db/migrations/202606220003_*`**: +- **`crates/nexus-local-db/migrations/202606220003_reference_sources_refresh_tracking.sql`**: DB migration adding `last_refreshed_at`, `refresh_policy`, `refresh_status`. --- @@ -209,7 +230,7 @@ deferred to P3 if the user-facing surface (CLI) requires them. P1 ships only ### 7.2 Scheduled refresh flow -1. Daemon boots → refresh scheduler spawns with 60s initial delay. +1. V1.58 historical daemon boot flow: the former host spawned the scheduler with a 60s initial delay. The current scheduler implementation is `crates/nexus-core/src/execution/schedules/refresh.rs` (§3); this example does not assert current host startup wiring. 2. After 60s, first tick: `find_stale_sources()` queries `reference_sources`. 3. For each stale source: `ReferenceRefresh::run({"reference_source_id": "..."})`. 4. Handler fetches URL, compares hash, updates DB. diff --git a/.mstar/specs/reference-store-layout.md b/.mstar/specs/runtime/reference-store-layout.md similarity index 92% rename from .mstar/specs/reference-store-layout.md rename to .mstar/specs/runtime/reference-store-layout.md index 831f64241..ef9828084 100644 --- a/.mstar/specs/reference-store-layout.md +++ b/.mstar/specs/runtime/reference-store-layout.md @@ -5,7 +5,7 @@ | **Status** | Active — normative V1.26 design for local reference registry + body storage | | **Document class** | Master | | **Scope** | User-scoped reference registration metadata in SQLite; canonical reference body text on disk under `~/.nexus42` | -| **Related** | v1.26 delivery compass §2, [local-db-schema.md](local-db-schema.md), [entity-scope-model.md](entity-scope-model.md) | +| **Related** | v1.26 delivery compass §2, [local-db-schema.md](local-db-schema.md), [entity-scope-model.md](../architecture/entity-scope-model.md) | ## 1. Decision @@ -78,10 +78,14 @@ The canonical body path remains `content_path`; callers must not infer filesyste ## 6. Contract/type alignment notes +> **Frozen historical implementation snapshot — As of R1.** The two observations below record the R1 state, not current implementation requirements. + As of R1, `crates/nexus-knowledge/src/reference_source.rs` and `crates/nexus-contracts/src/local/domain/reference_source.rs` do not yet expose `content_path` or `source_mutability`. R2/R3 implementation should add those fields to the local/domain representation before repository and handler wiring, or introduce an explicit DB DTO that carries them without duplicating wire-contract ownership. Generated files under `crates/nexus-contracts/src/generated/` currently contain only the shared `ReferenceSourceType` and `ScanStatus` enums; no generated `ReferenceSource` DTO needs hand edits. +**Current state:** the DAO's `ReferenceSourceRow` in `crates/nexus-local-db/src/reference_source.rs` carries both `source_mutability` and `content_path`; the historical domain/generated-type observation above does not imply those fields are absent from current storage. + ## 7. Migration policy Pre-1.0 local persistence may be wiped rather than migrated. The V1.26 migration should add `content_path TEXT` and `source_mutability TEXT NOT NULL DEFAULT 'static'`; legacy inline `content` should be retained only for compatibility and set to `NULL` for new rows. diff --git a/.mstar/specs/canvas-strategy-surface.md b/.mstar/specs/surfaces/canvas-strategy-surface.md similarity index 97% rename from .mstar/specs/canvas-strategy-surface.md rename to .mstar/specs/surfaces/canvas-strategy-surface.md index 4c7988a77..f6895c7b6 100644 --- a/.mstar/specs/canvas-strategy-surface.md +++ b/.mstar/specs/surfaces/canvas-strategy-surface.md @@ -5,7 +5,7 @@ | **Status** | **Shipped β (V1.74)** — Strategy read + visualization + live overlay + Idea-steer (V1.70), write-boundary operation DTOs + node-granular Strategy edits + conflict policy (V1.71), Outline+Timeline canvas β (Work → Volume → Chapter → Scene/Beat graph projection + timeline lane + foreshadow edges + 3 structured patch routes `outline.patch_structure` / `outline.patch_chapter` / `timeline.patch_event` + outlineRevision + structured conflict error + UI retry/merge + non-spatial alternate views) (V1.72), World KB canvas β (World KB graph + candidates projections, 2 structured patch routes `kb.patch_entity` / `kb.promote_candidate`, per-row OCC on `kb_key_blocks.revision` / `kb_extract_jobs.version`, 409/422 structured errors, and 4 Daemon API routes) (V1.73), and typed World KB relationship editing (schema-backed relationship DTOs, `world_kb.patch_relationship`, `kb_relationships.revision` OCC, directed/symmetric projections, non-spatial relationship table) (V1.74) are shipped. **Post-V1.74 overlay amendments (additive):** V1.122 Timeline peer surface + V1.123 three-layer/Work Timeline (Draft), V1.156 3×2 matrix completion, V1.159 era taxonomy, V1.162 fork authoring chrome, V1.163 event-level cross-surface binding — see the promotion blockquote chain below; shipped β text preserved; `wire_contracts_changed: false`. | | **Document class** | Draft overlay | | **Scope** | Product vision + Draft architecture for the human-facing **Canvas** control surfaces: Strategy (Preset) orchestration graph, Work outline + timeline graph, World KB graph; React Flow rendering; the "AI owns prose, human steers via Canvas" thesis; node-granular write boundaries; canvas token contract for DESIGN.md placeholders | -| **Coordinates with** | [orchestration-engine.md](orchestration-engine.md) (strategy = graph-of-graphs), [web-ui.md](web-ui.md) (§15 V1.67 stage + V1.68 canvas roadmap), [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md), [chapter-content-local-api.md](chapter-content-local-api.md), [daemon-runtime.md](daemon-runtime.md) | +| **Coordinates with** | [orchestration-engine.md](../orchestration/orchestration-engine.md) (strategy = graph-of-graphs), [web-ui.md](web-ui.md) (§15 V1.67 stage + V1.68 canvas roadmap), [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md), [chapter-content-local-api.md](../runtime/chapter-content-local-api.md), [daemon-runtime.md](../archived/daemon-runtime.md) | | **Supersedes** | the retired body-editor direction (rejected 2026-06-26; see §1 product thesis) | | **Authored** | V1.67 Phase 2b re-discussion — **@architect** (architecture + React Flow feasibility + DAG↔canvas mapping + write boundary) + **@product-manager** (product thesis + canvas UX + Strategy terminology); PM-scaffolded stub pending authoring | @@ -234,14 +234,14 @@ Surfaces should pass the returned `nodes`, `edges`, `nodeTypes`, `onNodesChange` > - **PD-6 post-create landing:** on success the canvas sets its active branch context to the response `branch_id` and renders that branch's World Timeline immediately (threaded through the existing `branch_id` query param on the timeline-events read — no new wire, no daemon change). > - **Read-only lineage chrome (fork-badge):** when the active branch is a fork, the canvas header shows a fork-badge + parent branch + fork-point event read-only, with **one-hop "open parent branch" navigation** back to the parent Timeline (`activeBranchId = parent_branch_id`). > - **Read-only by contract:** no merge, no lineage edit, no multi-branch comparison; **fork-merge remains a Non-Goal** (`BL-01`). -> - **Carrier:** the chrome derives from the **branch-level `fork_created` marker** (data composition below; [`entity-scope-model.md`](entity-scope-model.md) §6.6.3) — it is NOT bound to the world-level `WorldState.{is_fork, parent_world_id}` platform-fork fields. +> - **Carrier:** the chrome derives from the **branch-level `fork_created` marker** (data composition below; [`entity-scope-model.md`](../architecture/entity-scope-model.md) §6.6.3) — it is NOT bound to the world-level `WorldState.{is_fork, parent_world_id}` platform-fork fields. The Timeline surface is **World-scoped**. It projects a World's history — events, KnowledgeEntry entities, typed relationships — onto a when-axis, making the World's Timeline the central instrument for World building. It is the **default surface for World entry** (§4.5); the Outline (Timeline-companion) surface remains the default for Work entry (V1.118, unchanged). #### Data composition (LOCKED — single graph source) - **Graph source (sole):** `GET /v1/daemon/worlds/{world_id}/kb/graph` → **`WorldKbGraphResponse`** (V1.73 shipped; schema `schemas/daemon-api/canvas/world-kb/world-kb-graph-response.schema.json`). The adapter's `projectGraph` accepts `WorldKbGraphResponse` directly — **no wrapper, no join, no second graph endpoint**. -- **Fork-lineage chrome (header chrome only; V1.162 shipped):** the orchestrator derives the active branch's fork state from its `fork_created` marker — a `GET /v1/daemon/worlds/{world_id}/timeline/events` read filtered to `event_type=fork_created` (0-or-1 canon marker row; the marker carries `extensions.fork_lineage`). `is_fork` is `true` iff a `fork_created` marker is present on the active branch; `parent_branch_id` / `forked_from_event_id` / `label?` are read from the marker's `extensions.fork_lineage` ([`entity-scope-model.md`](entity-scope-model.md) §6.6.3, carrier B). The badge is **branch-level** — it is NOT bound to the world-level `WorldState.{is_fork, parent_world_id}` platform-fork fields. This chrome is **not a timeline data source**; it MUST NOT be merged into `projectGraph`. If the marker read is absent or errors, the badge is omitted (graceful degradation) and the Timeline surface remains fully functional. +- **Fork-lineage chrome (header chrome only; V1.162 shipped):** the orchestrator derives the active branch's fork state from its `fork_created` marker — a `GET /v1/daemon/worlds/{world_id}/timeline/events` read filtered to `event_type=fork_created` (0-or-1 canon marker row; the marker carries `extensions.fork_lineage`). `is_fork` is `true` iff a `fork_created` marker is present on the active branch; `parent_branch_id` / `forked_from_event_id` / `label?` are read from the marker's `extensions.fork_lineage` ([`entity-scope-model.md`](../architecture/entity-scope-model.md) §6.6.3, carrier B). The badge is **branch-level** — it is NOT bound to the world-level `WorldState.{is_fork, parent_world_id}` platform-fork fields. This chrome is **not a timeline data source**; it MUST NOT be merged into `projectGraph`. If the marker read is absent or errors, the badge is omitted (graceful degradation) and the Timeline surface remains fully functional. - **Explicitly NOT composed:** Work-scoped outline timeline events (`timeline.patch_event` surface) are **not** merged onto the World when-axis in V1.122. They are chapter-relative (`realizes_chapter_id`, foreshadow edges between chapter-linked events) with no World-level merge key; composing them would require N+1 fetches per bound Work. They remain on the Outline (Timeline-companion) surface for Work entry. - **Deferred:** a World-scoped `TimelineEvent` HTTP route (`GET /v1/daemon/worlds/{world_id}/timeline`) is out of V1.122 scope (would require daemon Rust changes + a new external route). The domain `schemas/domain/timeline-event.schema.json` table remains reachable only via `NarrativeGateway::get_timeline()` (internal) and the `nexus.timeline.recent.get` host-tool capability. Tracked under `DF-V1122-DEEPER-WB`. @@ -254,7 +254,7 @@ The Timeline surface is **World-scoped**. It projects a World's history — even | `relationships[]` | Typed relationship edges (read-only in V1.122), reusing `WorldKbEdgeData` **verbatim** (V1.74 `WorldKbRelationshipProjection`) | `Edge` where `TimelineEdgeData = WorldKbEdgeData` | | `source_anchors[]` | Grounding badge data on referenced nodes (optional rendering) | Node metadata; **not** a separate node kind | -`block_type=event` entities ARE World-scoped narrative events per [`entity-scope-model.md`](entity-scope-model.md) §5.1.1 — they ARE the "when-axis" content the Timeline hero surface projects. `foreshadow` / `realizes` / `fork-from` are **Work-outline projection labels**, not Timeline edge DTOs; the Timeline surface introduces **no** new edge types. +`block_type=event` entities ARE World-scoped narrative events per [`entity-scope-model.md`](../architecture/entity-scope-model.md) §5.1.1 — they ARE the "when-axis" content the Timeline hero surface projects. `foreshadow` / `realizes` / `fork-from` are **Work-outline projection labels**, not Timeline edge DTOs; the Timeline surface introduces **no** new edge types. #### Node types @@ -305,11 +305,11 @@ V1.122 P1 adds **only** a frontend `CanvasSurfaceKind = "timeline"` enum value + > **V1.156 amendment (shipped) — 3×2 matrix completion.** V1.156 closed the two deferred matrix cells: **World Timeline gains the Moment layer** (`DF-V1123-WORLD-MOMENT` — read/projection of bound Works' scene-precision; Moments remain Work-owned) and **Work Timeline gains the Brief layer** (`DF-V1123-WORK-BRIEF` — projection of the bound World's Brief; Brief remains World spine). V1.156 shipped: both surfaces render all three layers (Brief + Narrative + Moment). This is an **additive amendment** to the V1.123 overlay: it does not rewrite the V1.123 carrier locks or conflict policy; it extends each surface's layer set from two to three. Both amendments are **frontend-only** (`wire_contracts_changed: false` — see the "wire_contracts_changed: false verification (V1.156)" subsection below). Product semantics locked in `product-locks.md` PD-2 / PD-3. **Promoted to Normative (V1.158)** — the V1.123 overlay shipped its two-layer composition in V1.123 but was not promoted at V1.123 P-last (spec-hygiene debt); this amendment completed the matrix and was the promotion point for the whole §3.3.3 overlay. -> **V1.159 amendment (architect-locked, Phase 1 review chain) — typed nested era taxonomy (DF-V1123-ERA-TAXONOMY).** V1.159 deepens the Brief layer from a flat `block_type=era` marker list (V1.123) into a **typed nesting tree**: eras gain an optional `body.attributes.era_type` (freeform string) and era-era parent-child nesting via the §5.6 `custom` + `custom_label = "parent_era"` relationship edge. The Brief layer renders the tree as **vertical time bands** with per-type coloring and indented nesting. This is an **additive amendment** to the V1.123/V1.156 overlay: it does not change any carrier lock, layer-set, conflict policy, or write boundary; it extends the Brief-layer projection from flat-era to relationship-aware nested-era. It is **frontend-only** (`wire_contracts_changed: false` — era_type rides freeform `body.attributes`; nesting reuses the production V1.144 `relate` / V1.74 `patch_relationship` custom+label path with zero schema/codegen change; see the "Brief layer time-band UI contract (V1.159)" subsection below). Product semantics locked in `product-locks.md` PD-1..PD-6; era_type field semantics in [`entity-scope-model.md`](./entity-scope-model.md) §5.1.1 V1.159 amendment. **VC-1 resolved (architect pass):** `parent_era` is carried as `custom` + `custom_label` (NOT a new `WorldKbRelationshipKind` wire enum value) — see product-locks VC-1 resolution. +> **V1.159 amendment (architect-locked, Phase 1 review chain) — typed nested era taxonomy (DF-V1123-ERA-TAXONOMY).** V1.159 deepens the Brief layer from a flat `block_type=era` marker list (V1.123) into a **typed nesting tree**: eras gain an optional `body.attributes.era_type` (freeform string) and era-era parent-child nesting via the §5.6 `custom` + `custom_label = "parent_era"` relationship edge. The Brief layer renders the tree as **vertical time bands** with per-type coloring and indented nesting. This is an **additive amendment** to the V1.123/V1.156 overlay: it does not change any carrier lock, layer-set, conflict policy, or write boundary; it extends the Brief-layer projection from flat-era to relationship-aware nested-era. It is **frontend-only** (`wire_contracts_changed: false` — era_type rides freeform `body.attributes`; nesting reuses the production V1.144 `relate` / V1.74 `patch_relationship` custom+label path with zero schema/codegen change; see the "Brief layer time-band UI contract (V1.159)" subsection below). Product semantics locked in `product-locks.md` PD-1..PD-6; era_type field semantics in [`entity-scope-model.md`](../architecture/entity-scope-model.md) §5.1.1 V1.159 amendment. **VC-1 resolved (architect pass):** `parent_era` is carried as `custom` + `custom_label` (NOT a new `WorldKbRelationshipKind` wire enum value) — see product-locks VC-1 resolution. > **V1.163 amendment (architect-locked, Phase 1 review chain) — event-level cross-surface binding carrier (DF-V1123-CROSS-SURFACE-BINDING).** V1.163 upgrades the V1.123 P3 surface-level cross-surface CTAs ("View on World Timeline" / "View in Work Timeline") to **event-level read-only deep-links**. The carrier is an additive optional field `world_event_id?: string` on `WorkOutline.timeline_events[]` items (schema `schemas/daemon-api/canvas/outline/work-outline.schema.json`, `additionalProperties: false` preserved). The **referent is locked to the World KB entity `key_block_id`** — a `block_type=event` KnowledgeEntry entity from `WorldKbGraphResponse.entities[]`, which is exactly the id the World Timeline Narrative layer projects (React Flow node id = `entity:`; `TimelineNodeData extends WorldKbEntityProjection`, `nodeIdOf(keyBlockId)`). It is **NOT** `narrative_timeline_events.id` (`evt_…`) — those `TimelineEventInfo` rows are compute-result / fork-marker log events merged as synthetic `compute:` nodes (V1.147 P2 T3), not authored when-axis content; using them would require an explicit join with no projection benefit and would target non-selectable synthetic nodes. Work→World forward reads `world_event_id` on the selected Work event → `/worlds/:worldId/timeline?layer=narrative&event=:worldEventId` (`worldEventId` = `key_block_id`). World→Work reverse scans the capped set of realizing Works' outlines (`timeline_events[].world_event_id === `) → `/works/:workId/timeline?layer=narrative&event=:workEventId` (`workEventId` = `WorkOutline.timeline_events[].event_id`, Work Timeline React Flow node id `wt-event:`). **Focus mechanism = React Flow node selection** (destination orchestrator reads `?event=` via the existing `useSearchParams()` layer-param plumbing and selects the matching node after projection; unknown id → Narrative layer loads, no fabricated node — honest empty focus). Reverse fan-out cap = N=20 most-recent Works (reuses the V1.123 P3 `useWorks({ limit: 20 })` + per-Work detail fan-out; event-level scan adds an outline read for the capped candidate set). This is an **additive amendment**: it adds the `world_event_id` field + event-level focus behavior; it changes no layer-set, write boundary, or conflict policy. The V1.123 surface-level fallback (Work↔World bound but no event-level match → `?layer=narrative` without `event`) is preserved (PD-5 three-state matrix). Read-only in V1.163 — no author write path (deferred to post-dogfood; **superseded by the V1.200 Outline binding-authoring amendment below**). Authoritative iteration-scoped elaboration: `cross-surface-event-binding-product-locks.md`. -> **V1.200 amendment (shipped) — persisted Work-owned scene/beat carrier (DR-26 / `DF-V1123-MOMENT-WIRE`).** V1.200 replaces the deferred/fixtures-only Moment carrier with persisted Work-owned `WorkOutline.scenes[]` / `beats[]` (`{scene_id, chapter_id, title, status}` / `{beat_id, scene_id, title, status}`), read through the existing `GET /v1/daemon/works/{work_id}/outline` boundary and authored through four additive `outline.patch_structure` operations (`add_scene` / `remove_scene` / `add_beat` / `remove_beat` — see §3.5). This section's Layer composition and both surfaces' **Carrier contract** rows below are amended accordingly: the Work Timeline Moment layer projects its own `WorkOutline` carrier; the World Timeline Moment layer projects the composed bound-Work carrier (each entry tagged with its owning Work — chapter numbers are Work-local, so two Works that each own a chapter 1 stay distinct). Ownership is unchanged: **Outline remains the single authoring home; both Timeline Moment layers stay read-only projections; no World KB entity or storage change is introduced; scenes/beats are never fabricated** — an empty canonical array is real emptiness. Default layers are unchanged (World: Brief-if-`era`-data-else-Narrative; Work: Narrative). Coordinate [entity-scope-model.md](entity-scope-model.md) §1.4. **V1.200 is a wire change** (`wire_contracts_changed: true` — schema + codegen + Rust core + napi + service translation), which is why the V1.156 "frontend-only" verification paragraphs below are now explicitly version-scoped to V1.156. +> **V1.200 amendment (shipped) — persisted Work-owned scene/beat carrier (DR-26 / `DF-V1123-MOMENT-WIRE`).** V1.200 replaces the deferred/fixtures-only Moment carrier with persisted Work-owned `WorkOutline.scenes[]` / `beats[]` (`{scene_id, chapter_id, title, status}` / `{beat_id, scene_id, title, status}`), read through the existing `GET /v1/daemon/works/{work_id}/outline` boundary and authored through four additive `outline.patch_structure` operations (`add_scene` / `remove_scene` / `add_beat` / `remove_beat` — see §3.5). This section's Layer composition and both surfaces' **Carrier contract** rows below are amended accordingly: the Work Timeline Moment layer projects its own `WorkOutline` carrier; the World Timeline Moment layer projects the composed bound-Work carrier (each entry tagged with its owning Work — chapter numbers are Work-local, so two Works that each own a chapter 1 stay distinct). Ownership is unchanged: **Outline remains the single authoring home; both Timeline Moment layers stay read-only projections; no World KB entity or storage change is introduced; scenes/beats are never fabricated** — an empty canonical array is real emptiness. Default layers are unchanged (World: Brief-if-`era`-data-else-Narrative; Work: Narrative). Coordinate [entity-scope-model.md](../architecture/entity-scope-model.md) §1.4. **V1.200 is a wire change** (`wire_contracts_changed: true` — schema + codegen + Rust core + napi + service translation), which is why the V1.156 "frontend-only" verification paragraphs below are now explicitly version-scoped to V1.156. > > **V1.200 amendment (shipped) — Outline World-event binding authoring (DR-26 / `DF-V1123-CROSS-SURFACE-BINDING` write half; plan `002-cross-surface-binding-write.md`).** The V1.163 read carrier gains its first-party write path. `timeline.patch_event` gains two **additive** operations — `bind_world_event` / `unbind_world_event` — on the **existing** `POST /v1/daemon/works/{work_id}/timeline/patch` route (`TimelinePatchEventRequest` / `OutlinePatchResponse`, new optional `world_event_id` member; `additionalProperties: false` preserved, one `outline_revision` bump per accepted mutation). Authoring lives on the **Outline** surface (`apps/web` outline Timeline event inspector: each row shows the projected binding and offers bind/unbind); the projected Work/World Timeline inspectors stay read-only. **This supersedes AC-V1163-7's no-author-write scope**; everything else the V1.163 amendment locked is preserved — the KB `key_block_id` referent (`block_type=event`, never `narrative_timeline_events.id`), PD-5's three-state navigation, the N=20 reverse fan-out, and read-only navigation behavior (both CTAs still navigate and never patch). > @@ -466,7 +466,7 @@ V1.123 P1 + P2 add the frontend `CanvasSurfaceKind = "work-timeline"` enum value | **Adapter extension** | `createTimelineCanvasAdapter(ctxRef, 'brief')` projection gains relationship-awareness. The context/fetch shape is **unchanged** (no new query, no new DTO on the context). Era nodes (`timeline-brief-era`) gain two derived UI fields: `depth` (0 for roots, 1+ for children — drives indentation) and `parentKeyBlockId` (drives the nesting edge). These are UI-only derived fields, not wire DTO additions. | | **Type coloring** | Per-`era_type` color via **DESIGN.md tokens** (not inline hex). A `--color-era-type-*` token family (or a hue ramp off the existing `--color-canvas-layer-brief-accent` spine) distinguishes the recommended types (`kingdom` / `age` / `epoch` / `period` / `sub-age`). **Unknown or absent `era_type` falls back to the default Brief accent** (`--color-canvas-layer-brief-accent`, gold-bronze) — legacy V1.123 flat-era data renders compatibly. Token values + dark-theme parity (`DESIGN.md` + `DESIGN.dark.md`) land in P1 implementation with architect sign-off. | | **Read-only rendering** | The Brief-layer time band is a **read-only** rendering of the era tree. Selection may highlight a band and its descendants; cross-layer drill (Brief → Narrative) filters Narrative events within the selected era's `start_hint`/`end_hint` (V1.123 cross-layer rule preserved). No inline drag-to-reparent in the Brief layer (Non-Goal). | -| **Create entry** | A **"新建 era" / "+ New era"** affordance in the Brief-layer header chrome (sibling to the layer switcher tabs). On click: opens a create dialog that calls `kb.patch_entity` (V1.73, **create-on-absent** — client-minted `entity_id` (`kb_<32-hex>`) + `expected_version: 0` + absent row; see [`entity-scope-model.md`](entity-scope-model.md) §5.1.2 for the normative branching contract) with `block_type: "era"` and optional `body.attributes.era_type`, plus an **optional parent-era picker** (when a parent is chosen, the dialog also calls `kb.relate` / `kb.patch_relationship` with `relation_type: "custom"`, `custom_label: "parent_era"`, `source = parent`, `target = new era`). After creation, the graph refetch reflows the tree. **No Brief-layer inline drag-to-nest** — era-era parent edges are set via the create/edit dialog's parent picker or via the World KB relationships surface (PD-5). | +| **Create entry** | A **"新建 era" / "+ New era"** affordance in the Brief-layer header chrome (sibling to the layer switcher tabs). On click: opens a create dialog that calls `kb.patch_entity` (V1.73, **create-on-absent** — client-minted `entity_id` (`kb_<32-hex>`) + `expected_version: 0` + absent row; see [`entity-scope-model.md`](../architecture/entity-scope-model.md) §5.1.2 for the normative branching contract) with `block_type: "era"` and optional `body.attributes.era_type`, plus an **optional parent-era picker** (when a parent is chosen, the dialog also calls `kb.relate` / `kb.patch_relationship` with `relation_type: "custom"`, `custom_label: "parent_era"`, `source = parent`, `target = new era`). After creation, the graph refetch reflows the tree. **No Brief-layer inline drag-to-nest** — era-era parent edges are set via the create/edit dialog's parent picker or via the World KB relationships surface (PD-5). | | **Write boundary** | Unchanged from V1.123 + V1.74/V1.144: era entity edits via `POST /v1/daemon/worlds/{world_id}/kb/patch-entity` (`kb.patch_entity`, V1.73); era-era nesting via `kb.relate` (V1.144 spoke `RelationPort`, `relation_type: "custom"` + `label: "parent_era"`) or `POST /v1/daemon/worlds/{world_id}/kb/patch-relationship` (`kb.patch_relationship`, V1.74, `relation_type: "custom"` + `custom_label: "parent_era"`). No new write route. | | **Conflict policy** | Reuses V1.73 `WorldKbConflictError` (409, entity OCC on `revision`) + V1.144 `RelationAlreadyExists`/`RelationNotFound` (relationship OCC on `revision`). No new conflict DTO. | | **Empty-state honesty** | Extends the V1.123/V1.156 Brief empty-state: no era entities → honest empty-state (unchanged). Eras present but **no nesting edges and/or no `era_type`** → compatible flat rendering (all roots at depth 0, default color) — the V1.159 rendering MUST NOT fabricate nesting from `canonical_name`/`start_hint` ordering; nesting comes **only** from `parent_era` relationship edges. | @@ -620,7 +620,7 @@ TipTap remains useful as an in-node editor for prompt snippets, outline fragment ### 3.6 Canvas → DESIGN.md token contract (B4) -V1.69 freezes the minimal credible token names that V1.70 canvas implementation will need. Repo-root [`DESIGN.md`](../../DESIGN.md) + [`DESIGN.dark.md`](../../DESIGN.dark.md) stub these as commented LEVEL placeholders (formerly under `apps/web/` pre-V1.98); V1.70 assigns concrete values when implementing the canvas. +V1.69 freezes the minimal credible token names that V1.70 canvas implementation will need. Repo-root [`DESIGN.md`](../../../DESIGN.md) + [`DESIGN.dark.md`](../../../DESIGN.dark.md) stub these as commented LEVEL placeholders (formerly under `apps/web/` pre-V1.98); V1.70 assigns concrete values when implementing the canvas. | Token | Intent | | --- | --- | diff --git a/.mstar/specs/design-studio.md b/.mstar/specs/surfaces/design-studio.md similarity index 99% rename from .mstar/specs/design-studio.md rename to .mstar/specs/surfaces/design-studio.md index ed4623f66..9d9a77e60 100644 --- a/.mstar/specs/design-studio.md +++ b/.mstar/specs/surfaces/design-studio.md @@ -7,11 +7,11 @@ **Scope**: `apps/design-studio` — read-only gallery and visual proving ground for the Nexus DESIGN SSOT, brand VI, shared presentational primitives, and representative surface fixtures **Coordinates with**: -- Repo-root [`DESIGN.md`](../../DESIGN.md) + [`DESIGN.dark.md`](../../DESIGN.dark.md) — sole token SSOT +- Repo-root [`DESIGN.md`](../../../DESIGN.md) + [`DESIGN.dark.md`](../../../DESIGN.dark.md) — sole token SSOT - [`web-ui.md`](web-ui.md) §30 — Studio is contributor tooling, not a Control Room feature - `@42ch/nexus-ui` — brand layer plus approved presentational primitives (public exports only) -- Root [`AGENTS.md`](../../AGENTS.md) UI Component Policy (Studio-first) -- [`apps/design-studio/AGENTS.md`](../../apps/design-studio/AGENTS.md) — import guardrails +- Root [`AGENTS.md`](../../../AGENTS.md) UI Component Policy (Studio-first) +- [`apps/design-studio/AGENTS.md`](../../../apps/design-studio/AGENTS.md) — import guardrails Iteration history that used to live in this file (V1.98–V1.107 task tables, superseded process notes) is **not** current promise. See §12. diff --git a/.mstar/specs/desktop-shell.md b/.mstar/specs/surfaces/desktop-shell.md similarity index 98% rename from .mstar/specs/desktop-shell.md rename to .mstar/specs/surfaces/desktop-shell.md index ceb29c188..0a6c446fa 100644 --- a/.mstar/specs/desktop-shell.md +++ b/.mstar/specs/surfaces/desktop-shell.md @@ -2,7 +2,7 @@ **Classification:** Master. **Status:** Electron is the shipped desktop host: the v1.192 cutover (RFT-09) is accepted, unsigned packaging is delivered (RFT-10), and the replaced Tauri composition is retired (RFT-11), leaving exactly one desktop host. This is **not a claim that dual-architecture GUI qualification, Gatekeeper trust or installed-deployment behavior has been verified** — those rows remain **[UNVERIFIED]** (§12). This in-place revision replaces Tauri-specific normative hosting, preserves the shipped setup/product behavior, and leaves historical evidence unchanged. -Architecture authority: [rust-core-service-boundary.md](rust-core-service-boundary.md) §§5,7–12,16. This Master owns desktop capability, window/setup, IPC and packaging contracts; service/domain HTTP schemas remain schema-owned. No second desktop UI or competing desktop spec is introduced. +Architecture authority: [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §§5,7–12,16. This Master owns desktop capability, window/setup, IPC and packaging contracts; service/domain HTTP schemas remain schema-owned. No second desktop UI or competing desktop spec is introduced. ## 1. Product and cohort @@ -16,7 +16,7 @@ Bundle id `io.nexus42.desktop`; product/app name `Nexus`. Product version comes - Preload exposes only `window.nexusDesktop` version1. Renderer remains sandboxed, context-isolated, Node-disabled, web-security-enabled and never loads `.node`, native handles, Principal claims or persisted secrets. A path shown in UI is not path authority. - An Electron utility process hosts `@42ch/nexus-service`; the service calls the Rust/native authority. No separate proof `openCore` owner exists beside the service. Service code never imports Electron. - A utility process is app-lifetime-bound. Only independent TS-service composition may outlive the GUI; attach and keep/quit are defined in §7. -- The Tauri product tree/toolchain/CI retirement landed in v1.192, after accepted host parity and unsigned packaging. **Delivered (v1.193 P2):** the integrated legacy daemon + embedded SPA composition and the dormant CLI rows were retired in that iteration — the whole `nexus42 daemon` group, hidden `daemon-run`, the `web-embed` SPA bytes and the thin `DaemonClient` leaves are deleted, with no replacement service launcher. **No public operator name survives:** the desktop host and the standalone TS service own the service lifecycle, and the CLI is a one-shot direct-core/cloud/Connect product ([rust-core-service-boundary.md](rust-core-service-boundary.md) §7.2, [cli-spec.md](cli-spec.md) §6.3). +- The Tauri product tree/toolchain/CI retirement landed in v1.192, after accepted host parity and unsigned packaging. **Delivered (v1.193 P2):** the integrated legacy daemon + embedded SPA composition and the dormant CLI rows were retired in that iteration — the whole `nexus42 daemon` group, hidden `daemon-run`, the `web-embed` SPA bytes and the thin `DaemonClient` leaves are deleted, with no replacement service launcher. **No public operator name survives:** the desktop host and the standalone TS service own the service lifecycle, and the CLI is a one-shot direct-core/cloud/Connect product ([rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) §7.2, [cli-spec.md](../cli/cli-spec.md) §6.3). ## 3. Public entries and resources diff --git a/.mstar/specs/web-ui-design-requirements.md b/.mstar/specs/surfaces/web-ui-design-requirements.md similarity index 97% rename from .mstar/specs/web-ui-design-requirements.md rename to .mstar/specs/surfaces/web-ui-design-requirements.md index 4fcdb9786..ee4c655d5 100644 --- a/.mstar/specs/web-ui-design-requirements.md +++ b/.mstar/specs/surfaces/web-ui-design-requirements.md @@ -1,8 +1,9 @@ # Web UI — Design Requirements (input brief for repo-root `DESIGN.md`) **Status**: Input brief (Prepare Phase 2b) — **not** the DESIGN.md itself +**Document class**: Companion **Author**: `@product-manager` -**Consumer**: `@architect` (authors repo-root [`DESIGN.md`](../../DESIGN.md), the design-token SSOT; completeness level **Standard** per compass §5 item #6) *(V1.98: sole SSOT — former `apps/web/DESIGN*.md` retired)* +**Consumer**: `@architect` (authors repo-root [`DESIGN.md`](../../../DESIGN.md), the design-token SSOT; completeness level **Standard** per compass §5 item #6) *(V1.98: sole SSOT — former `apps/web/DESIGN*.md` retired)* **Iteration**: V1.64 (V1.65 authoring-surface amendment appended in §5) **Drives**: [web-ui.md](web-ui.md) §6 (MVP surface) — the screens whose look/feel this brief constrains @@ -32,7 +33,7 @@ The primary user is a **writer, not an engineer**. They chose Nexus to write, no ## 3. Brand voice and content -The UI copy must be **consistent with the existing CLI voice** (see [cli-spec.md](cli-spec.md) §7.1 UX principles — "本地助手" framing, actionable next-steps over raw error text). Concretely: +The UI copy must be **consistent with the existing CLI voice** (see [cli-spec.md](../cli/cli-spec.md) §7.1 UX principles — "本地助手" framing, actionable next-steps over raw error text). Concretely: - **Tone**: helpful, plain, action-oriented. Errors give a one-line next step, never just a code. - **Vocabulary**: reuse CLI terms authors already know (Work, preset, stage, finding, capability). Do **not** invent UI-only synonyms. @@ -92,7 +93,7 @@ All three V1.65 component classes — editor, table, context menu — must ship ## What this brief deliberately does NOT decide -- Token values (colors, type scale, spacing, radii, elevation, motion durations) → repo-root [`DESIGN.md`](../../DESIGN.md) (`@architect`). +- Token values (colors, type scale, spacing, radii, elevation, motion durations) → repo-root [`DESIGN.md`](../../../DESIGN.md) (`@architect`). - Component inventory beyond "strong tables + strong forms + status/severity primitives + loading/empty/error states" (V1.64) plus the V1.65 "editor + structure table + read-only context menu" increment (§5) → repo-root `DESIGN.md`. - Completeness level beyond **Standard** for V1.64 + **Standard+ increment** for V1.65 authoring components (Production-level polish/animations are V1.66, compass §5 item #6/#7). diff --git a/.mstar/specs/web-ui.md b/.mstar/specs/surfaces/web-ui.md similarity index 95% rename from .mstar/specs/web-ui.md rename to .mstar/specs/surfaces/web-ui.md index fc87f4eff..ddec00a92 100644 --- a/.mstar/specs/web-ui.md +++ b/.mstar/specs/surfaces/web-ui.md @@ -3,22 +3,31 @@ **Status**: Shipped (V1.65) — Control Room + Setup MVP (V1.64) **+ Content-Authoring UI stage (V1.65, §13)**: outline rich-text editor + chapter structure table + structure CRUD (slug/wc/volume/status; title display-only) + body read-only render + browser "Copy path" context menu. Tauri desktop shell + body full-text editor + "open-with" → **V1.66** (compass §0 Q5). QC tri-review Approve (fix-wave-1) + QA Pass. **+ V1.67 Surface Convergence & De-risk (§15)** + **V1.69 Design System Maturation & Canvas Draft** (`apps/web/DESIGN.md` Production + Canvas Draft) + **V1.70 Canvas Strategy Implement α (§16)** + **CI/desktop-build optimization** (parallel ops track; PR path filter narrowed + release-gated full build) + **V1.71 Canvas Strategy Write-Boundary (§17)** (Strategy patch routes, graphRevision conflict policy, conflict modal UX, canvas-write tokens) + **V1.72 Canvas Outline+Timeline β (§18)** (3 outline/timeline patch routes `outline.patch_structure` / `outline.patch_chapter` / `timeline.patch_event` + outlineRevision conflict policy + outline-flavored conflict modal UX + non-spatial alternate views + 8 outline/timeline canvas-write DESIGN.md tokens). V1.71 `wire_contracts_changed: TRUE` for Strategy; V1.72 `wire_contracts_changed: TRUE` for additive Outline+Timeline (`@42ch/nexus-contracts` 0.7.0 → 0.8.0); V1.73 `wire_contracts_changed: TRUE` for additive World KB (`@42ch/nexus-contracts` 0.8.0 → 0.9.0). **V1.74 Shipped** — Canvas World KB Relationships β (§20) with typed relationship edges, `world_kb.patch_relationship`, relationship inspector, non-spatial relationship table, and KB-flavored conflict modal reuse. **V1.94 Draft amendment** — §29 Information Architecture (V1.94): two-tab sidebar, nested nav, footer Profiles switcher, daemon status bar simplification, Strategies unification, button contrast invariant. **V1.98 Draft amendment** — §30 Design Studio dev surface (auxiliary gallery app; not author-facing). **V1.118 Draft amendment** — §29.17 Creation peer groups (Works / Worlds / Memories) + Canvas-first work shell (`WorkShellLayout` + `WorkRail`). **V1.125 Draft amendment** — §29.17.4 Worlds-first Creator list-mode sidebar (supersedes §29.17.1 peer groups only). **V1.122 Draft amendment** — §29.18 Three-pillar pivot (Harness/Canvas/Computable) + Timeline-first Canvas IA: Timeline is the default surface for **World entry** (`/worlds/:worldId` → Timeline); Work entry stays Outline (V1.118); `CanvasSurfaceKind = "timeline"` added as a peer surface. `wire_contracts_changed: false`. **V1.147/V1.156** (§29.18.2 pillar framing): Computable pillar fronted — V1.147 Run Studio on Modules + compute-on-Timeline Accept-landed nodes; V1.156 P3 Harness pillar-entry rename (user-visible copy only; internal identifiers unchanged). **V1.157** (§3 stack): React 19 upgrade. **V1.170 P1** (§29.2/§29.13, AR-15/AR-17): Entrance axis + Entrance-first setup step (Create/Develop layout trees). **Document class**: Feature line **Created**: 2026-06-24 -**Scope**: Nexus local Web UI product contract — placement (`apps/web`), stack, daemon-served model, `tauri-api` adapter boundary, MVP surface (Control Room + Setup), Content-Authoring stage (V1.65), Tauri / body-editor roadmap (V1.66), and strict separation from the private cloud SaaS +**Scope**: Nexus local Web SPA (`apps/web`), its `NexusClient` transport boundary and standalone TypeScript HTTP service (`apps/nexus-service`) under Electron lifecycle ownership; Control Room, Setup and content-authoring product stages; strict separation from the private cloud SaaS. -> **Desktop host note (v1.192, RFT-11):** the Tauri desktop host was retired; the repository has exactly one desktop host — Electron, contract [desktop-shell.md](desktop-shell.md). Tauri-era names below (`tauri-api`, `TauriClient`, `apps/desktop`, the V1.66 shell stage) are historical records of what shipped at that time, kept for traceability. The daemon-served browser SPA model (§§4, 11) is unchanged: the integrated daemon and its embedded SPA still ship. +> **Current host boundary (v1.193 P2; reconciled 2026-09-29):** Electron is the sole desktop host ([desktop-shell.md](desktop-shell.md)); Tauri was retired in v1.192. The integrated daemon, `nexus-daemon-runtime`, `nexus42 daemon` command group and `web-embed` were deleted in v1.193 P2. The standalone `apps/web` SPA uses `apps/nexus-service` for `/v1/daemon/*`; that retained URL prefix does not imply a Rust daemon host. Tauri/daemon-era shipping stages below are historical records, not current host or packaging requirements. **Coordinates with**: -- [cli-spec.md](cli-spec.md) §6.3 (daemon command group — Web UI access) + §7.1 (first-run path) -- [daemon-runtime.md](daemon-runtime.md) §2 (normative layering) — static-asset serving on the axum router -- [schemas-external-consumer-boundary.md](schemas-external-consumer-boundary.md) — the bundled UI is a first-class external consumer of `@42ch/nexus-contracts` -- [local-cloud-crate-architecture.md](local-cloud-crate-architecture.md) §1 — strict local-product vs cloud-product separation -- Repo-root [`DESIGN.md`](../../DESIGN.md) + [`DESIGN.dark.md`](../../DESIGN.dark.md) — sole normative DESIGN pair *(V1.98: supersedes former `apps/web/DESIGN*.md` — see §30)* -- [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) (NEW, `@architect`-authored Master) — cursor pagination / `ErrorResponse` / naming conventions the UI data layer relies on +- [cli-spec.md](../cli/cli-spec.md) — current CLI contract; its former daemon Web UI launcher is historical +- [rust-core-service-boundary.md](../architecture/rust-core-service-boundary.md) — current core / TS service boundary; [daemon-runtime.md](../archived/daemon-runtime.md) retains the retired axum/static-asset topology +- [schemas-external-consumer-boundary.md](../architecture/schemas-external-consumer-boundary.md) — the bundled UI is a first-class external consumer of `@42ch/nexus-contracts` +- [local-cloud-crate-architecture.md](../archived/local-cloud-crate-architecture.md) §1 — strict local-product vs cloud-product separation +- Repo-root [`DESIGN.md`](../../../DESIGN.md) + [`DESIGN.dark.md`](../../../DESIGN.dark.md) — sole normative DESIGN pair *(V1.98: supersedes former `apps/web/DESIGN*.md` — see §30)* +- [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md) (NEW, `@architect`-authored Master) — cursor pagination / `ErrorResponse` / naming conventions the UI data layer relies on --- -## 1. Purpose +## 0. Current architecture + +`apps/web` is a standalone SPA, not a Rust-embedded asset feature. In the desktop product, Electron loads the built web assets through `nexus://app/index.html` and owns the local service lifecycle through `DesktopServiceController`. The standalone TS service opens the native core and serves the retained `/v1/daemon/*` HTTP surface. Browser development/preview runs the SPA separately with a proxy to that service. + +Code anchors: [`apps/desktop-electron/src/main.ts`](../../../apps/desktop-electron/src/main.ts) (web protocol, `DesktopServiceController`, standalone service entry), [`apps/nexus-service/src/index.ts`](../../../apps/nexus-service/src/index.ts) (`startService`), [`apps/nexus-service/src/routes.ts`](../../../apps/nexus-service/src/routes.ts), and [`apps/web/vite.config.ts`](../../../apps/web/vite.config.ts) (dev/preview proxy). §§1, 4.1–4.3, 11–14 retain their shipped-era context where they describe the deleted daemon or Tauri; this section and §4's current boundary supersede those hosting claims. + +--- + + +## 1. Purpose (historical V1.64 introduction) Through V1.63 the local-first runtime is **feature-complete for writing but only reachable from the terminal**. Every operational action — see my Works, watch an orchestration session, inspect findings, configure a preset, start a Work — requires remembering `nexus42` commands. @@ -39,7 +48,7 @@ The local Web UI lives in **this OSS repository** at `apps/web/` (a pnpm workspa Rationale (frozen, compass §0 Q2): -1. **Build coupling.** The release build embeds the SPA bundle into the `nexus42` binary via `rust-embed`. The OSS binary build must not depend on a private repo's build graph; otherwise the public binary cannot be reproduced from the public repo. +1. **Build coupling (historical V1.64 rationale).** The release build then embedded the SPA bundle into the `nexus42` binary via `rust-embed`. That packaging was retired in v1.193 P2; the public SPA, Electron host and TS service still build within this OSS repository without the private repo's build graph. 2. **Type coupling.** The UI consumes `@42ch/nexus-contracts` via `workspace:*` so there is zero cross-repo version lag between wire schemas and the UI types. A private-repo placement would reintroduce npm-semver drift that V1.63's codegen promotion was meant to eliminate. 3. **Audience coupling.** This UI is a *local-first* surface for the local product line; it shares nothing with the cloud SaaS deployment model. @@ -49,10 +58,10 @@ This is a **different product** from any web UI in the private `nexus-platform`: | Dimension | Local Web UI (this spec, OSS) | Cloud SaaS (private `nexus-platform`) | | --- | --- | --- | -| Deployment | bundled into the local `nexus42` binary; served from `localhost` | hosted multi-tenant cloud | +| Deployment | standalone `apps/web` SPA; Electron packages the web assets and owns the local TS service lifecycle | hosted multi-tenant cloud | | Data source | local `state.db` + reference store via loopback Daemon API | platform HTTP / cloud DB | | Audience | a single author on their own machine | platform tenants / cloud users | -| Auth | loopback only (keyless on `localhost`; see §4.2) | platform auth / sessions | +| Auth | local service / desktop transport policy; §4.2 records the historical loopback model | platform auth / sessions | | Roadmap home | this spec + `apps/web/` | `nexus-platform` `v1-spec/` | **Invariant:** no cloud-product feature, platform auth flow, or platform-gated capability (DF-13/16/55/59; PD-05) is exposed in this UI while `platform_integration = paused`. The UI surfaces only the local product line. Cross-repo contract sharing is one-way: this repo's `schemas/` → `nexus-contracts`; the UI never imports platform-only types. @@ -64,7 +73,7 @@ This is a **different product** from any web UI in the private `nexus-platform`: | Layer | Choice | Why | | --- | --- | --- | | Framework | **React 19** (V1.157 upgrade from 18.3) | largest ecosystem; mental-model consistency with the existing `@42ch/nexus-contracts` TS consumer surface | -| Build / dev server | **Vite** (SPA) | matches "single-binary local-first"; no Node runtime required in the shipped product (build-time only) | +| Build / dev server | **Vite** (SPA) | builds standalone web assets; dev/preview proxies the local TS service | | Language | **TypeScript** (strict) | non-negotiable; the whole point of V1.63 codegen is end-to-end type safety | | Styling | **TailwindCSS** | utility-first, low design-debt, pairs with the component layer | | Component primitives | **shadcn/ui** | copy-in components keep ownership inside the repo; no opaque runtime dependency | @@ -78,22 +87,26 @@ This stack is the **desktop-ready** foundation: it introduces no browser-only AP ## 4. Serving and access model -### 4.1 Two serving modes +**Current (v1.193 P2):** the SPA and HTTP service are separate surfaces. Electron serves packaged web assets and owns `apps/nexus-service` startup/stop/handoff; the TS service, not `nexus42`, serves `/v1/daemon/*`. Dev/preview Vite proxies that prefix to the configured service endpoint. There is no current integrated-daemon or `web-embed` release mode; see §0 for source anchors and [desktop-shell.md](desktop-shell.md) for lifecycle policy. + +The following V1.64 subsections preserve the original serving/access design for traceability; they do not prescribe today's host, auth configuration, or CLI launch path. + +### 4.1 Two serving modes (historical V1.64) - **Release** — the built `apps/web/dist` is embedded into the `nexus42` binary via **`rust-embed`** and exposed by the daemon router through **`tower-http::ServeDir`-style** static serving semantics at the server root (`/`). The same binary that runs the runtime serves the UI. (Embedding strategy is finalized in plan P3; `serve-from-disk` under `~/.nexus42/web/` is the fallback only if embedding creates release-pipeline friction.) - **Dev** — `apps/web` runs the **Vite dev server**, which proxies `/v1/daemon/*` to the running daemon (`nexus42 daemon start`). No embedding in dev; hot reload against the live Daemon API. The static shell (HTML/JS/CSS assets) is **unauthenticated** by design: it carries no data. All data flows through the Daemon API. -### 4.2 Auth model (unchanged from the daemon) +### 4.2 Auth model (historical daemon boundary) The Web UI introduces **no new auth surface**. It inherits the daemon's existing loopback model (V1.20 compass): Daemon API data endpoints are reachable on `localhost` and are **keyless on loopback**; the static shell needs no credential because it holds no data. The UI does not add login, sessions, or tokens. Any future remote (non-loopback) access is explicitly opt-in (§8) and would require both `NEXUS42_DAEMON_API_KEY` and `NEXUS_DAEMON_REMOTE_BIND=1`; loopback remains the default. > Implementation note for `daemon-api-surface-conventions.md`: the shared `ErrorResponse` (F-E1) is what the UI's toast/notification layer parses; the UI must never have to special-case per-handler error shapes. -### 4.3 CLI entry +### 4.3 CLI entry (historical; retired) -See §11 and the [cli-spec.md](cli-spec.md) §6.3 amendment (proposed by this iteration): `nexus42 daemon start` serves the UI and logs its URL; an optional `nexus42 ui` convenience command may start the daemon (if not running) and open the OS browser. Final shape is a PM + architect decision; the spec records the chosen shape at P-last. +See §11 and the [cli-spec.md](../cli/cli-spec.md) §6.3 amendment (proposed by this iteration): `nexus42 daemon start` serves the UI and logs its URL; an optional `nexus42 ui` convenience command may start the daemon (if not running) and open the OS browser. Final shape is a PM + architect decision; the spec records the chosen shape at P-last. --- @@ -227,14 +240,14 @@ Versioning, npm/Rust bumps, and the single breaking shape change (Works list) ar --- -## 11. CLI entry (summary; detail in cli-spec.md §6.3 amendment) +## 11. CLI entry (historical daemon-era summary; retired v1.193 P2) - `nexus42 daemon start` serves the UI at `http://localhost:/` and **logs that URL** on startup. - An optional `nexus42 ui` (alias `nexus42 web`) convenience command starts the daemon if not running and opens the OS browser. Whether it ships in V1.64 (P3) or is deferred is a PM decision grounded in cost; the spec records the outcome at P-last. --- -## 12. Acceptance (spec-level) +## 12. Acceptance (historical V1.64 spec-level criteria) 1. The UI is served from the `nexus42` binary (release) with no Node runtime requirement, and from the Vite dev server (dev) proxying `/v1/daemon/*`. 2. All seven MVP screen groups render and operate against the hardened Daemon API; no screen calls a transport directly (all via `NexusClient`). @@ -256,7 +269,7 @@ V1.64 made the runtime **legible and configurable** (Control Room + Setup). V1.6 ### 13.1 What ships in V1.65 (Track A lead slice) -The browser SPA gains an authoring surface layered on the V1.64 Control Room + Setup screens. All new screens route through the same `NexusClient` interface (§5) and consume the new V1.65 chapter-content Daemon API (Track B / P0 backend; conventions in [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md)). +The browser SPA gains an authoring surface layered on the V1.64 Control Room + Setup screens. All new screens route through the same `NexusClient` interface (§5) and consume the new V1.65 chapter-content Daemon API (Track B / P0 backend; conventions in [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md)). - **Chapter structure table** (per-Work, multi-Work switcher reusing the V1.64 Works dashboard entry): columns — chapter #, title (**display-only** — derived from outline frontmatter or slug/chapter# fallback; no `title` column exists in `work_chapters` in V1.65), slug, planned word count, volume, status (`not_started` / `outlined` / `draft` / `finalized` / `published`), actual word count. Sortable by chapter #. - **Outline rich-text editor**: edit a chapter's `outline_path` markdown in a rich-text editor; save writes the file atomically (reuse the reconcile atomic-write pattern) and updates DB metadata (`outline_path`, `updated_at`) in the same transaction. Restricted to a markdown subset (headings, lists, bold/italic, code, blockquote, links). @@ -294,7 +307,7 @@ Explicitly deferred with rationale (compass §0 Q2/Q4/Q5, §1.2; satisfies the D ### 13.5 Wire contracts (V1.65) -The authoring surface consumes new chapter-content schemas (additive, owned by Track B / P0; conventions in [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md)): chapter list (cursor + `items`) / detail / outline GET+PUT (atomic write) / structure PATCH (status progression) / body GET (read-only), plus `work_profile` on Work requests and full preset CRUD routes. Versioning, npm/Rust bumps, and per-DTO `schema_version` increments are owned by compass §1.3. +The authoring surface consumes new chapter-content schemas (additive, owned by Track B / P0; conventions in [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md)): chapter list (cursor + `items`) / detail / outline GET+PUT (atomic write) / structure PATCH (status progression) / body GET (read-only), plus `work_profile` on Work requests and full preset CRUD routes. Versioning, npm/Rust bumps, and per-DTO `schema_version` increments are owned by compass §1.3. --- @@ -302,7 +315,7 @@ The authoring surface consumes new chapter-content schemas (additive, owned by T --- -## 14. Next stage — Desktop Shell (V1.66 lead slice) +## 14. Next stage — Desktop Shell (historical V1.66 Tauri lead slice) V1.65 made the UI an **authoring entry surface** in the browser. V1.66 takes Nexus from **"open a browser tab to `localhost:8420`"** to a **double-clickable macOS desktop application**. The browser SPA transport stays **unchanged** (screen data access remains transport-agnostic); a new `apps/desktop` Tauri v2 wrapper loads the `apps/web` dist, the `TauriClient` impl of `NexusClient` swaps in, and the bundled `nexus42` daemon comes up transparently on launch. This is the gating prerequisite for everything desktop-native in the roadmap (signing, multi-OS, auto-update, mobile). @@ -477,7 +490,7 @@ Explicitly deferred with rationale (compass §1.2; satisfies the Durable Roadmap V1.70 made the Strategy canvas legible and steerable. V1.71 makes the **Strategy surface editable at node granularity** while preserving the core boundary: the browser/Tauri webview never writes raw files. All Strategy edits flow through schema-backed Daemon API patch routes, daemon validation, atomic persistence, and graphRevision conflict handling. -> **Scope and roadmap SSOT**: §1.1 Track A (A1–A9), §1.3 wire contracts, §2 normative specs, and §6 risk notes. Architectural detail: [canvas-strategy-surface.md](canvas-strategy-surface.md) (V1.71 Shipped β) and [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) §7 patch-route pattern. +> **Scope and roadmap SSOT**: §1.1 Track A (A1–A9), §1.3 wire contracts, §2 normative specs, and §6 risk notes. Architectural detail: [canvas-strategy-surface.md](canvas-strategy-surface.md) (V1.71 Shipped β) and [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md) §7 patch-route pattern. ### 17.1 What ships in V1.71 (Track A — Strategy β writes) @@ -595,7 +608,7 @@ V1.72 shipped the Outline+Timeline canvas. V1.73 completes the Canvas program's V1.74 completes the World KB canvas surface by promoting first-class typed relationships from the V1.73 deferred slot into a shipped authoring surface. The relationship route is reachable from both the canvas graph and the complete non-spatial relationship view; both entry points call the same Daemon API contract and preserve the §5 `NexusClient` boundary. -> **Scope and roadmap SSOT**: §0 grill decisions, §1.1 Track A, §1.3 wire contracts, and §2 normative specs. Architectural detail: [canvas-strategy-surface.md](canvas-strategy-surface.md) (V1.74 Shipped β), [entity-scope-model.md](entity-scope-model.md) §5.6, and [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) §7.6. +> **Scope and roadmap SSOT**: §0 grill decisions, §1.1 Track A, §1.3 wire contracts, and §2 normative specs. Architectural detail: [canvas-strategy-surface.md](canvas-strategy-surface.md) (V1.74 Shipped β), [entity-scope-model.md](../architecture/entity-scope-model.md) §5.6, and [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md) §7.6. ### 20.1 What ships in V1.74 (Track A — relationship β) @@ -633,7 +646,7 @@ V1.74 completes the World KB canvas surface by promoting first-class typed relat V1.76 shipped the World KB Relationship γ surface, completing the canvas program (V1.67–V1.76, 10 iterations). V1.77 pivots from the canvas to the **quality loop**: the Control-Room findings page — read-only since V1.64 — is promoted to a full **remediation authoring surface** that closes the "observe → triage → resolve" quality loop in the UI, exactly as the canvas closed the "steer → execute → review" writing loop. The backend already ships the full findings PATCH surface (6-state lifecycle adjacency enforcement, 7-field `UpdateFindingRequest` payload, full CRUD routes, stale-count endpoint); V1.77 consumes them from the web app with no new backend routes. -> **Scope and roadmap SSOT**: §0 grill decisions (Q1–Q4 locked), §1.1 Track A scope, §2 normative specs, §Phase 2b D4 (UX lock — authoritative), and §6 risk notes (all RESOLVED). This section records the product contract; the compass is authoritative for scope, batching, and residual tracking. Lifecycle detail: [findings-lifecycle.md](findings-lifecycle.md) (architect-drafted Master). API surface: [daemon-api-surface-conventions.md](daemon-api-surface-conventions.md) (findings PATCH reference). +> **Scope and roadmap SSOT**: §0 grill decisions (Q1–Q4 locked), §1.1 Track A scope, §2 normative specs, §Phase 2b D4 (UX lock — authoritative), and §6 risk notes (all RESOLVED). This section records the product contract; the compass is authoritative for scope, batching, and residual tracking. Lifecycle detail: [findings-lifecycle.md](../contracts/findings-lifecycle.md) (architect-drafted Master). API surface: [daemon-api-surface-conventions.md](../runtime/daemon-api-surface-conventions.md) (findings PATCH reference). ### 23.1 What ships in V1.77 @@ -1010,7 +1023,7 @@ When a highlight's stored offsets no longer fit the current body text (after a b Replace the V1.64 flat 10-item sidebar with a two-tab information architecture (Creator | Orchestrator) with nested nav, footer profile switcher, and simplified daemon status bar. The reshape addresses author-reported defects 3 (menu IA) and 4 (footer profiles) as one coherent IA pass. -**Entrance axis (V1.170 P1, AR-15):** the two-tab structure is a **separate axis** from the [Entrance](#entrance) (User-layer `developer` | `content-creator`). The sidebar renders entrance-filtered `navGroups` from `ENTRANCE_DESCRIPTORS[entrance]`; the Creator|Orchestrator tabs and `tabFromPathname` are untouched. **Create** (content-creator) is a *reduced* tree that hides the EL §3 operator chrome (agent catalog, preset manager, sessions, schedule, rules authoring, inspector, Connect, capability browser); **Develop** (developer) is the full Control Room plus the Develop hub v1 land route. `_system.*` presets stay hidden in both trees. Normative: `v1.170-entrance-locks.md` §2–§4. +**Entrance axis (V1.170 P1, AR-15):** the two-tab structure is a **separate axis** from the [Entrance](../../../CONCEPTS.md#entrance) (User-layer `developer` | `content-creator`). The sidebar renders entrance-filtered `navGroups` from `ENTRANCE_DESCRIPTORS[entrance]`; the Creator|Orchestrator tabs and `tabFromPathname` are untouched. **Create** (content-creator) is a *reduced* tree that hides the EL §3 operator chrome (agent catalog, preset manager, sessions, schedule, rules authoring, inspector, Connect, capability browser); **Develop** (developer) is the full Control Room plus the Develop hub v1 land route. `_system.*` presets stay hidden in both trees. Normative: `v1.170-entrance-locks.md` §2–§4. ### 29.2 Sidebar — two-tab structure @@ -1078,7 +1091,7 @@ The daemon status bar is desktop-only in the current build; it subscribes to the ### 29.7 Button contrast invariant -Recorded in repo-root [`DESIGN.md`](../../DESIGN.md) §Component Primitives/Button and [`DESIGN.dark.md`](../../DESIGN.dark.md): +Recorded in repo-root [`DESIGN.md`](../../../DESIGN.md) §Component Primitives/Button and [`DESIGN.dark.md`](../../../DESIGN.dark.md): > **Every button (or button-like element) with a dark, primary, or saturated background MUST use light/white text in both light and dark themes.** @@ -1261,7 +1274,7 @@ Bootstrap (`ensureSetupBootstrap`) on Workspace **Continue** only. #### 30.1 DESIGN SSOT move (web consumer) -- After V1.98 merge, **repo-root** [`DESIGN.md`](../../DESIGN.md) + [`DESIGN.dark.md`](../../DESIGN.dark.md) are the sole normative DESIGN pair. +- After V1.98 merge, **repo-root** [`DESIGN.md`](../../../DESIGN.md) + [`DESIGN.dark.md`](../../../DESIGN.dark.md) are the sole normative DESIGN pair. - Former `apps/web/DESIGN.md` and `apps/web/DESIGN.dark.md` are **deleted**; `src/index.css`, `tailwind.config.ts`, and AGENTS references consume the root SSOT via `@nexus/design-tokens`. - Token **names** preserved verbatim where possible to minimize CSS churn; value changes from merge audit are documented in `design-unification.md` §9. - `apps/web` behavior and author-visible UI remain the product contract in §§1–29; only the token **source path** changes. @@ -1284,7 +1297,7 @@ Bootstrap (`ensureSetupBootstrap`) on Workspace **Continue** only. #### 30.4 Contributor workflow (cross-reference) -Token tuning: edit repo-root [`DESIGN.md`](../../DESIGN.md) pair on disk → refresh design-studio → validate gallery → verify `apps/web` test/build. Full steps in [`design-studio.md`](design-studio.md) §4.2. +Token tuning: edit repo-root [`DESIGN.md`](../../../DESIGN.md) pair on disk → refresh design-studio → validate gallery → verify `apps/web` test/build. Full steps in [`design-studio.md`](design-studio.md) §4.2. #### 30.5 Non-goals @@ -1319,7 +1332,7 @@ Prefer `wire_contracts_changed: false`. Studio-first invariant locked for all au #### 29.14.5 Voice & Content — first-launch + daemon chrome (P0/P1 Must) -Normative copy lives in repo-root [`DESIGN.md`](../../DESIGN.md) (`### Launch & daemon status`, `### Done step copy`, `### States`). Iteration examples: +Normative copy lives in repo-root [`DESIGN.md`](../../../DESIGN.md) (`### Launch & daemon status`, `### Done step copy`, `### States`). Iteration examples: | Surface | Example copy | |---------|----------------| @@ -1443,6 +1456,8 @@ Outline and World KB are **not** Creation peer groups. Strategy remains under Or V1.122 inverts the **World-entry** default so an author meets a World's history first, not its entity graph. **Work entry is unchanged.** +**Current route clarification (2026-09-29):** [`apps/web/src/App.tsx`](../../../apps/web/src/App.tsx) explicitly nests an index `` under `worlds/:worldId`, alongside the `timeline` route rendering `TimelinePage`. Thus `/worlds/:worldId` redirects to `/worlds/:worldId/timeline`; the latter is also directly navigable. There is no World-detail-page index route. The Work Timeline remains a sibling of `outline`, not the Work index. + | Entry context | Route | Default surface (V1.122) | Prior default | | --- | --- | --- | --- | | **World entry** | `/worlds/:worldId` → **Timeline** (index redirect / `/timeline`); Worlds list pick-target updates | **Timeline (World-building hero)** | `/worlds/:worldId/kb` (World KB) | @@ -1452,13 +1467,13 @@ The Canvas shell now hosts **four** peer surfaces: Strategy / Outline (Timeline- #### 29.18.2 Pillar framing (P0) -The Web UI is the primary home of the **Canvas** pillar (spatial steering surface, with Timeline-centric World building as the hero). The **Harness** pillar (orchestration/agent host/capability registry) user-visible label **landed as "Harness" in V1.156 P3** (`DF-V1122-HARNESS-RENAME` closed; Preset stays as the mechanism name; internal identifiers unchanged — see V1.156 forward-pointer below). The **Computable** pillar (WASM reactivity) was backend-only in V1.122; compute-registry/canvas surfacing shipped in V1.147 (`DF-V1122-COMPUTABLE-UI`, `DF-V1122-COMPUTE-ON-TIMELINE` closed). Pillar definitions: [`STRATEGY.md`](../../STRATEGY.md) + [`CONCEPTS.md`](../../CONCEPTS.md). +The Web UI is the primary home of the **Canvas** pillar (spatial steering surface, with Timeline-centric World building as the hero). The **Harness** pillar (orchestration/agent host/capability registry) user-visible label **landed as "Harness" in V1.156 P3** (`DF-V1122-HARNESS-RENAME` closed; Preset stays as the mechanism name; internal identifiers unchanged — see V1.156 forward-pointer below). The **Computable** pillar (WASM reactivity) was backend-only in V1.122; compute-registry/canvas surfacing shipped in V1.147 (`DF-V1122-COMPUTABLE-UI`, `DF-V1122-COMPUTE-ON-TIMELINE` closed). Pillar definitions: [`STRATEGY.md`](../../../STRATEGY.md) + [`CONCEPTS.md`](../../../CONCEPTS.md). > **V1.147 forward-pointer:** the Computable pillar is no longer backend-only — > V1.147 shipped **Run Studio** on the Modules surface (`DF-V1122-COMPUTABLE-UI` > closed) and **compute-on-Timeline** entry with Accept-landed **Compute result** > nodes (`DF-V1122-COMPUTE-ON-TIMELINE` closed; both tracker rows archived). -> The direct lane routes: [`daemon-api-surface-conventions.md`](daemon-api-surface-conventions.md) §12.3. +> The direct lane routes: [`daemon-api-surface-conventions.md`](../runtime/daemon-api-surface-conventions.md) §12.3. > Product lock: `computable-author-behavior.md`. > **V1.156 forward-pointer:** the Harness pillar product rename **lands in V1.156 P3** > (the `DF-V1122-HARNESS-RENAME` tracker row closes at iteration-close). The user-visible pillar-entry label changes diff --git a/AGENTS.md b/AGENTS.md index fced1074d..5999dfbf0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,16 +50,23 @@ See linked AGENTS.md files for per-directory decision rules and invariants: | `tooling/` | Codegen pipeline & CI | [`tooling/AGENTS.md`](tooling/AGENTS.md) | | `tooling/design-tokens/` | Shared `@nexus/design-tokens` Tailwind preset + tokens.css | [`tooling/design-tokens/AGENTS.md`](tooling/design-tokens/AGENTS.md) | | `apps/nexus42/` | CLI executable (polyglot product-surfaces dir) | [`apps/nexus42/AGENTS.md`](apps/nexus42/AGENTS.md) | +| `apps/nexus-service/` | Standalone Node HTTP service over `@42ch/nexus-native` | [`apps/nexus-service/AGENTS.md`](apps/nexus-service/AGENTS.md) | | `apps/web/` | Web SPA — Control Room + canvas (React; served by the Electron/TS host) | [`apps/web/AGENTS.md`](apps/web/AGENTS.md) | | `apps/desktop-electron/` | Electron desktop host (unsigned macOS arm64 + x64) wrapping `apps/web` | [`apps/desktop-electron/AGENTS.md`](apps/desktop-electron/AGENTS.md) | | `apps/design-studio/` | Design-system gallery (daemon-independent Vite SPA) | [`apps/design-studio/AGENTS.md`](apps/design-studio/AGENTS.md) | | `crates/nexus-acp-host/` | ACP client adapter | [`crates/nexus-acp-host/AGENTS.md`](crates/nexus-acp-host/AGENTS.md) | | `crates/nexus-agent-host/` | Agent host adapter | [`crates/nexus-agent-host/AGENTS.md`](crates/nexus-agent-host/AGENTS.md) | | `crates/nexus-contracts/` | Generated Rust wire types | [`crates/nexus-contracts/AGENTS.md`](crates/nexus-contracts/AGENTS.md) | +| `crates/nexus-core/` | Transport-neutral World KB service + stored Actor/holder admission authority | [`crates/nexus-core/AGENTS.md`](crates/nexus-core/AGENTS.md) | +| `crates/nexus-core-node/` | Thin Node-API cdylib composing core + provider ports; audited FFI boundary | [`crates/nexus-core-node/AGENTS.md`](crates/nexus-core-node/AGENTS.md) | | `crates/nexus-embedding/` | Embedding readiness contract (RN-OGA-3) — provider trait seam, identity tuple, fail-closed derived-index protocol; no OSS execution | [`crates/nexus-embedding/AGENTS.md`](crates/nexus-embedding/AGENTS.md) | | `crates/nexus-home-layout/` | `~/.nexus42/` path layout | [`crates/nexus-home-layout/AGENTS.md`](crates/nexus-home-layout/AGENTS.md) | | `crates/nexus-local-db/` | Local database layer | [`crates/nexus-local-db/AGENTS.md`](crates/nexus-local-db/AGENTS.md) | | `crates/nexus-orchestration/` | Orchestration engine | [`crates/nexus-orchestration/AGENTS.md`](crates/nexus-orchestration/AGENTS.md) | +| `crates/nexus-preset/` | Pure preset authoring/source-file domain shared by core + orchestration | [`crates/nexus-preset/AGENTS.md`](crates/nexus-preset/AGENTS.md) | +| `crates/nexus-provider-conformance/` | Provider-neutral normalized `HostEvent` stream conformance; CI/test-only | [`crates/nexus-provider-conformance/AGENTS.md`](crates/nexus-provider-conformance/AGENTS.md) | +| `crates/nexus-provider-ports/` | Port-only `ProviderPort` / `ProviderResult` contracts; no provider implementation | [`crates/nexus-provider-ports/AGENTS.md`](crates/nexus-provider-ports/AGENTS.md) | +| `crates/nexus-storage-guard/` | Audited SQLite FFI for connection-local writer-protocol functions | [`crates/nexus-storage-guard/AGENTS.md`](crates/nexus-storage-guard/AGENTS.md) | | `crates/nexus-spoke-adapter/` | SPOKE boundary — extensions.nexus accessors + spoke-operations delegation | [`crates/nexus-spoke-adapter/AGENTS.md`](crates/nexus-spoke-adapter/AGENTS.md) | | `crates/nexus-cloud-sync/` | Cloud sync transport | [`crates/nexus-cloud-sync/AGENTS.md`](crates/nexus-cloud-sync/AGENTS.md) | | `crates/nexus-creator/` | Creator aggregate + local identity | [`crates/nexus-creator/AGENTS.md`](crates/nexus-creator/AGENTS.md) | @@ -109,7 +116,7 @@ UI work in this repo follows a **studio-first** routing rule. The visual proving - Studio boundaries + `@web-*` aliases: [`apps/design-studio/AGENTS.md`](apps/design-studio/AGENTS.md) - Promotion rules + package boundary: [`packages/nexus-ui/AGENTS.md`](packages/nexus-ui/AGENTS.md) - Canonical workflow + classification labels (`promoted primitive` / `studio-local fixture` / `web-only wrapper` / `future web product component`): [`.mstar/knowledge/architecture-patterns/ui-component-promotion-workflow.md`](.mstar/knowledge/architecture-patterns/ui-component-promotion-workflow.md) -- Studio spec: [`.mstar/specs/design-studio.md`](.mstar/specs/design-studio.md) +- Studio spec: [`.mstar/specs/surfaces/design-studio.md`](.mstar/specs/surfaces/design-studio.md) ## Development Policy diff --git a/CONCEPTS.md b/CONCEPTS.md index 01c396f3e..8736bb536 100644 --- a/CONCEPTS.md +++ b/CONCEPTS.md @@ -9,10 +9,10 @@ Core domain terms used across Nexus OSS documentation, plans, and code. Each ent The product thesis (canonized in the V1.122 pivot): **Nexus is the local-first creative-writing tool where a World's Timeline is the central instrument, AI agents are harnessed through Canvas, and Computable modules make worlds react.** Each pillar below names a product thesis, not a single crate. See `STRATEGY.md` § *Vision → Three pillars* for the crate/spec mapping. ### Harness -The **control-strategy pillar**: how an author *harnesses* AI agents to execute creative work — orchestration, capability routing, agent hosting, and presets. Maps to the orchestration engine + agent host + capability registry + presets. The user-visible pillar entry labels **Harness** (rename landed in V1.156 P3 — closes `DF-V1122-HARNESS-RENAME`); **Preset stays** as the mechanism name under Harness. Specs: [orchestration-engine.md](.mstar/specs/orchestration-engine.md), [agent-host.md](.mstar/specs/agent-host.md), [capability-registry.md](.mstar/specs/capability-registry.md). +The **control-strategy pillar**: how an author *harnesses* AI agents to execute creative work — orchestration, capability routing, agent hosting, and presets. Maps to the orchestration engine + agent host + capability registry + presets. The user-visible pillar entry labels **Harness** (rename landed in V1.156 P3 — closes `DF-V1122-HARNESS-RENAME`); **Preset stays** as the mechanism name under Harness. Specs: [orchestration-engine.md](.mstar/specs/orchestration/orchestration-engine.md), [agent-host.md](.mstar/specs/agents/agent-host.md), [capability-registry.md](.mstar/specs/agents/capability-registry.md). ### Computable -The **product-thesis pillar** that *worlds react* via WASM compute — combat resolution, dice, relationship-graph computation, user-authored modules. **Distinct from `Compute (Capability)` below**: *Computable* is the pillar (the product claim that worlds react); *Compute (Capability)* is the mechanism (the WASM execution unit an author/agent invokes). The pillar names the thesis; the capability names the implementation unit. Specs: [compute-module-abi.md](.mstar/specs/compute-module-abi.md), [wasm-host.md](.mstar/specs/wasm-host.md). +The **product-thesis pillar** that *worlds react* via WASM compute — combat resolution, dice, relationship-graph computation, user-authored modules. **Distinct from `Compute (Capability)` below**: *Computable* is the pillar (the product claim that worlds react); *Compute (Capability)* is the mechanism (the WASM execution unit an author/agent invokes). The pillar names the thesis; the capability names the implementation unit. Specs: [compute-module-abi.md](.mstar/specs/compute/compute-module-abi.md), [wasm-host.md](.mstar/specs/compute/wasm-host.md). ### Timeline-first World building The **Canvas hero pattern** (V1.122, deepened V1.123): a World's Timeline is the primary Canvas surface for **World entry** — authors open a World and meet its *when* axis before its entity graph or chapter structure. `CanvasSurfaceKind = "timeline"` is a peer surface alongside Strategy / Outline (Timeline-companion) / World KB, and is the default **World-entry** surface. **Outline** remains the default for **Work entry** (V1.118, unchanged). From V1.123, Timeline is not a single flat event list: it is **three zoom layers** — [Brief](#brief), [Narrative](#narrative), and [Moment](#moment) — with domain-differentiated use (World: Brief+Narrative; Work: Narrative+Moment via peer `work-timeline`). @@ -21,13 +21,13 @@ The **Canvas hero pattern** (V1.122, deepened V1.123): a World's Timeline is the - **Spine:** World + Timeline + KnowledgeEntry + Fork — the truth of the narrative universe. Timeline is the World's *when* axis (three layers). KnowledgeEntry is one primitive with exactly one canonical owner scope (World / Character / ActorWorldBinding — see [KnowledgeEntry](#knowledgeentry)); **v1.184 shipped** Character and binding owner scopes; World remains the pre-Actor default. - **Projection:** Work + Outline + Manuscript — the authoring plan and prose bound to a World. Outline is the Work's structural projection (chapters / scenes); Work Timeline is a peer projection for Narrative+Moment. -Authors should feel: **World first for World building (Timeline, Brief-led); Work first for chapter writing (Outline), with Work Timeline reachable for scene precision.** Dual entry defaults encode that. Spec: [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md). +Authors should feel: **World first for World building (Timeline, Brief-led); Work first for chapter writing (Outline), with Work Timeline reachable for scene precision.** Dual entry defaults encode that. Spec: [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md). --- ## Actors & Narrative Identity -The Actor model is **accepted product direction**. **v1.184 shipped** the Character bearer, ActorWorldBinding, three KE owner scopes, Character KnowledgeView, one-host execution, Character SOUL/Memory, and ToM L1/L2. **v1.185 maintenance is not shipped** (identity edit, reversible archive/restore, post-create WorldSheet maintenance, KE content/detail/edit/delete, run-connected `--remember`). Durable authority: [actor-product-model.md](.mstar/specs/actor-product-model.md). Do not treat missing v1.185 verbs as proof that no Actor storage or API exists. +The Actor model is **accepted product direction**. **v1.184 shipped** the Character bearer, ActorWorldBinding, three KE owner scopes, Character KnowledgeView, one-host execution, Character SOUL/Memory, and ToM L1/L2. **v1.185 maintenance is not shipped** (identity edit, reversible archive/restore, post-create WorldSheet maintenance, KE content/detail/edit/delete, run-connected `--remember`). Durable authority: [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md). Do not treat missing v1.185 verbs as proof that no Actor storage or API exists. ### Actor The cross-cutting **narrative identity** primitive — *who can think and act* in a story. Outward line: **Nexus Actors are who can think and act — Creators conduct the story; Characters live it.** `ActorRef` is a closed v1 sum: `Creator | Character` — a product-identity model, **not** a unified actors-table storage commitment (existing Creator storage remains). Actor is **not a fourth pillar**: it cuts across [Harness](#harness) (executes an Actor), Canvas (surfaces one), and [Computable](#computable) (worlds react to one). One [Agent Host](#agent-host) / runtime / provider plane serves both kinds; a Character session executes under the owning Creator's admission boundary with an isolated ACP conversation history. @@ -66,7 +66,7 @@ The composed, authorized knowledge scope a [Character](#character) perceives ins Cross-World sharing is explicit — it never implicitly copies all World facts or memories. Contrast the Creator view over an owned World: omniscient, including creator-only facts. ### Viewpoint -Subordinate **execution context** paired with an `ActorRef` — logically `{world_id, optional binding_id/branch_id/event_id}` (it does not repeat an actor id; Character execution requires the binding id, Creator omits it) — describing *from where* an [Actor](#actor) acts or reads within a session. Viewpoint is not an identity, not an Actor kind, and not the name of any Character↔World association. The earlier same-day Viewpoint-as-identity direction (2026-09-04) is superseded by the Actor product lock ([actor-product-model.md](.mstar/specs/actor-product-model.md) §0). +Subordinate **execution context** paired with an `ActorRef` — logically `{world_id, optional binding_id/branch_id/event_id}` (it does not repeat an actor id; Character execution requires the binding id, Creator omits it) — describing *from where* an [Actor](#actor) acts or reads within a session. Viewpoint is not an identity, not an Actor kind, and not the name of any Character↔World association. The earlier same-day Viewpoint-as-identity direction (2026-09-04) is superseded by the Actor product lock ([actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) §0). --- @@ -81,25 +81,25 @@ The fundamental unit of structured knowledge in a world. KnowledgeEntries have t **Canonical owner scope** (Actor-model alignment): KnowledgeEntry stays **one primitive**, and each entry has exactly **one** canonical owner scope — **World**, **[Character](#character)**, or **[ActorWorldBinding](#actorworldbinding)**. **v1.184 shipped** Character and binding owners alongside World. World-owned KE remains World-local; Character-owned KE is visible across that Character's bindings without copying; ActorWorldBinding-owned KE is isolated to that World life. Current `block_type=character` rows are [WorldSheets](#worldsheet). KE **content** maintenance is **v1.185, not shipped**. The per-scope composition a Character perceives is the [Character KnowledgeView](#character-knowledgeview). ### Lore Activation -The default-on mechanism (V1.149 / DF-74) that selects and orders World KB entries for a moment by their `modules.activation` fire-conditions (`keys` / `secondary_keys` / `logic` / `constant` / `priority` / `order` / `match`), with optional relation-hop expansion (≤2 hops) from firing entries. Worlds whose entries carry no activation module are assembled byte-identically to the pre-activation path. Applied during [Moment Context Assembly](#moment-context-assembly); dialect and contract: [`spoke-adapter-architecture.md`](.mstar/specs/spoke-adapter-architecture.md) §7.4. +The default-on mechanism (V1.149 / DF-74) that selects and orders World KB entries for a moment by their `modules.activation` fire-conditions (`keys` / `secondary_keys` / `logic` / `constant` / `priority` / `order` / `match`), with optional relation-hop expansion (≤2 hops) from firing entries. Worlds whose entries carry no activation module are assembled byte-identically to the pre-activation path. Applied during [Moment Context Assembly](#moment-context-assembly); dialect and contract: [`spoke-adapter-architecture.md`](.mstar/specs/architecture/spoke-adapter-architecture.md) §7.4. ### Moment Directive -A **short-horizon, author-written instruction** (V1.150 / DF-75) that injects into the assembled prompt as a distinct section **above lore, below system/personality** — the clean-room Author's-Note analogue. One paragraph, not a second system prompt; never silently generated. Scoped **per-Work with an optional World override** (closest scope wins; not creator-global). Lifetime is governed by **TTL** (`generations` — one injecting assemble = one count; `chapters` — one per chapter advance for novel Works) and optionally **clear-on-scene-change** (focused `event_id` change proxy). **Product-local only** — never a SPOKE object: not a `modules.*` entry, not a KnowledgeEntry, never on the spoke wire or in AssemblePacket traces (AC-I3). Author surface V1.150: CLI (`nexus42 creator moment-directive set|show|clear`); observation via `platform context assemble-moment` output. Not stage-gated — its TTL governs lifetime, not generation stage. Spec: [`spoke-adapter-architecture.md`](.mstar/specs/spoke-adapter-architecture.md) §7.4. Cross-ref: [Lore Activation](#lore-activation), [Preset (Injection) Slot](#preset-injection-slot), [Moment Context Assembly](#moment-context-assembly). +A **short-horizon, author-written instruction** (V1.150 / DF-75) that injects into the assembled prompt as a distinct section **above lore, below system/personality** — the clean-room Author's-Note analogue. One paragraph, not a second system prompt; never silently generated. Scoped **per-Work with an optional World override** (closest scope wins; not creator-global). Lifetime is governed by **TTL** (`generations` — one injecting assemble = one count; `chapters` — one per chapter advance for novel Works) and optionally **clear-on-scene-change** (focused `event_id` change proxy). **Product-local only** — never a SPOKE object: not a `modules.*` entry, not a KnowledgeEntry, never on the spoke wire or in AssemblePacket traces (AC-I3). Author surface V1.150: CLI (`nexus42 creator moment-directive set|show|clear`); observation via `platform context assemble-moment` output. Not stage-gated — its TTL governs lifetime, not generation stage. Spec: [`spoke-adapter-architecture.md`](.mstar/specs/architecture/spoke-adapter-architecture.md) §7.4. Cross-ref: [Lore Activation](#lore-activation), [Preset (Injection) Slot](#preset-injection-slot), [Moment Context Assembly](#moment-context-assembly). ### Preset (Injection) Slot -A **named, ordered region of the assembled prompt** (V1.150 / DF-75) filled by activated lore — the slot layer that shapes the `## World Knowledge Base` block after [Lore Activation](#lore-activation) decides what fires. Shipped slots: `world.before` (before-defs anchors), the default fallback (the V1.149 flat block — the byte-equivalence anchor), `world.after` (post-defs reminders), open `kb.outlet.` (author-named outlets, sorted; unknown names are not errors), and `style.post_history` (the one reserved well-known outlet, tail of the lore block) — plus the `moment.directive` slot (top-level section, filled by the [Moment Directive](#moment-directive)). Emit order is locked (spec §2/Q5); within-slot order keeps the V1.149 priority-then-order. Slot filling is **generation-stage gated** (spec §4): `style.post_history` fills only for `produce`/`review`; `system_maintenance` runs no lore slots; direct-CLI `unspecified` keeps everything on. **Disambiguation:** distinct from [Preset](#preset) under Compute & AI Domain (a pre-configured bundle of compute capabilities) — this entry is the *injection* slot in the assembled prompt, not a preset manifest. Spec: [`spoke-adapter-architecture.md`](.mstar/specs/spoke-adapter-architecture.md) §7.4. +A **named, ordered region of the assembled prompt** (V1.150 / DF-75) filled by activated lore — the slot layer that shapes the `## World Knowledge Base` block after [Lore Activation](#lore-activation) decides what fires. Shipped slots: `world.before` (before-defs anchors), the default fallback (the V1.149 flat block — the byte-equivalence anchor), `world.after` (post-defs reminders), open `kb.outlet.` (author-named outlets, sorted; unknown names are not errors), and `style.post_history` (the one reserved well-known outlet, tail of the lore block) — plus the `moment.directive` slot (top-level section, filled by the [Moment Directive](#moment-directive)). Emit order is locked (spec §2/Q5); within-slot order keeps the V1.149 priority-then-order. Slot filling is **generation-stage gated** (spec §4): `style.post_history` fills only for `produce`/`review`; `system_maintenance` runs no lore slots; direct-CLI `unspecified` keeps everything on. **Disambiguation:** distinct from [Preset](#preset) under Compute & AI Domain (a pre-configured bundle of compute capabilities) — this entry is the *injection* slot in the assembled prompt, not a preset manifest. Spec: [`spoke-adapter-architecture.md`](.mstar/specs/architecture/spoke-adapter-architecture.md) §7.4. ### Assembly Inspector -The **read-only observation surface** for [Moment Context Assembly](#moment-context-assembly) (V1.151 / DF-76) — what the author sees when they want to know *why this moment assembled the way it did*. The inspector consumes the **enriched inspector packet** — a separate emission path from the assembled prompt (never changes assembled bytes, AC-I6) — built by `build_inspector_packet` (`nexus-moment-context-assembly/src/inspector.rs`) and presented in the Control Room panel, the daemon route `POST /v1/daemon/inspector/moment`, and the CLI `assemble-moment --inspect` / `--emit-packet`. It surfaces: **activation trace** (`modules.activation_trace` — full per-entry fire/miss with reasons, in the spoke assemble-module recipe vocabulary; consumer-only — nexus presents the trace, it does not clone the spoke assemble wire), **placement** (`modules.placement` — accepted entries only), **slot map** (`slot_map` — which accepted entry landed in which named slot, captured post stage-gate), **token budget** (`budget` — chars/4 primary/hop estimates + cap/remaining), and **directive status** (`moment_directive` — status/metadata only; the directive body never appears, AC-I3). Read-only: it observes `assemble_moment` output; it never re-runs activation, never mutates the World KB, never injects content. Spec: [`spoke-adapter-architecture.md`](.mstar/specs/spoke-adapter-architecture.md) §7.4 (inspector packet field surface). +The **read-only observation surface** for [Moment Context Assembly](#moment-context-assembly) (V1.151 / DF-76) — what the author sees when they want to know *why this moment assembled the way it did*. The inspector consumes the **enriched inspector packet** — a separate emission path from the assembled prompt (never changes assembled bytes, AC-I6) — built by `build_inspector_packet` (`nexus-moment-context-assembly/src/inspector.rs`) and presented in the Control Room panel, the daemon route `POST /v1/daemon/inspector/moment`, and the CLI `assemble-moment --inspect` / `--emit-packet`. It surfaces: **activation trace** (`modules.activation_trace` — full per-entry fire/miss with reasons, in the spoke assemble-module recipe vocabulary; consumer-only — nexus presents the trace, it does not clone the spoke assemble wire), **placement** (`modules.placement` — accepted entries only), **slot map** (`slot_map` — which accepted entry landed in which named slot, captured post stage-gate), **token budget** (`budget` — chars/4 primary/hop estimates + cap/remaining), and **directive status** (`moment_directive` — status/metadata only; the directive body never appears, AC-I3). Read-only: it observes `assemble_moment` output; it never re-runs activation, never mutates the World KB, never injects content. Spec: [`spoke-adapter-architecture.md`](.mstar/specs/architecture/spoke-adapter-architecture.md) §7.4 (inspector packet field surface). ### Knowledge Pack -A **portable World-lore transport** (V1.152 / DF-77) — a single JSON handbook envelope carrying ordered `KnowledgeEntry` records, their `Relation`s, optional `SourceAnchor`s, and `modules.pack` catalog metadata (`title`, `version`, `creator`, optional `description`). Pack I/O moves lore between Worlds or hosts via `creator world kb pack export|import` and daemon routes `POST /v1/daemon/worlds/:world_id/kb/pack/export|import`. Imported rows carry `source_provenance_kind = pack_import` (shared `IMPORT_PROVENANCE` constant). **Consumer-only:** the handbook shape is product transport, not a `spoke-operations` surface — nexus builds/parses via `nexus_spoke_adapter::pack` and orchestrates writes through shared `import_pack` (`crates/nexus-daemon-runtime/src/pack_import.rs`). Conflict policies: **skip** (default), **rename** (`canonical_name` disambiguation with ` imported` suffix), **overwrite** (CAS body replace; `status` preserved). `modules.activation` fire-conditions round-trip with lore (no force-enable on import). Cross-ref: [Lore Activation](#lore-activation), [Moment Context Assembly](#moment-context-assembly), [`spoke-adapter-architecture.md`](.mstar/specs/spoke-adapter-architecture.md) §11. +A **portable World-lore transport** (V1.152 / DF-77) — a single JSON handbook envelope carrying ordered `KnowledgeEntry` records, their `Relation`s, optional `SourceAnchor`s, and `modules.pack` catalog metadata (`title`, `version`, `creator`, optional `description`). Pack I/O moves lore between Worlds or hosts via `creator world kb pack export|import` and daemon routes `POST /v1/daemon/worlds/:world_id/kb/pack/export|import`. Imported rows carry `source_provenance_kind = pack_import` (shared `IMPORT_PROVENANCE` constant). **Consumer-only:** the handbook shape is product transport, not a `spoke-operations` surface — nexus builds/parses via `nexus_spoke_adapter::pack` and orchestrates writes through shared `import_pack` (`crates/nexus-daemon-runtime/src/pack_import.rs`). Conflict policies: **skip** (default), **rename** (`canonical_name` disambiguation with ` imported` suffix), **overwrite** (CAS body replace; `status` preserved). `modules.activation` fire-conditions round-trip with lore (no force-enable on import). Cross-ref: [Lore Activation](#lore-activation), [Moment Context Assembly](#moment-context-assembly), [`spoke-adapter-architecture.md`](.mstar/specs/architecture/spoke-adapter-architecture.md) §11. ### SourceAnchor A reference that ties a KnowledgeEntry to its provenance — which artifact (manuscript chapter, outline node, etc.) produced it and at what position. ### Extensions (`extensions.nexus`) -A SPOKE-standard mechanism for carrying nexus-specific fields on spoke-schema objects. `extensions.nexus` is a typed namespace on spoke `KnowledgeEntry` (and other spoke types) that holds nexus-local identity, provenance, and lifecycle metadata — e.g., `world_id`, `created_from_command_id`, and provenance fields. Accessors live in `nexus-spoke-adapter::extensions`. This avoids requiring spoke to declare every nexus product field in its core schema. The `nexus-spoke-adapter` exposes a dual-surface API: **Surface A** (pure delegates, frozen) for consumers that manage their own storage, and **Surface B** (injection-orchestration via port traits) for consumers that want spoke to compose the full lifecycle. See [`spoke-adapter-architecture.md`](.mstar/specs/spoke-adapter-architecture.md) for the adoption guide. +A SPOKE-standard mechanism for carrying nexus-specific fields on spoke-schema objects. `extensions.nexus` is a typed namespace on spoke `KnowledgeEntry` (and other spoke types) that holds nexus-local identity, provenance, and lifecycle metadata — e.g., `world_id`, `created_from_command_id`, and provenance fields. Accessors live in `nexus-spoke-adapter::extensions`. This avoids requiring spoke to declare every nexus product field in its core schema. The `nexus-spoke-adapter` exposes a dual-surface API: **Surface A** (pure delegates, frozen) for consumers that manage their own storage, and **Surface B** (injection-orchestration via port traits) for consumers that want spoke to compose the full lifecycle. See [`spoke-adapter-architecture.md`](.mstar/specs/architecture/spoke-adapter-architecture.md) for the adoption guide. ### Manuscript The structured prose output within a world — organized into chapters, scenes, and narrative flow. A world may have multiple manuscripts representing parallel storylines or drafts. @@ -114,7 +114,7 @@ Timeline's **world-global layer** — era / age / multi-decade markers and world Timeline's **event-level layer** — human-paced events in order (days/weeks/years): battles, treaties, journeys. Shared by **World Timeline** and **Work Timeline**. This is the V1.122 Timeline surface reframed as one of three layers (balanced event axis + relationship edges + Context clusters). **Disambiguation:** not "narrative writing" (prose craft) and not a synonym for Manuscript — here *Narrative* means the **event-granularity Timeline zoom layer**. Cross-ref: [Timeline](#timeline), [Brief](#brief), [Moment](#moment), [KnowledgeEntry](#knowledgeentry). ### Moment -Timeline's **scene/beat-precise layer** — sub-scene time (minutes/hours within a scene), manuscript-anchored, so an author can scrutinize what happens in an exact scene. Moment is the **hero layer for Work Timeline** (peer `CanvasSurfaceKind = "work-timeline"`; Work **entry** stays Outline). World Timeline does not ship a Moment layer in V1.123 (`DF-V1123-WORLD-MOMENT`). **Disambiguation:** distinct from [Moment Context Assembly](#moment-context-assembly) (the session process that packs KnowledgeEntries + memory for an agent task). Scope hierarchy already includes Moment under `World > Timeline > Event > Moment` ([entity-scope-model.md](.mstar/specs/entity-scope-model.md)); V1.123 adds Canvas projection as a Timeline layer. Cross-ref: [Timeline](#timeline), [Narrative](#narrative), [Outline](#outline), [Manuscript](#manuscript). +Timeline's **scene/beat-precise layer** — sub-scene time (minutes/hours within a scene), manuscript-anchored, so an author can scrutinize what happens in an exact scene. Moment is the **hero layer for Work Timeline** (peer `CanvasSurfaceKind = "work-timeline"`; Work **entry** stays Outline). World Timeline does not ship a Moment layer in V1.123 (`DF-V1123-WORLD-MOMENT`). **Disambiguation:** distinct from [Moment Context Assembly](#moment-context-assembly) (the session process that packs KnowledgeEntries + memory for an agent task). Scope hierarchy already includes Moment under `World > Timeline > Event > Moment` ([entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md)); V1.123 adds Canvas projection as a Timeline layer. Cross-ref: [Timeline](#timeline), [Narrative](#narrative), [Outline](#outline), [Manuscript](#manuscript). ### Fork The only mechanism for changing world history. Creates a divergent branch from a point in the timeline. Original history is preserved. Forks are the structural equivalent of version control branches for narrative. @@ -136,7 +136,7 @@ A structured, non-linear representation of a work's planned content — nodes re A WASM-powered execution unit within a world — the *mechanism* an author or agent invokes. Examples: combat engine resolution, dice rolling, relationship graph computation. Compute modules are embedded (shipped with the binary) or user-authored. **Distinct from the [Computable](#computable) pillar** in *Three Pillars* above: this entry is the capability mechanism; *Computable* is the product thesis that worlds react via such capabilities. ### Run -One execution of a compute module against a World — the direct-lane (Control Room) product concept over the `compute_sessions` row. A Run moves `running → succeeded | failed`; a succeeded Run stays **Needs review** until the author explicitly **Accept**s (→ Applied) or **Discard**s (→ Discarded). The direct lane **never auto-applies** (review-then-apply); the preset `narrative.compute` path may auto-apply inside a Harness session. Run history is retained, and terminal Runs can be cleared per World (Clear history — never `running`/needs-review rows). Author-facing vocabulary (Run / Proposal / Accept / Discard): [daemon-api-surface-conventions.md](.mstar/specs/daemon-api-surface-conventions.md) §12.3. Cross-ref: [Compute (Capability)](#compute-capability), [Compute result](#compute-result), [Computable](#computable). Wire surface: [daemon-api-surface-conventions.md](.mstar/specs/daemon-api-surface-conventions.md) §12.3. +One execution of a compute module against a World — the direct-lane (Control Room) product concept over the `compute_sessions` row. A Run moves `running → succeeded | failed`; a succeeded Run stays **Needs review** until the author explicitly **Accept**s (→ Applied) or **Discard**s (→ Discarded). The direct lane **never auto-applies** (review-then-apply); the preset `narrative.compute` path may auto-apply inside a Harness session. Run history is retained, and terminal Runs can be cleared per World (Clear history — never `running`/needs-review rows). Author-facing vocabulary (Run / Proposal / Accept / Discard): [daemon-api-surface-conventions.md](.mstar/specs/runtime/daemon-api-surface-conventions.md) §12.3. Cross-ref: [Compute (Capability)](#compute-capability), [Compute result](#compute-result), [Computable](#computable). Wire surface: [daemon-api-surface-conventions.md](.mstar/specs/runtime/daemon-api-surface-conventions.md) §12.3. ### Compute result A Timeline node created when an author **accepts** a Run's proposals — `event_type: "compute_result"`, appended **canon** (never provisional) with `extensions.nexus.compute` provenance (module id/version, run id, `source_kind: "direct_invoke"`). Preset-path compute events share the same event family so accepted reactions speak one visual language; failed/discarded Runs never produce Timeline nodes (the Timeline stays narrative truth, not an ops log). Cross-ref: [Run](#run), [Timeline](#timeline), [Computable](#computable). @@ -201,7 +201,7 @@ The local background process within `nexus42` that manages the World KB SQLite d The HTTP surface served by the Daemon Runtime, reachable under `/v1/daemon/*` (previously `/v1/local/*`). It exposes world/knowledge, creator, orchestration, and manuscript endpoints to the CLI, web SPA, and desktop shell. By default it binds to loopback; remote bind requires both `NEXUS42_DAEMON_API_KEY` and `NEXUS_DAEMON_REMOTE_BIND=1`. ### Connect Host -The opt-in spoke-connect surface for **third-party narrative reasoning** (PD-09 / FL-R / DF-72 N-C0, V1.148): a separate OS process started by `nexus42 connect start` (Cargo feature `connect-host`, default off) that peers over spoke-connect with integrator runtimes and advertises an honest `HostCapabilityManifest` (installation `host_id` = `~/.nexus42/device-id`; roles `["data-store", "checker", "assembler", "computable-engine"]`; `extensions.nexus.served_ops` = `["upsert", "promote", "relate", "check", "assemble", "compute", "tools.nexus.list_observed_peers", "tools.nexus.list_modules"]` — the six core ops plus the shipped V1.173 (DF-84) local tool ops; compute has shipped since V1.154 P2 (N-C2 E2), so the connect surface is the semantic reasoning-complete milestone wire form; the literal `"reasoning-complete"` string stays absent because the manifest schema defines open-string arrays, not that enum). It is the third consumption surface **alongside Daemon HTTP** — Adapter-full, not Product-full: it never exposes Harness UI, ACP-as-server, or Canvas, and non-served inbound ops are refused (`op_unsupported`). Capability-token / world scoping must exist before multi-tenant exposure. See [Daemon API](#daemon-api) (creator UI SSOT) and the FL-R roadmap record. Spec: [spoke-adapter-architecture.md](.mstar/specs/spoke-adapter-architecture.md) §10. +The opt-in spoke-connect surface for **third-party narrative reasoning** (PD-09 / FL-R / DF-72 N-C0, V1.148): a separate OS process started by `nexus42 connect start` (Cargo feature `connect-host`, default off) that peers over spoke-connect with integrator runtimes and advertises an honest `HostCapabilityManifest` (installation `host_id` = `~/.nexus42/device-id`; roles `["data-store", "checker", "assembler", "computable-engine"]`; `extensions.nexus.served_ops` = `["upsert", "promote", "relate", "check", "assemble", "compute", "tools.nexus.list_observed_peers", "tools.nexus.list_modules"]` — the six core ops plus the shipped V1.173 (DF-84) local tool ops; compute has shipped since V1.154 P2 (N-C2 E2), so the connect surface is the semantic reasoning-complete milestone wire form; the literal `"reasoning-complete"` string stays absent because the manifest schema defines open-string arrays, not that enum). It is the third consumption surface **alongside Daemon HTTP** — Adapter-full, not Product-full: it never exposes Harness UI, ACP-as-server, or Canvas, and non-served inbound ops are refused (`op_unsupported`). Capability-token / world scoping must exist before multi-tenant exposure. See [Daemon API](#daemon-api) (creator UI SSOT) and the FL-R roadmap record. Spec: [spoke-adapter-architecture.md](.mstar/specs/architecture/spoke-adapter-architecture.md) §10. ### Setup Wizard The first-launch flow (Entrance → Agent → Workspace → Done since V1.170 P1; historically welcome + workspace → daemon ready → ACP agent detection → done) gated by a `setup_completed` marker in `~/.nexus42/config.toml`. The Entrance step persists the [Entrance](#entrance) via Tauri IPC before completion. Triggers again if the marker is cleared. Every app launch (not only first) verifies the daemon is running before entering the main UI. @@ -224,7 +224,7 @@ The local-first "Control Room + Setup" web interface (`apps/web`). A React SPA s On Creator hub routes (`/works`, `/worlds`), the **content region** flips between two modes (V1.128): **Create page** (no World/Work selected — card CTAs to create) and **Controller Panel stub** (entity selected — placeholder + **Back** that clears selection). Mode SSOT is `CreatorEntitySelectionContext`, orthogonal to canvas routes under `/works/:workId/*`. See [creator-shell-content-mode-pattern.md](.mstar/knowledge/architecture-patterns/creator-shell-content-mode-pattern.md). ### Entrance -The **User-layer usage identity** (V1.170 P1) — `developer` | `content-creator` — that selects between the two first-party SPA layout trees: **Create** (a *reduced* tree that hides the operator chrome — agent catalog, preset manager, sessions, schedule, rules authoring, inspector, Connect, capability browser) and **Develop** (the full Control Room plus the Develop hub v1 land route `/developer`). **Orthogonal to [Creator](#creator)**: switching entrance never creates, swaps, or hides Creator profiles, and the profile switcher stays available in both trees. v1 is **web/desktop persisted state only** — browser `localStorage` (`nexus-entrance`) and desktop Tauri IPC (`get_entrance` / `set_entrance` writing the `entrance` key of `~/.nexus42/config.toml`, same durability class as `setup_completed`); **no daemon User entity, no schema, no wire contract** (`wire_contracts_changed: false`). Default = `content-creator`; unset/failed reads resolve to it without writing. Specs: [web-ui.md](.mstar/specs/web-ui.md) §29, [desktop-shell.md](.mstar/specs/desktop-shell.md) §13. +The **User-layer usage identity** (V1.170 P1) — `developer` | `content-creator` — that selects between the two first-party SPA layout trees: **Create** (a *reduced* tree that hides the operator chrome — agent catalog, preset manager, sessions, schedule, rules authoring, inspector, Connect, capability browser) and **Develop** (the full Control Room plus the Develop hub v1 land route `/developer`). **Orthogonal to [Creator](#creator)**: switching entrance never creates, swaps, or hides Creator profiles, and the profile switcher stays available in both trees. v1 is **web/desktop persisted state only** — browser `localStorage` (`nexus-entrance`) and desktop Tauri IPC (`get_entrance` / `set_entrance` writing the `entrance` key of `~/.nexus42/config.toml`, same durability class as `setup_completed`); **no daemon User entity, no schema, no wire contract** (`wire_contracts_changed: false`). Default = `content-creator`; unset/failed reads resolve to it without writing. Specs: [web-ui.md](.mstar/specs/surfaces/web-ui.md) §29, [desktop-shell.md](.mstar/specs/surfaces/desktop-shell.md) §13. ### Desktop Shell The Tauri v2 native desktop client (`apps/desktop`). Wraps the web SPA (`apps/web/dist`) in a native window, adds OS-level capabilities (Open with…, Reveal in Finder, Copy Path, sidecar lifecycle management). Detects the Tauri runtime at startup and selects `TauriClient` over `BrowserClient` via capability detection. @@ -239,49 +239,49 @@ Paths are relative to the repo root. Each entry links the term to its authoritat | Term | Related concepts | Spec doc | |------|-----------------|----------| -| Harness | Orchestration Engine, Agent Host, Capability Registry, Preset | [orchestration-engine.md](.mstar/specs/orchestration-engine.md) | -| Computable (pillar) | Compute (Capability), WASM host, compute-module-abi | [compute-module-abi.md](.mstar/specs/compute-module-abi.md) | -| Timeline-first World building | World, Timeline, Brief, Narrative, Moment, Outline, Workspace (Canvas), Fork | [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md) | +| Harness | Orchestration Engine, Agent Host, Capability Registry, Preset | [orchestration-engine.md](.mstar/specs/orchestration/orchestration-engine.md) | +| Computable (pillar) | Compute (Capability), WASM host, compute-module-abi | [compute-module-abi.md](.mstar/specs/compute/compute-module-abi.md) | +| Timeline-first World building | World, Timeline, Brief, Narrative, Moment, Outline, Workspace (Canvas), Fork | [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md) | ### Actors & Narrative Identity | Term | Related concepts | Spec doc | |------|-----------------|----------| -| Actor | Creator, Character, ActorWorldBinding, Viewpoint | [actor-product-model.md](.mstar/specs/actor-product-model.md) — durable authority (v1.184 stages shipped; v1.185 maintenance not shipped) | -| Creator | Actor, WorldMembership (Creator↔World), Creator Memory, World | [creator-workflow.md](.mstar/specs/creator-workflow.md) (shipped operational owner); [actor-product-model.md](.mstar/specs/actor-product-model.md) (Actor-kind reframing) | -| Character | Actor, ActorWorldBinding, WorldSheet, Character KnowledgeView | [actor-product-model.md](.mstar/specs/actor-product-model.md) — v1.184 shipped; edit/archive v1.185 not shipped | -| ActorWorldBinding | Character, World, WorldSheet (≠ WorldMembership) | [actor-product-model.md](.mstar/specs/actor-product-model.md) — v1.184 shipped; WorldSheet maintenance v1.185 not shipped | -| WorldSheet | KnowledgeEntry (`block_type=character`), ActorWorldBinding | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) (shipped KE taxonomy); [actor-product-model.md](.mstar/specs/actor-product-model.md) (binding linkage) | -| Character KnowledgeView | Character, ActorWorldBinding, KnowledgeEntry, Scope | [actor-product-model.md](.mstar/specs/actor-product-model.md) — v1.184 shipped; KE content maintenance v1.185 not shipped | -| Viewpoint | Actor, World, Moment Context Assembly | [actor-product-model.md](.mstar/specs/actor-product-model.md) (subordinate execution context) | +| Actor | Creator, Character, ActorWorldBinding, Viewpoint | [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) — durable authority (v1.184 stages shipped; v1.185 maintenance not shipped) | +| Creator | Actor, WorldMembership (Creator↔World), Creator Memory, World | [creator-workflow.md](.mstar/specs/creator/creator-workflow.md) (shipped operational owner); [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) (Actor-kind reframing) | +| Character | Actor, ActorWorldBinding, WorldSheet, Character KnowledgeView | [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) — v1.184 shipped; edit/archive v1.185 not shipped | +| ActorWorldBinding | Character, World, WorldSheet (≠ WorldMembership) | [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) — v1.184 shipped; WorldSheet maintenance v1.185 not shipped | +| WorldSheet | KnowledgeEntry (`block_type=character`), ActorWorldBinding | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) (shipped KE taxonomy); [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) (binding linkage) | +| Character KnowledgeView | Character, ActorWorldBinding, KnowledgeEntry, Scope | [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) — v1.184 shipped; KE content maintenance v1.185 not shipped | +| Viewpoint | Actor, World, Moment Context Assembly | [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) (subordinate execution context) | ### Creative Writing Domain | Term | Related concepts | Spec doc | |------|-----------------|----------| -| World | Fork, Timeline, Manuscript, Scope | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| KnowledgeEntry | SourceAnchor, Taxonomy, Computable | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| SourceAnchor | KnowledgeEntry, Provenance | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| Manuscript | World, Timeline, Chapter, Moment (layer) | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| Timeline | World, KnowledgeEntry, Fork, Brief, Narrative, Moment | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| Brief | Timeline, Narrative, Timeline-first World building | [entity-scope-model.md](.mstar/specs/entity-scope-model.md); [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md) | -| Narrative (Timeline layer) | Timeline, Brief, Moment, KnowledgeEntry | [entity-scope-model.md](.mstar/specs/entity-scope-model.md); [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md) | -| Moment (Timeline layer) | Timeline, Narrative, Outline, Manuscript | [entity-scope-model.md](.mstar/specs/entity-scope-model.md); [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md) | -| Fork | World, Timeline | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| Scope | KnowledgeEntry, Moment Context Assembly | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | +| World | Fork, Timeline, Manuscript, Scope | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| KnowledgeEntry | SourceAnchor, Taxonomy, Computable | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| SourceAnchor | KnowledgeEntry, Provenance | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| Manuscript | World, Timeline, Chapter, Moment (layer) | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| Timeline | World, KnowledgeEntry, Fork, Brief, Narrative, Moment | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| Brief | Timeline, Narrative, Timeline-first World building | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md); [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md) | +| Narrative (Timeline layer) | Timeline, Brief, Moment, KnowledgeEntry | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md); [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md) | +| Moment (Timeline layer) | Timeline, Narrative, Outline, Manuscript | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md); [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md) | +| Fork | World, Timeline | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| Scope | KnowledgeEntry, Moment Context Assembly | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | | Narrative Profile | Novel, Essay, Game-Bible, Script | [novel-writing/workflow-profile.md](.mstar/specs/novel-writing/workflow-profile.md) | -| Outline | Workspace, Canvas, Manuscript, Moment (layer) | [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md) | +| Outline | Workspace, Canvas, Manuscript, Moment (layer) | [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md) | ### Compute & AI Domain | Term | Related concepts | Spec doc | |------|-----------------|----------| -| Compute | Preset, WASM module, Capability Registry | [compute-module-abi.md](.mstar/specs/compute-module-abi.md) | -| Run | Compute, Module, Accept, Discard, Compute result | [daemon-api-surface-conventions.md](.mstar/specs/daemon-api-surface-conventions.md) | -| Compute result | Run, Timeline, Accept, Computable | [entity-scope-model.md](.mstar/specs/entity-scope-model.md) | -| Preset | Compute, Orchestration, Capability | [orchestration-engine.md](.mstar/specs/orchestration-engine.md) | -| Creator Memory | Creator, SOUL I/O, Character (distinct SOUL/Memory bearer — roadmap) | [creator-workflow.md](.mstar/specs/creator-workflow.md) | -| Moment Context Assembly | Scope, KnowledgeEntry, Creator Memory (≠ Timeline Moment layer) | [local-runtime-boundary.md](.mstar/specs/local-runtime-boundary.md) | +| Compute | Preset, WASM module, Capability Registry | [compute-module-abi.md](.mstar/specs/compute/compute-module-abi.md) | +| Run | Compute, Module, Accept, Discard, Compute result | [daemon-api-surface-conventions.md](.mstar/specs/runtime/daemon-api-surface-conventions.md) | +| Compute result | Run, Timeline, Accept, Computable | [entity-scope-model.md](.mstar/specs/architecture/entity-scope-model.md) | +| Preset | Compute, Orchestration, Capability | [orchestration-engine.md](.mstar/specs/orchestration/orchestration-engine.md) | +| Creator Memory | Creator, SOUL I/O, Character (distinct SOUL/Memory bearer — roadmap) | [creator-workflow.md](.mstar/specs/creator/creator-workflow.md) | +| Moment Context Assembly | Scope, KnowledgeEntry, Creator Memory (≠ Timeline Moment layer) | [local-runtime-boundary.md](.mstar/specs/architecture/local-runtime-boundary.md) | | Quality Loop | Findings, Review, Knowledge Loop | [novel-writing/quality-loop.md](.mstar/specs/novel-writing/quality-loop.md) | | Knowledge Loop | KnowledgeEntry, SourceAnchor, Quality Loop | [novel-writing/quality-loop.md](.mstar/specs/novel-writing/quality-loop.md) | @@ -289,23 +289,23 @@ Paths are relative to the repo root. Each entry links the term to its authoritat | Term | Related concepts | Spec doc | |------|-----------------|----------| -| ACP | Agent Host, Daemon Runtime | [acp-client-tech-spec.md](.mstar/specs/acp-client-tech-spec.md) | -| Agent Host | ACP, Capability, Daemon Runtime | [agent-host.md](.mstar/specs/agent-host.md) | -| Hosted Execution Owner | Engine epoch, Confirmed close, Agent Host, Local Database | [rust-core-service-boundary.md](.mstar/specs/rust-core-service-boundary.md) | -| Engine epoch | Hosted Execution Owner, Confirmed close, Run (run identity) | [orchestration-engine.md](.mstar/specs/orchestration-engine.md) | -| Confirmed close | Hosted Execution Owner, Engine epoch, Local Database | [rust-core-service-boundary.md](.mstar/specs/rust-core-service-boundary.md) | -| Daemon Runtime | Local Database, Agent Host, Daemon API | [daemon-runtime.md](.mstar/specs/daemon-runtime.md) | -| Daemon API | Daemon Runtime, Web UI, CLI, JSON Schema | [daemon-api-surface-conventions.md](.mstar/specs/daemon-api-surface-conventions.md) | -| Connect Host | Daemon API, ACP, FL-R / DF-72 | [spoke-adapter-architecture.md](.mstar/specs/spoke-adapter-architecture.md) | -| Local Database | SQLite, World KB, Orchestration state | [local-db-schema.md](.mstar/specs/local-db-schema.md) | -| JSON Schema (Wire Contracts) | schemas/, codegen, nexus-contracts | [schemas-directory-layout.md](.mstar/specs/schemas-directory-layout.md) | -| Workspace (Canvas) | Canvas, Outline, Manuscript | [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md) | -| Web UI | Desktop Shell, Daemon Runtime, NexusClient | [web-ui.md](.mstar/specs/web-ui.md) | -| Entrance | Web UI, Desktop Shell, Creator (orthogonal) | [web-ui.md](.mstar/specs/web-ui.md); [desktop-shell.md](.mstar/specs/desktop-shell.md) | -| Desktop Shell | Web UI, Sidecar, Tauri IPC | [desktop-shell.md](.mstar/specs/desktop-shell.md) | -| Setup Wizard | Desktop Shell, Daemon Runtime, ACP Agent Detection | [desktop-shell.md](.mstar/specs/desktop-shell.md) | -| ACP Agent Detection | Desktop Shell, Daemon API, ACP | [desktop-shell.md](.mstar/specs/desktop-shell.md) | -| Profile Switcher | Web UI, Creator | [web-ui.md](.mstar/specs/web-ui.md) | +| ACP | Agent Host, Daemon Runtime | [acp-client-tech-spec.md](.mstar/specs/agents/acp-client-tech-spec.md) | +| Agent Host | ACP, Capability, Daemon Runtime | [agent-host.md](.mstar/specs/agents/agent-host.md) | +| Hosted Execution Owner | Engine epoch, Confirmed close, Agent Host, Local Database | [rust-core-service-boundary.md](.mstar/specs/architecture/rust-core-service-boundary.md) | +| Engine epoch | Hosted Execution Owner, Confirmed close, Run (run identity) | [orchestration-engine.md](.mstar/specs/orchestration/orchestration-engine.md) | +| Confirmed close | Hosted Execution Owner, Engine epoch, Local Database | [rust-core-service-boundary.md](.mstar/specs/architecture/rust-core-service-boundary.md) | +| Daemon Runtime | Local Database, Agent Host, Daemon API | [daemon-runtime.md](.mstar/specs/archived/daemon-runtime.md) | +| Daemon API | Daemon Runtime, Web UI, CLI, JSON Schema | [daemon-api-surface-conventions.md](.mstar/specs/runtime/daemon-api-surface-conventions.md) | +| Connect Host | Daemon API, ACP, FL-R / DF-72 | [spoke-adapter-architecture.md](.mstar/specs/architecture/spoke-adapter-architecture.md) | +| Local Database | SQLite, World KB, Orchestration state | [local-db-schema.md](.mstar/specs/runtime/local-db-schema.md) | +| JSON Schema (Wire Contracts) | schemas/, codegen, nexus-contracts | [schemas-directory-layout.md](.mstar/specs/architecture/schemas-directory-layout.md) | +| Workspace (Canvas) | Canvas, Outline, Manuscript | [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md) | +| Web UI | Desktop Shell, Daemon Runtime, NexusClient | [web-ui.md](.mstar/specs/surfaces/web-ui.md) | +| Entrance | Web UI, Desktop Shell, Creator (orthogonal) | [web-ui.md](.mstar/specs/surfaces/web-ui.md); [desktop-shell.md](.mstar/specs/surfaces/desktop-shell.md) | +| Desktop Shell | Web UI, Sidecar, Tauri IPC | [desktop-shell.md](.mstar/specs/surfaces/desktop-shell.md) | +| Setup Wizard | Desktop Shell, Daemon Runtime, ACP Agent Detection | [desktop-shell.md](.mstar/specs/surfaces/desktop-shell.md) | +| ACP Agent Detection | Desktop Shell, Daemon API, ACP | [desktop-shell.md](.mstar/specs/surfaces/desktop-shell.md) | +| Profile Switcher | Web UI, Creator | [web-ui.md](.mstar/specs/surfaces/web-ui.md) | --- diff --git a/DESIGN.md b/DESIGN.md index 9c2a776e8..c617b7e4e 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -440,7 +440,7 @@ Nexus is a **precision creative tool**: a neutral workbench with clear boundarie This light/default frontmatter and [DESIGN.dark.md](DESIGN.dark.md) are the sole token authority. `version: 0.5.0` is this repository's design-contract revision, continuing its existing schema: nested component recipes, semantic `rounded` keys, `space-*` steps, and scalar typography metrics are intentional. Do not flatten/rename them to match an external template. Every frontmatter key exists in both themes; only values differ. Level 3 describes specification completeness, not a claim of rendered QA. -The implementation contract and complete Studio inventory live in [.mstar/specs/design-studio.md](.mstar/specs/design-studio.md). No app-specific palette, shadow table, font stack, or live token override is allowed. +The implementation contract and complete Studio inventory live in [.mstar/specs/surfaces/design-studio.md](.mstar/specs/surfaces/design-studio.md). No app-specific palette, shadow table, font stack, or live token override is allowed. ## Design Concept — Precision Creative Tool @@ -586,7 +586,7 @@ Existing editor, data-table, context-menu, desktop-window-chrome, app-menu, nati ## Implementation Mapping -One pipeline: DESIGN pair → shared token projection → shared Tailwind utilities and existing brand projections → public primitives → Studio and web consumers. Full projection/compiler contract: [Studio spec §3.5](.mstar/specs/design-studio.md#35-token-projection-contract). Shared `:root` and `.dark` are the only theme value layers. Pair view uses isolated documents loading the **same** entrypoint and CSS, not nested `.dark`/light-reset subtrees. +One pipeline: DESIGN pair → shared token projection → shared Tailwind utilities and existing brand projections → public primitives → Studio and web consumers. Full projection/compiler contract: [Studio spec §3.5](.mstar/specs/surfaces/design-studio.md#35-token-projection-contract). Shared `:root` and `.dark` are the only theme value layers. Pair view uses isolated documents loading the **same** entrypoint and CSS, not nested `.dark`/light-reset subtrees. All existing CSS names and Tailwind utility keys are retained, including historical structural names under `--color-*`; do not rename them while web edits are excluded. New missing color, typography and brand-step projections follow the documented mapping. Existing shadow names remain projections of the elevation scale, not duplicated shadow values. `brandColors` literal values are generated light snapshots; `--nexus-brand-*` and `--color-*` resolve per theme. diff --git a/STRATEGY.md b/STRATEGY.md index 831136584..c7b3c5830 100644 --- a/STRATEGY.md +++ b/STRATEGY.md @@ -8,9 +8,9 @@ | Pillar | Means (developer + author) | Maps to in the codebase | |--------|-------------------------|-------------------------| -| **Harness** | How developers *and* authors harness AI agents: presets, orchestration, capability routing, skills. Developers configure and author this service; authors consume named modes without operator chrome. | `crates/nexus-orchestration/` + `crates/nexus-agent-host/` + `crates/nexus-acp-host/` + capability registry + presets. Surfaced in UI as **Harness** — the user-visible pillar-entry rename **Strategy / Strategies → Harness** landed in V1.156 P3 (closes `DF-V1122-HARNESS-RENAME`); **Preset stays** as the mechanism name under Harness (product lock PD-4; durable authority: [web-ui.md](.mstar/specs/web-ui.md) §29.4). Internal identifiers (route `/strategies`, `CanvasSurfaceKind = 'strategy'`, `preset` wire fields, CSS classes, hook names) stay unchanged. Specs: [orchestration-engine.md](.mstar/specs/orchestration-engine.md), [agent-host.md](.mstar/specs/agent-host.md), [capability-registry.md](.mstar/specs/capability-registry.md). | -| **Canvas** | Spatial steering for the reference creator surface — **Timeline-centric World building** as the hero author entry. Timeline is **three layers** — **Brief** / **Narrative** / **Moment** — **World Timeline** = Brief+Narrative (Brief-led); **Work Timeline** = Narrative+Moment (Moment-led peer; Work entry stays Outline). Strategy canvas is the developer explainability surface for preset orchestration. | `apps/web` React Flow canvas surfaces (`CanvasSurfaceKind = "strategy" \| "outline" \| "world-kb-entities" \| "world-kb-relationships" \| "timeline" \| "work-timeline"`). Timeline is the default **World-entry** surface (V1.122; default layer Brief when data exists from V1.123); Work entry stays Outline (V1.118); Work Timeline is a peer from V1.123. Spec: [canvas-strategy-surface.md](.mstar/specs/canvas-strategy-surface.md). | -| **Computable** | The WASM layer that makes worlds *react* — combat, dice, graph computation, integrator modules. Developers author modules via the official SDK; authors run installed modules (review-then-apply). | Native WASM host (`wasmtime`) + compute-module ABI + combat-engine preset (shipped V1.62; foundation V1.114). Specs: [compute-module-abi.md](.mstar/specs/compute-module-abi.md), [wasm-host.md](.mstar/specs/wasm-host.md). | +| **Harness** | How developers *and* authors harness AI agents: presets, orchestration, capability routing, skills. Developers configure and author this service; authors consume named modes without operator chrome. | `crates/nexus-orchestration/` + `crates/nexus-agent-host/` + `crates/nexus-acp-host/` + capability registry + presets. Surfaced in UI as **Harness** — the user-visible pillar-entry rename **Strategy / Strategies → Harness** landed in V1.156 P3 (closes `DF-V1122-HARNESS-RENAME`); **Preset stays** as the mechanism name under Harness (product lock PD-4; durable authority: [web-ui.md](.mstar/specs/surfaces/web-ui.md) §29.4). Internal identifiers (route `/strategies`, `CanvasSurfaceKind = 'strategy'`, `preset` wire fields, CSS classes, hook names) stay unchanged. Specs: [orchestration-engine.md](.mstar/specs/orchestration/orchestration-engine.md), [agent-host.md](.mstar/specs/agents/agent-host.md), [capability-registry.md](.mstar/specs/agents/capability-registry.md). | +| **Canvas** | Spatial steering for the reference creator surface — **Timeline-centric World building** as the hero author entry. Timeline is **three layers** — **Brief** / **Narrative** / **Moment** — **World Timeline** = Brief+Narrative (Brief-led); **Work Timeline** = Narrative+Moment (Moment-led peer; Work entry stays Outline). Strategy canvas is the developer explainability surface for preset orchestration. | `apps/web` React Flow canvas surfaces (`CanvasSurfaceKind = "strategy" \| "outline" \| "world-kb-entities" \| "world-kb-relationships" \| "timeline" \| "work-timeline"`). Timeline is the default **World-entry** surface (V1.122; default layer Brief when data exists from V1.123); Work entry stays Outline (V1.118); Work Timeline is a peer from V1.123. Spec: [canvas-strategy-surface.md](.mstar/specs/surfaces/canvas-strategy-surface.md). | +| **Computable** | The WASM layer that makes worlds *react* — combat, dice, graph computation, integrator modules. Developers author modules via the official SDK; authors run installed modules (review-then-apply). | Native WASM host (`wasmtime`) + compute-module ABI + combat-engine preset (shipped V1.62; foundation V1.114). Specs: [compute-module-abi.md](.mstar/specs/compute/compute-module-abi.md), [wasm-host.md](.mstar/specs/compute/wasm-host.md). | **Spine vs projection** (locked product model — both audiences): **World + Timeline + KnowledgeEntry + Fork** are the *spine* (truth of the narrative universe the service stores and Connect serves); **Work + Outline + Manuscript** are *projections* (the authoring plan and prose bound to a World). Timeline is the World's *when* axis at three scales (Brief · Narrative · Moment); Outline is the Work's structural projection; Work Timeline is the Work's when-axis peer (Narrative · Moment). Under the Actor model, KnowledgeEntry stays **one spine primitive with exactly one canonical owner scope** — World, Character, or ActorWorldBinding. **v1.184 shipped** Character and ActorWorldBinding owner scopes alongside World-owned KE; World remains the pre-Actor default ([CONCEPTS.md](CONCEPTS.md) § *KnowledgeEntry*). Dual authoring defaults: **World first for World building (Timeline, Brief-led); Work first for chapter writing (Outline), with Work Timeline for scene precision.** See [CONCEPTS.md](CONCEPTS.md) § *Three Pillars* and § *Brief* / *Narrative* / *Moment*. @@ -21,7 +21,7 @@ - **Creator** — *conducts* the story: the god/orchestrator/narrative driver and operational owner. Carries SOUL + Memory and holds omniscient read over all KnowledgeEntries in every World it owns (including creator-only facts). This is the shipped `creator_id` identity aggregate; its storage and execution remain byte-stable. - **Character** — *lives* the story: a durable, Creator-owned identity with its own SOUL, Memory, ToM (built additively on the V1.164–V1.166 l5 MindState/belief/observation foundation), and image/persona assets. A Character enters **one or more** Worlds only through explicit `ActorWorldBinding`s — never implicitly, and no World KB is ever copied per Character. Character creation establishes an initial binding atomically; an active Character never has zero active bindings, so removal of its last active binding rejects with zero mutation; transitioning a Character out of active state is a separate later lifecycle contract (explicit archive/restore, **shipped in v1.185**), never an implicit effect of binding removal. -**Viewpoint** is subordinate execution context paired with an `ActorRef` (`{world_id, optional binding_id/branch_id/event_id}` — it does not repeat an actor id; Character execution requires the binding id, Creator omits it), not identity. One Agent Host / runtime / provider plane serves both kinds; Character sessions execute under the owning Creator's admission boundary with isolated conversation histories. No consumption end changes: still no first-party player (PD-09), no second runtime, no companion app. Outward line: **Nexus Actors are who can think and act — Creators conduct the story; Characters live it.** Durable authority: [actor-product-model.md](.mstar/specs/actor-product-model.md) (accepted product direction — v1.184 stages shipped; v1.185 edit/archive/content/`--remember` shipped, PR #241). Vocabulary: [CONCEPTS.md](CONCEPTS.md) § *Actors & Narrative Identity*. +**Viewpoint** is subordinate execution context paired with an `ActorRef` (`{world_id, optional binding_id/branch_id/event_id}` — it does not repeat an actor id; Character execution requires the binding id, Creator omits it), not identity. One Agent Host / runtime / provider plane serves both kinds; Character sessions execute under the owning Creator's admission boundary with isolated conversation histories. No consumption end changes: still no first-party player (PD-09), no second runtime, no companion app. Outward line: **Nexus Actors are who can think and act — Creators conduct the story; Characters live it.** Durable authority: [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) (accepted product direction — v1.184 stages shipped; v1.185 edit/archive/content/`--remember` shipped, PR #241). Vocabulary: [CONCEPTS.md](CONCEPTS.md) § *Actors & Narrative Identity*. ## What we build @@ -52,7 +52,7 @@ Shared: local-first privacy; harness the user's own ACP/native agents; structure - **A general-purpose note-taking app** — narrative orchestration + reference authoring, not generic notes - **A competing IDE or editor** — we integrate with the user's tools and agents, not replace them - **A new first-party player app for third-party users** (PD-09) — partners ship their UI; we ship runtime + Connect -- **A second runtime, companion Character app, NPC swarm, or per-Character copied World KB** (Actor product lock, 2026-09-04 — [actor-product-model.md](.mstar/specs/actor-product-model.md)) — Characters are an Actor kind executed by the one Agent Host under the owning Creator's admission boundary; not a new process plane or player surface (the PD-09 no-first-party-player stance above is unchanged) +- **A second runtime, companion Character app, NPC swarm, or per-Character copied World KB** (Actor product lock, 2026-09-04 — [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md)) — Characters are an Actor kind executed by the one Agent Host under the owning Creator's admission boundary; not a new process plane or player surface (the PD-09 no-first-party-player stance above is unchanged) - **A general-purpose MCP server** — DF-49 (V1.79) cancelled the standalone MCP server; **reversed 2026-08-24 (user decision)** for a scoped **tools-only MCP exposure surface**: nexus serves `tools/list` + @@ -145,11 +145,11 @@ The rows below are the durable decision history, recorded as written on their da | V1.168 — Native host provider series: external protocol clients + dsh-native | **Context:** Nexus owned vendor wire parsers for the two native Harness rails (`claude --print` line stream; `codex exec --json` hand-rolled JSONL) — brittle under weekly CLI drift; no first-party DeepSeek Harness provider. **Decision (grill-me lock):** complete replace, not a second stack — `claude-native` internals become `claude-codes` (stream-json) and `codex-native` becomes `codex-codes` (**app-server** JSON-RPC), keeping `ProviderAdapter`/`HostEvent`/provider ids/discovery; decode-drift contract locked (unknown variant skip vs typed-decode/stream-abort → single terminal `OpFailed`; no capability raises); new `dsh-native` provider driven by crates.io `deepseek-harness-sdk` with PATH/`DSH_RUNTIME_BIN` discovery and an honest `dsh_limited` descriptor (no incremental streaming/cancel on the SDK surface). QC caught and fix-waved real reliability defects (provider-global lock across frame reads, 180 s frame-gap timeout, stale turn terminal poisoning the next turn, env-route scan invisibility). ACP-first rail unchanged. `wire_contracts_changed: false`. | V1.168 (Aug 2026) | | PD-11 — Dual-audience, developer-first pivot | **Context:** 2026-08-20 user-locked direction. Developers are the primary audience; the first-party authoring app is the reference creator surface. Research: pivot product-direction report, technical-feasibility report, and decision lock (2026-08-20 research package; held in the local harness research archive, not tracked in-repo). **Decision:** STRATEGY vision = local-first narrative-orchestration platform; three consumption ends (CLI+Daemon API / Create layout / nexus-runtime+Connect per PD-09); official compute-module SDK + User-layer entrance split (`developer` \| `content-creator`, orthogonal to agent-layer Creator profiles); no new first-party player, no MCP server (DF-49), no user-authored capability ABI before V1.5+ (DR-10); DF-81 deprioritized. First slice = V1.170 A+B. | V1.170 (2026-08-20) | | DF-49 reversed: tools-only MCP exposure surface | **Context:** ACP wire has no client→agent tool-registration API; native CLI provider adapters pin `structured_tool_calls: false` — the integrator journey (register custom tools → reasoning agents use them) had no viable provider-native face. **Decision (2026-08-24, user):** nexus serves a scoped MCP server (official `rmcp` SDK, stdio transport first; streamable HTTP deferred) exposing the full registry (builtin + user + peer tools) through the single dispatch spine; consumers = any MCP client (ACP `newSession.mcp_servers`, native CLI `--mcp-config`, third-party tools). Supersedes V1.79 DF-49 cancellation rationale for this scope only. | 2026-08-24 (V1.174) | -| First-class Actor product model — Actor as cross-cutting identity primitive | **Context:** the earlier same-day Character Viewpoint-as-identity direction (2026-09-04) encoded Viewpoint as identity and Character as an existing World-scoped `KnowledgeEntry(block_type=character)`; the user rejected that direction — Character must be a durable first-class identity, not lore. **Decision:** lock **Actor** as the cross-cutting narrative identity primitive — *who can think and act* — with `ActorRef = Creator | Character` (closed v1 sum; not a unified actors-table commitment): Creators conduct the story (SOUL+Memory, omniscient KE read over owned Worlds, shipped operational `creator_id` owner); Characters live it (own SOUL+Memory+ToM on the V1.164–166 l5 foundation + image/persona assets; enter **one or more** Worlds via explicit `ActorWorldBinding`s — creation establishes an initial binding atomically, an active Character never has zero active bindings, and last-binding removal must fail or transition the Character out of active state per the later lifecycle contract; one KnowledgeEntry primitive with exactly one canonical owner scope — World-owned KE stays World-local, Character-owned KE is shared explicitly across that Character's bindings without copying, ActorWorldBinding-owned KE is isolated to that World life); Viewpoint demoted to subordinate execution context; one Agent Host/runtime; existing Creator storage byte-stable and existing character KEs remain WorldSheets. Supersedes the same-day Viewpoint-as-identity direction; no fourth pillar, second runtime, companion app, or first-party player. Accepted 2026-09-04; **v1.184 shipped** the identity/binding/knowledge/execution/memory/ToM vertical (PR [#240](https://github.com/42ch-dev/nexus/pull/240)); **v1.185** developer maintenance (edit/archive, WorldSheet, KE content, `--remember`) is **not shipped**. Durable authority: [actor-product-model.md](.mstar/specs/actor-product-model.md). | 2026-09-04; honesty 2026-09-06 | +| First-class Actor product model — Actor as cross-cutting identity primitive | **Context:** the earlier same-day Character Viewpoint-as-identity direction (2026-09-04) encoded Viewpoint as identity and Character as an existing World-scoped `KnowledgeEntry(block_type=character)`; the user rejected that direction — Character must be a durable first-class identity, not lore. **Decision:** lock **Actor** as the cross-cutting narrative identity primitive — *who can think and act* — with `ActorRef = Creator | Character` (closed v1 sum; not a unified actors-table commitment): Creators conduct the story (SOUL+Memory, omniscient KE read over owned Worlds, shipped operational `creator_id` owner); Characters live it (own SOUL+Memory+ToM on the V1.164–166 l5 foundation + image/persona assets; enter **one or more** Worlds via explicit `ActorWorldBinding`s — creation establishes an initial binding atomically, an active Character never has zero active bindings, and last-binding removal must fail or transition the Character out of active state per the later lifecycle contract; one KnowledgeEntry primitive with exactly one canonical owner scope — World-owned KE stays World-local, Character-owned KE is shared explicitly across that Character's bindings without copying, ActorWorldBinding-owned KE is isolated to that World life); Viewpoint demoted to subordinate execution context; one Agent Host/runtime; existing Creator storage byte-stable and existing character KEs remain WorldSheets. Supersedes the same-day Viewpoint-as-identity direction; no fourth pillar, second runtime, companion app, or first-party player. Accepted 2026-09-04; **v1.184 shipped** the identity/binding/knowledge/execution/memory/ToM vertical (PR [#240](https://github.com/42ch-dev/nexus/pull/240)); **v1.185** developer maintenance (edit/archive, WorldSheet, KE content, `--remember`) is **not shipped**. Durable authority: [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md). | 2026-09-04; honesty 2026-09-06 | ### Superseded by the delivered architecture (v1.192–v1.193) -The rows above are that history, not the current architecture. v1.192 delivered the Electron desktop cutover and v1.193 retired the integrated local host; the current owners are the Electron desktop host, the direct-core `nexus42` CLI cohort, the standalone TypeScript service as the HTTP host for browser/Electron, and the independent `nexus-runtime` Connect host ([rust-core-service-boundary.md](.mstar/specs/rust-core-service-boundary.md)). +The rows above are that history, not the current architecture. v1.192 delivered the Electron desktop cutover and v1.193 retired the integrated local host; the current owners are the Electron desktop host, the direct-core `nexus42` CLI cohort, the standalone TypeScript service as the HTTP host for browser/Electron, and the independent `nexus-runtime` Connect host ([rust-core-service-boundary.md](.mstar/specs/architecture/rust-core-service-boundary.md)). | Historical entry | Superseded by | |------------------|---------------| @@ -158,6 +158,6 @@ The rows above are that history, not the current architecture. v1.192 delivered | Desktop shell (`apps/desktop`) via Tauri v2 (V1.66) | v1.192 delivered the Electron host `apps/desktop-electron` and retired the Tauri composition; exactly one desktop host ships. | | Local API Trust-Boundary Hardening (V1.86) | Historical host framing — the retired daemon host. The origin-admission discipline is re-owned by the current hosts: the TS service's `checkOrigin` allowlist and Electron's exact-origin CSP and IPC sender checks. | | Rows naming daemon HTTP routes, `nexus-daemon-runtime`, the Daemon API or the daemon-served SPA — e.g. V1.92, V1.148, V1.151, V1.152, V1.162, V1.163, V1.165, V1.166, and PD-11's "CLI+Daemon API" | Records of the retired host. Retained families now call the Rust authority directly, or through the standalone TS service for browser/Electron; Connect serves third-party integrators. PD-11's three consumption ends stand — only its developer-surface naming changed. | -| "First-class Actor product model" row — "**v1.185** developer maintenance (edit/archive, WorldSheet, KE content, `--remember`) is **not shipped**" | A record-time statement: v1.185 shipped that developer maintenance loop (PR #241). Durable authority: [actor-product-model.md](.mstar/specs/actor-product-model.md) §11. | +| "First-class Actor product model" row — "**v1.185** developer maintenance (edit/archive, WorldSheet, KE content, `--remember`) is **not shipped**" | A record-time statement: v1.185 shipped that developer maintenance loop (PR #241). Durable authority: [actor-product-model.md](.mstar/specs/architecture/actor-product-model.md) §11. | Retained uses of *daemon* in the rows above are wire and configuration vocabulary — `/v1/daemon/*` paths, `NEXUS_DAEMON_ALLOWED_ORIGINS`, the desktop host's service-status vocabulary — and never a launch route for a retired Rust daemon. diff --git a/apps/design-studio/AGENTS.md b/apps/design-studio/AGENTS.md index 9780210ce..b928ddcaf 100644 --- a/apps/design-studio/AGENTS.md +++ b/apps/design-studio/AGENTS.md @@ -13,8 +13,8 @@ Parent rules: [`../AGENTS.md`](../AGENTS.md) (apps placement), root [`AGENTS.md` - Design tokens: repo-root [`DESIGN.md`](../../DESIGN.md) + [`DESIGN.dark.md`](../../DESIGN.dark.md) only - CSS projection: [`@nexus/design-tokens`](../../tooling/design-tokens) (`tokens.css` + Tailwind preset) — shared with `apps/web` -- Normative spec: [`.mstar/specs/design-studio.md`](../../.mstar/specs/design-studio.md) -- Import tiers and source categories: [`.mstar/specs/design-studio.md`](../../.mstar/specs/design-studio.md) §3.2, §7.5 +- Normative spec: [`.mstar/specs/surfaces/design-studio.md`](../../.mstar/specs/surfaces/design-studio.md) +- Import tiers and source categories: [`.mstar/specs/surfaces/design-studio.md`](../../.mstar/specs/surfaces/design-studio.md) §3.2, §7.5 ## Import boundaries (HARD) @@ -35,7 +35,7 @@ Design Studio and `apps/web` use distinct import source categories. Do not treat - `@web-*` aliases remain valid; V1.128+ success is **clarity**, not mass migration into `@42ch/nexus-ui`. - Promote only through the studio-first workflow and an explicit plan promotion list entry. -Surfaces pages label each section with badges (`surface-source-badge-*` test ids). Source classification: [`.mstar/specs/design-studio.md`](../../.mstar/specs/design-studio.md) §7.5. +Surfaces pages label each section with badges (`surface-source-badge-*` test ids). Source classification: [`.mstar/specs/surfaces/design-studio.md`](../../.mstar/specs/surfaces/design-studio.md) §7.5. ### Allowed @@ -99,7 +99,7 @@ No daemon or Tauri required. - Theme toggle: `class` strategy on `` — mirrors web `theme-provider` behavior - Read-only gallery — no YAML write-back, no localStorage token overrides - App chrome shows **Read-only · edit `DESIGN.md`** (repo-root SSOT helper) -- Voice & Content and Surfaces fixture strings: [`.mstar/specs/design-studio.md`](../../.mstar/specs/design-studio.md) §7.4–§7.5 — sourced from DESIGN § Voice & Content and shipped product copy +- Voice & Content and Surfaces fixture strings: [`.mstar/specs/surfaces/design-studio.md`](../../.mstar/specs/surfaces/design-studio.md) §7.4–§7.5 — sourced from DESIGN § Voice & Content and shipped product copy - Canvas surfaces fixture mirrors Outline + Strategy + WorldKB + World Timeline + Work Timeline node chrome, plus Global Timeline list chrome, Layer breadcrumb, and shared conflict-modal chrome (V1.124 P2). ## Audiences @@ -111,7 +111,7 @@ No daemon or Tauri required. | Brand / VI reviewers | Confirm logo usage, clear space, and theme.css alignment | | Authors (local Web UI users) | **Not in scope** — studio is not bundled in `nexus42` or desktop installer | -See [design-studio.md spec §2](../../.mstar/specs/design-studio.md#2-audiences) for audience job-to-be-done detail. +See [design-studio.md spec §2](../../.mstar/specs/surfaces/design-studio.md#2-audiences-and-contributor-jobs) for audience job-to-be-done detail. ## Tests diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.md index e8a3ba803..47ae58ab4 100644 --- a/apps/web/AGENTS.md +++ b/apps/web/AGENTS.md @@ -21,7 +21,7 @@ Parent rules: [`../../AGENTS.md`](../../AGENTS.md) (repo), ## SSOT & authority - **Design tokens**: Root [`DESIGN.md`](../../DESIGN.md) + [`DESIGN.dark.md`](../../DESIGN.dark.md) are the **sole normative SSOT** (Production completeness). Shared CSS variables + Tailwind preset live in `tooling/design-tokens` (`@nexus/design-tokens`). `src/index.css` + `tailwind.config.ts` *consume* them via `@import '@nexus/design-tokens/tokens.css'` and the shared preset; they do not invent tokens. If a token you need is missing, **report** it to the architect — do not fabricate a value. -- **Product contract**: [`web-ui.md`](../../.mstar/specs/web-ui.md). +- **Product contract**: [`web-ui.md`](../../.mstar/specs/surfaces/web-ui.md). - **Transport boundary**: the `NexusClient` interface (`src/lib/nexus/types.ts`). Screens must depend only on the interface, never on `fetch`/`window.nexusDesktop` directly — the client factory selects @@ -115,5 +115,5 @@ and consumed by the screens. Remaining gaps the UI adapts around: locale catalogs. Exclude developer-auxiliary surfaces (`apps/design-studio`), test fixtures, and manuscript body text. - **Normative spec:** - [`web-ui.md` §29.16](../../.mstar/specs/web-ui.md) (V1.112 frontend i18n amendments, shipped); the distilled pattern note lives at + [`web-ui.md` §29.16](../../.mstar/specs/surfaces/web-ui.md) (V1.112 frontend i18n amendments, shipped); the distilled pattern note lives at [`.mstar/knowledge/architecture-patterns/web-i18n-pattern.md`](../../.mstar/knowledge/architecture-patterns/web-i18n-pattern.md). diff --git a/crates/nexus-core/AGENTS.md b/crates/nexus-core/AGENTS.md index 74d61404e..b662600ff 100644 --- a/crates/nexus-core/AGENTS.md +++ b/crates/nexus-core/AGENTS.md @@ -9,7 +9,7 @@ Owned transport-neutral World KB service for graph/patch/candidates/changes. ## Actor holder governance (v1.191 P1 — shipped) Core is the admission authority for holder-scoped knowledge; the durable -contract is [holder-governance.md](../../.mstar/specs/holder-governance.md) §§3–5: +contract is [holder-governance.md](../../.mstar/specs/architecture/holder-governance.md) §§3–5: - **Admission, not client input.** `actor_knowledge` builds a private-field non-`Serialize` `AdmittedKnowledgeContext` only after the `Principal`, stored diff --git a/crates/nexus-embedding/AGENTS.md b/crates/nexus-embedding/AGENTS.md index 8c5e722f7..c473b71b4 100644 --- a/crates/nexus-embedding/AGENTS.md +++ b/crates/nexus-embedding/AGENTS.md @@ -2,7 +2,7 @@ Embedding contract crate: the `EmbeddingProvider` trait seam, the embedding identity tuple, and the fail-closed derived-index protocol. Normative spec: -`.mstar/specs/embedding-readiness.md`. +`.mstar/specs/runtime/embedding-readiness.md`. ## Key Rules diff --git a/crates/nexus-knowledge/AGENTS.md b/crates/nexus-knowledge/AGENTS.md index c803ffd3c..7ce7c21cc 100644 --- a/crates/nexus-knowledge/AGENTS.md +++ b/crates/nexus-knowledge/AGENTS.md @@ -65,7 +65,7 @@ the spoke `KnowledgeEntry` wire type for consumers that read it through this cra The domain record and the store traits own the native holder contract; authority stays in `nexus-core` admission, never in a client value (durable -[holder-governance.md](../../.mstar/specs/holder-governance.md) §§1–5): +[holder-governance.md](../../.mstar/specs/architecture/holder-governance.md) §§1–5): - **Native pair.** `KnowledgeEntryRecord.holder_entry_id: Option` / `.disclosure: Option` carry the resolved holder and its disclosure diff --git a/crates/nexus-local-db/AGENTS.md b/crates/nexus-local-db/AGENTS.md index 9e305d6d2..0275d33ca 100644 --- a/crates/nexus-local-db/AGENTS.md +++ b/crates/nexus-local-db/AGENTS.md @@ -19,13 +19,13 @@ Use a **14-digit prefix** when the migration must run **after** existing 14-digi - **Compile-time checked queries only** — use `sqlx::query!()` / `sqlx::query_as!()` for all static SQL. Runtime `sqlx::query()` only for DDL, PRAGMAs, or truly dynamic SQL with a `// SAFETY:` comment. - See [`crates/nexus-daemon-runtime/AGENTS.md`](../nexus-daemon-runtime/AGENTS.md) for full sqlx compile-time macro rules and `.sqlx/` commit conventions. - Do not add local sqlx features beyond what the workspace declares. -- **Pure storage (V1.145 P1b):** this crate is storage-only — DB CRUD primitives (`SqliteKbStore`, `open_pool`, `run_migrations`, CAS helpers). The production adapter (`NexusAdapter`, V1.146 rename) + 6 spoke port impls **moved to `nexus-spoke-adapter/src/adapter/`** (spec §7.4 / §8). `nexus-local-db` has **no `nexus-spoke-adapter` dependency**; the `extensions.nexus` round-trip helpers (`build_extensions_nexus`, `is_known_nexus_key`) are inlined as private local fns in `kb_store.rs` so the legacy INSERT/UPDATE wrappers stay spoke-unaware. See `.mstar/specs/spoke-adapter-architecture.md` §7.4 for the family matrix (production vs stub). -- **Timeline ordering (V1.146 P1):** the former `SqliteNarrativeGateway::get_timeline_ordered` (which called the spoke `order_timeline_events_by_ids` helper via a direct `spoke-operations` dep) was **removed** — it never had a production call site, and the ordered-timeline facet now lives on the spoke-adapter boundary as `NexusAdapter::list_timeline_events_ordered` in `nexus-spoke-adapter` (spec §7.4). `nexus-local-db` no longer depends on `spoke-operations`. See `.mstar/specs/spoke-adapter-architecture.md` §7.4 "Read-path ScopeQuery adoption". +- **Pure storage (V1.145 P1b):** this crate is storage-only — DB CRUD primitives (`SqliteKbStore`, `open_pool`, `run_migrations`, CAS helpers). The production adapter (`NexusAdapter`, V1.146 rename) + 6 spoke port impls **moved to `nexus-spoke-adapter/src/adapter/`** (spec §7.4 / §8). `nexus-local-db` has **no `nexus-spoke-adapter` dependency**; the `extensions.nexus` round-trip helpers (`build_extensions_nexus`, `is_known_nexus_key`) are inlined as private local fns in `kb_store.rs` so the legacy INSERT/UPDATE wrappers stay spoke-unaware. See `.mstar/specs/architecture/spoke-adapter-architecture.md` §7.4 for the family matrix (production vs stub). +- **Timeline ordering (V1.146 P1):** the former `SqliteNarrativeGateway::get_timeline_ordered` (which called the spoke `order_timeline_events_by_ids` helper via a direct `spoke-operations` dep) was **removed** — it never had a production call site, and the ordered-timeline facet now lives on the spoke-adapter boundary as `NexusAdapter::list_timeline_events_ordered` in `nexus-spoke-adapter` (spec §7.4). `nexus-local-db` no longer depends on `spoke-operations`. See `.mstar/specs/architecture/spoke-adapter-architecture.md` §7.4 "Read-path ScopeQuery adoption". ## Holder governance storage (v1.191 P1 — shipped) This crate owns the storage half of the holder contract -([holder-governance.md](../../.mstar/specs/holder-governance.md) §§2–6); policy stays +([holder-governance.md](../../.mstar/specs/architecture/holder-governance.md) §§2–6); policy stays in `nexus-core`: - **Registry.** `src/holders.rs` owns `knowledge_holders`: one row per stored Creator diff --git a/crates/nexus-orchestration/AGENTS.md b/crates/nexus-orchestration/AGENTS.md index 1bad1d350..7ed1bb01f 100644 --- a/crates/nexus-orchestration/AGENTS.md +++ b/crates/nexus-orchestration/AGENTS.md @@ -50,4 +50,4 @@ The validation path should check a preset YAML/bundle for: ## Design Reference -Full design: `.mstar/specs/orchestration-engine.md` (sections 7–9 cover presets, loader, validation). +Full design: `.mstar/specs/orchestration/orchestration-engine.md` (sections 7–9 cover presets, loader, validation). diff --git a/crates/nexus-provider-conformance/AGENTS.md b/crates/nexus-provider-conformance/AGENTS.md index 9bfd0bbaf..a5e2da7d1 100644 --- a/crates/nexus-provider-conformance/AGENTS.md +++ b/crates/nexus-provider-conformance/AGENTS.md @@ -43,4 +43,4 @@ fixture CLIs; this crate stays provider-neutral. ## Design Reference See `.mstar/plans/2026-09-02-v1.180-p0-provider-conformance-runner.md` and -`.mstar/specs/agent-host.md` §3.4. +`.mstar/specs/agents/agent-host.md` §3.4. diff --git a/crates/nexus-spoke-adapter/AGENTS.md b/crates/nexus-spoke-adapter/AGENTS.md index 52e7d39e3..14fdf2fc5 100644 --- a/crates/nexus-spoke-adapter/AGENTS.md +++ b/crates/nexus-spoke-adapter/AGENTS.md @@ -22,9 +22,9 @@ Since V1.141 the crate also flat-re-exports spoke 0.4.0's adapter **port traits ## Authority -- Normative spec: [`specs/spoke-adapter-architecture.md`](../../.mstar/specs/spoke-adapter-architecture.md) (tracked). §7.2 is the authoritative public API surface; §7.3 is the Surface B (ports + orchestrators) surface; §2 is the `extensions.nexus` contract. +- Normative spec: [`specs/architecture/spoke-adapter-architecture.md`](../../.mstar/specs/architecture/spoke-adapter-architecture.md) (tracked). §7.2 is the authoritative public API surface; §7.3 is the Surface B (ports + orchestrators) surface; §2 is the `extensions.nexus` contract. - Upstream types: `spoke-schemas` + `spoke-operations` (crates.io, lockstep exact pin on the **pinned upstream lockstep release** — the version SSOT is the workspace manifest, mirrored by the two root npm pins and `tooling/check-wire-drift.sh::SPOKE_PIN`). -- **Shipped (v1.191 P1):** the lockstep SPOKE release plus complete Actor-holder governance (native `holder_entry_id`/`disclosure`, Creator management vs ActorView admission, `creator_only` cutover) and the production extraction wrapper. Durable contract: [`.mstar/specs/holder-governance.md`](../../.mstar/specs/holder-governance.md). `spoke-connect` stays behind `connect-host` / `connect-client`. +- **Shipped (v1.191 P1):** the lockstep SPOKE release plus complete Actor-holder governance (native `holder_entry_id`/`disclosure`, Creator management vs ActorView admission, `creator_only` cutover) and the production extraction wrapper. Durable contract: [`.mstar/specs/architecture/holder-governance.md`](../../.mstar/specs/architecture/holder-governance.md). `spoke-connect` stays behind `connect-host` / `connect-client`. ## Key rules @@ -38,7 +38,7 @@ Since V1.141 the crate also flat-re-exports spoke 0.4.0's adapter **port traits This crate is the single place where native holder governance crosses the SPOKE wire: - **Exact field mapping.** `KnowledgeEntryRecord.holder_entry_id` → spoke `KnowledgeEntry.owner`, and `.disclosure` → `.disclosure`. No governance value rides in `extensions.nexus`, and the wire `owner` is never a narrative-container id (durable §1, D2). -- **Scoped ports (HARD).** `NexusAdapter::new(pool, KnowledgeReadScope)` requires a validated request-bound scope for every KE load/mutate/query path; `NexusAdapter::new_host(pool)` is tools/metadata only and fails closed on every KE entry point. Relationship/finding/compute expansion filters or rejects hidden operands **before** emitting an id or payload, and a missing scope never widens selection. See `.mstar/specs/holder-governance.md` §4. +- **Scoped ports (HARD).** `NexusAdapter::new(pool, KnowledgeReadScope)` requires a validated request-bound scope for every KE load/mutate/query path; `NexusAdapter::new_host(pool)` is tools/metadata only and fails closed on every KE entry point. Relationship/finding/compute expansion filters or rejects hidden operands **before** emitting an id or payload, and a missing scope never widens selection. See `.mstar/specs/architecture/holder-governance.md` §4. - **Retired legacy key.** Raw input that still carries `extensions.nexus.creator_only` is refused with the stable `legacy_creator_only_unsupported` reason (`false` included) — never folded into governance, never carried as an unknown extra. - **Production extraction wrapper.** `src/extraction.rs` owns `ResolvedExtractionPort` + the native callback and is the only caller of `spoke_operations::adapter::orchestrate_extract`; `ExtractionPort` stays outside `BaselinePorts`/`FullPorts`. The adapter imports neither `nexus-core` nor `nexus-orchestration`. See durable §8. - **Connect manifest.** `src/manifest.rs` declares `ke-ownership` only on the composition that enforces every served family, and never declares `ke-extraction` (remote extract is not served). See durable §9. @@ -55,6 +55,6 @@ Dev-deps mirror the runtime deps so tests can compare wrapper output against the ## V1.146 P5 sweep notes -- The adapter now hosts 13 modules in `src/adapter/` (activation, computable_port, computable_port_stub, finding_port, fork_port, host_manifest_port, knowledge_entry_port, mca_read, mind_state, narrative_read, relation_port, rule_query_port, scope_query_port) plus the free-function conversion seam in `src/conversion/`. See `.mstar/specs/spoke-adapter-architecture.md` §7.4 for the production-vs-stub matrix. +- The adapter now hosts 13 modules in `src/adapter/` (activation, computable_port, computable_port_stub, finding_port, fork_port, host_manifest_port, knowledge_entry_port, mca_read, mind_state, narrative_read, relation_port, rule_query_port, scope_query_port) plus the free-function conversion seam in `src/conversion/`. See `.mstar/specs/architecture/spoke-adapter-architecture.md` §7.4 for the production-vs-stub matrix. - `activation` is the **default-on lore activation engine** (V1.149 / DF-74) — pure match + Relation hop expand; supersedes the V1.146 flag-gated spike. MCA calls the engine; CLI loads hop edges; no matching/hop code in `spoke-operations`. - `build_assemble_packet` exposes the spec §7.2 signature. Spoke's real API takes a `BuildAssemblePacketInput` struct with `&[KnowledgeEntryForAssemble]` and a packet-level `extensions` slot. The wrapper honors §7.2 and wraps internally. See `src/ops.rs` doc comment. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bac73ac8e..1390ad3f2 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -9,9 +9,9 @@ This document is for **orientation and decision-making**. It does not inventory | Product vision & tech rationale | [`STRATEGY.md`](../STRATEGY.md) | | Domain vocabulary | [`CONCEPTS.md`](../CONCEPTS.md) | | Day-to-day commands | [`README.md`](../README.md) → Development; [`CONTRIBUTING.md`](CONTRIBUTING.md) | -| Entity ownership & naming | [`.mstar/specs/entity-scope-model.md`](../.mstar/specs/entity-scope-model.md) | -| Local vs cloud crate rules | [`.mstar/specs/local-cloud-crate-architecture.md`](../.mstar/specs/local-cloud-crate-architecture.md) | -| Local trust / API classes | [`.mstar/specs/local-runtime-boundary.md`](../.mstar/specs/local-runtime-boundary.md), [`.mstar/specs/rust-core-service-boundary.md`](../.mstar/specs/rust-core-service-boundary.md) | +| Entity ownership & naming | [`.mstar/specs/architecture/entity-scope-model.md`](../.mstar/specs/architecture/entity-scope-model.md) | +| Local vs cloud crate rules | [`.mstar/specs/archived/local-cloud-crate-architecture.md`](../.mstar/specs/archived/local-cloud-crate-architecture.md) | +| Local trust / API classes | [`.mstar/specs/architecture/local-runtime-boundary.md`](../.mstar/specs/architecture/local-runtime-boundary.md), [`.mstar/specs/architecture/rust-core-service-boundary.md`](../.mstar/specs/architecture/rust-core-service-boundary.md) | | Per-directory invariants | Root [`AGENTS.md`](../AGENTS.md) and each subtree’s `AGENTS.md` | --- @@ -55,7 +55,7 @@ Cross-language wire shapes start in **`schemas/`** (JSON Schema). Codegen produc - Local-only daemon/orchestration shapes may live under `nexus-contracts` local modules when platform does not observe them; they still must not be redefined in app crates. - After schema edits: validate → codegen → commit schemas and generated output together. -Schema layout and external-consumer boundary: [`.mstar/specs/schemas-directory-layout.md`](../.mstar/specs/schemas-directory-layout.md), [`.mstar/knowledge/schemas-external-consumer-boundary.md`](../.mstar/knowledge/schemas-external-consumer-boundary.md). +Schema layout and external-consumer boundary: [`.mstar/specs/architecture/schemas-directory-layout.md`](../.mstar/specs/architecture/schemas-directory-layout.md), [`.mstar/specs/architecture/schemas-external-consumer-boundary.md`](../.mstar/specs/architecture/schemas-external-consumer-boundary.md). --- @@ -167,8 +167,8 @@ When designing or reviewing a change: 1. Root [`AGENTS.md`](../AGENTS.md) — repo invariants 2. This file — orientation -3. [`entity-scope-model.md`](../.mstar/specs/entity-scope-model.md) — ownership -4. [`local-cloud-crate-architecture.md`](../.mstar/specs/local-cloud-crate-architecture.md) — line split & forbidden edges +3. [`entity-scope-model.md`](../.mstar/specs/architecture/entity-scope-model.md) — ownership +4. [`local-cloud-crate-architecture.md`](../.mstar/specs/archived/local-cloud-crate-architecture.md) — line split & forbidden edges 5. Domain Master for the subsystem (local-runtime-boundary, rust-core-service-boundary, orchestration, CLI, web-ui, desktop-shell, …) under [`.mstar/specs/`](../.mstar/specs/) Iteration plans and audit compasses record delivery history; they are not architecture SSOT. Prefer Master specs over dated gap tables when deciding what “should” be true. diff --git a/docs/README.md b/docs/README.md index f8d6e2009..7eb988994 100644 --- a/docs/README.md +++ b/docs/README.md @@ -24,4 +24,4 @@ compute, fork + validate). ## Normative sources -The ABI spec stays authoritative for the module contract: [`.mstar/specs/compute-module-abi.md`](../.mstar/specs/compute-module-abi.md). +The ABI spec stays authoritative for the module contract: [`.mstar/specs/compute/compute-module-abi.md`](../.mstar/specs/compute/compute-module-abi.md). diff --git a/docs/mcp-server.md b/docs/mcp-server.md index ac5256c6a..694ab10e7 100644 --- a/docs/mcp-server.md +++ b/docs/mcp-server.md @@ -10,7 +10,7 @@ > features: peer tool registry, shared rmcp bridge core, embedded Model B > server, `VisibilityPolicy`, peer-control lane), composed by the native/TS > consumers. See -> [`.mstar/specs/rust-core-service-boundary.md`](../.mstar/specs/rust-core-service-boundary.md) +> [`.mstar/specs/architecture/rust-core-service-boundary.md`](../.mstar/specs/architecture/rust-core-service-boundary.md) > §3–§4 and [`ARCHITECTURE.md`](ARCHITECTURE.md). `nexus42 mcp serve` **was** a **tools-only** Model Context Protocol (MCP) diff --git a/docs/module-authoring.md b/docs/module-authoring.md index 3c3e19c60..8bcd2f31b 100644 --- a/docs/module-authoring.md +++ b/docs/module-authoring.md @@ -11,7 +11,7 @@ compute is **read-only** — the module never commits state itself (see [Read-only compute](#read-only-compute)). The normative ABI contract is -[`.mstar/specs/compute-module-abi.md`](../.mstar/specs/compute-module-abi.md) — +[`.mstar/specs/compute/compute-module-abi.md`](../.mstar/specs/compute/compute-module-abi.md) — this doc is the authoring reference: the contract at a glance, the `manifest.json` contract (incl. `wasm_sha256`), the allowlist gate, and the operator install. The module-authoring walkthrough lives in @@ -330,4 +330,4 @@ is documented in the - Module guide: [`modules/README.md`](../modules/README.md) — authoring walkthrough + embedding procedure. - Reference implementation: [`modules/basic-combat/`](../modules/basic-combat/). -- ABI spec (normative): [`.mstar/specs/compute-module-abi.md`](../.mstar/specs/compute-module-abi.md). +- ABI spec (normative): [`.mstar/specs/compute/compute-module-abi.md`](../.mstar/specs/compute/compute-module-abi.md). diff --git a/docs/nexus-runtime.md b/docs/nexus-runtime.md index 30b5cdcd9..735284199 100644 --- a/docs/nexus-runtime.md +++ b/docs/nexus-runtime.md @@ -285,4 +285,4 @@ distinct trust role from `identity.key`) and prints the signed wire proof - [Integrator walkthrough](../strategy-samples/README.md) — worked example end to end. - [Docs index](README.md) — all docs. -- ABI spec: [`.mstar/specs/compute-module-abi.md`](../.mstar/specs/compute-module-abi.md). +- ABI spec: [`.mstar/specs/compute/compute-module-abi.md`](../.mstar/specs/compute/compute-module-abi.md). diff --git a/docs/strategy-authoring.md b/docs/strategy-authoring.md index 6e93f9e7f..e6ade57bf 100644 --- a/docs/strategy-authoring.md +++ b/docs/strategy-authoring.md @@ -331,7 +331,7 @@ Once a strategy is installed under `~/.nexus42/presets//`, the **write path is the local service host's strategy canvas API** (`POST /v1/daemon/strategies/…`, served by the Electron/TS service) through the retained CLI leaves (`nexus42 preset patch state|transition|prompt`, V1.175 P1 -— see [cli-spec §6.2G.4](../.mstar/specs/cli-spec.md)): +— see [cli-spec §6.2G.4](../.mstar/specs/cli/cli-spec.md)): ```bash # Patch a state node (rename via --label, or update --description). diff --git a/modules/README.md b/modules/README.md index a89186de8..0d0540a26 100644 --- a/modules/README.md +++ b/modules/README.md @@ -9,7 +9,7 @@ timeline events, new key blocks, battle report). This directory holds their **source**. > Spec context: the normative ABI contract is -> [`.mstar/specs/compute-module-abi.md`](../.mstar/specs/compute-module-abi.md); +> [`.mstar/specs/compute/compute-module-abi.md`](../.mstar/specs/compute/compute-module-abi.md); > the integrator-facing authoring guide is > [`docs/module-authoring.md`](../docs/module-authoring.md). @@ -248,7 +248,7 @@ intentionally: the per-invocation instance is discarded right after the call. - SDK crate: [`nexus-module-sdk/`](nexus-module-sdk/) — the authoring surface. - Authoring guide: [`docs/module-authoring.md`](../docs/module-authoring.md). - ABI spec (normative): - [`.mstar/specs/compute-module-abi.md`](../.mstar/specs/compute-module-abi.md). + [`.mstar/specs/compute/compute-module-abi.md`](../.mstar/specs/compute/compute-module-abi.md). - Host crate: [`crates/nexus-wasm-host/`](../crates/nexus-wasm-host/) — engine, sandbox, host-function ABI, embedded-module loader, registry module. - `compute-module-author` skill: