wishforge-ide/docs/system-design.md
eust-w b47a07e8d2 chore: baseline snapshot of the Codex-delivered code before review
Imports the previously untracked working tree as-is so that the review
changes that follow (requirements -> design -> implementation) can be
reviewed as diffs and reverted if needed. No content changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 13:18:04 +08:00

7.5 KiB

WishForge system design

Status: implementation design and acceptance contract. A component being described here does not mean its live integration has passed. Evidence is tracked separately in acceptance-traceability.md.

Product and boundaries

WishForge is a single-region, multi-tenant commercial development platform. Users submit a wish from the Web workbench, WorkBuddy or Codex. It creates a Web app or changes an existing repository, runs a bounded engineering loop, and delivers to either a managed target or an enrolled customer target. Model credentials are tenant BYOK. The platform's self-evolution uses a separate platform account and budget. Low-risk changes can deploy under existing policy; high-risk changes need a human approval bound to the exact release.

The Web workbench handles wishes, runs, evidence, releases, budgets and approvals. The separate Theia process provides the full IDE framework. A read-only review panel is useful for viewers but must not be represented as the full cloud IDE. Theia/OCT integration has its own acceptance requirements below.

Control, execution and trust

The control plane owns tenant/project authorization, durable run state, policy, credential references, event history and idempotency. PostgreSQL RLS is enforced through a non-superuser application role; an administration connection is used only for migration. JWT tenant claims select a tenant context, while database membership determines actual permission. Connector identities cannot impersonate the human approval channel.

Temporal owns durable scheduling, retry and waiting. Activity handlers execute external work and return evidence; replaying a workflow must not repeat an external side effect. Workers acquire expiring leases with monotonic fencing tokens. Cancellation/revocation invalidates subsequent writes. External commands use idempotency keys and explicit reconciliation after an uncertain outcome.

Each execution gets a separate workspace and a resource/time/token budget. In production, untrusted code runs under Kata on a dedicated node pool, without a Kubernetes API token, host mount or cloud/model master credential. The tool gateway enforces scope and egress. The trusted controller creates jobs; the separate deployer applies approved artifacts. Secret references resolve just in time through the credential broker. Encrypted storage alone is not permission to expose a BYOK secret to an arbitrary process or another tenant.

The trust root includes authorization, tenant separation, budget enforcement, secret issuance, independent verification, audit/attestation and rollback control. Agents can propose changes to that code, but a separately controlled human upgrade channel must approve and release it. Agent-generated evidence is not automatically trusted evidence.

Task loop and release contract

The task loop is clarify → plan → implement → verify → integrate → build → preview → release → accept. Waiting for user input, budget or approval is a durable state, not a worker process sleeping indefinitely. Stage transitions require relevant evidence. A successful build is distinct from a successful deployment, and HTTP health is distinct from user-flow acceptance.

At Run start, pin the project baseline, AgentBundle, tool/runtime version, policy, model route and acceptance specification. A verified commit must equal the built commit. A release binds image digest, architecture, target environment, config version, secret-version references, policy and evidence. A change to any bound input invalidates an existing approval. High-risk examples include permission expansion, schema/data migrations and protected paths; the backend computes risk from trusted change facts rather than trusting a caller's self-classification.

Managed and BYO deployment adapters use the same release contract. BYO enrollment is expiring, target-bound and revocable. The customer-side runner receives only the approved artifact/action. A timeout creates an unknown outcome requiring target readback, not immediate blind redeployment. Keep the preceding stable artifact; rollback verifies the resulting target version and runtime checks. Destructive schema changes require a separate migration/recovery plan rather than an automatic database downgrade.

Self-evolution loop

Task experiences are tenant/project scoped by default. The global meta loop uses platform-owned synthetic/public tasks or explicitly authorized examples. Raw code, logs, prompts and embeddings are not shared across tenants by default. Model training permission is separate from permission to reuse a task example.

The meta loop clusters failures, writes an improvement hypothesis, creates an immutable candidate, builds it, compares it with a fixed baseline, performs side-effect-free shadow replay, then canaries eligible new runs. It can change prompts, tools, orchestration, ordinary platform code and its own generator. It cannot modify its own evaluation gate, authorization or budget while being scored. Retain candidate ancestry and rejected evidence to avoid repeating failed ideas.

The evaluator has development, frozen validation and sealed holdout sets. Outcome tests, paired budgets and independent evidence take precedence over model self- reports. Tenant leakage, privilege escalation and fabricated evidence are hard failures; average quality/cost improvements cannot offset them. A new scoring rubric is a separately reviewed version. Repeated holdout queries are budgeted.

Risk preauthorization applies to evolution too. Eligible low-risk candidates can be promoted automatically after required evidence and minimum observation/sample thresholds; high-risk changes require human review. Existing runs retain their pinned Bundle. A failed candidate stops receiving new work and its capabilities are revoked; rollback selects the previous stable version. Candidate generation and evaluation consume the platform's own credentials and budget.

Cloud IDE and collaboration

Theia 1.76 runs a Node backend and browser frontend, with terminal, editor, file, SCM and debugger extension hosts. The self-hosted OCT 0.3.1 transport provides live collaboration. The gateway must authorize tenant/project/session on every HTTP and WebSocket path. Owners/editors may join editing rooms; viewers use read-only review and receive neither an editing session nor OCT room access.

Workspace metadata records the owner, member ACL, filesystem snapshot, IDE version and room generation. A save barrier locks one source revision for validation and deployment. A debugger has one controller lease; observers cannot send mutating DAP commands. These controls require a gateway/extension integration and are not guaranteed merely by installing Theia/OCT.

OCT rooms are in memory. Restart recovery restores persisted files and membership metadata into a new room generation and asks participants to rejoin. Unsaved collaboration changes may be lost. Production cannot claim lossless recovery until durable CRDT persistence and a recovery test demonstrate it.

Deployment and operational acceptance

infra/compose.yaml is localhost-only development infrastructure with public fixture passwords. The separate deployment adapter also supports enrolled customer Compose targets; those require their own reviewed Runner, credentials and target acceptance. Production needs HA PostgreSQL/PITR, production Temporal, TLS identity services, private S3/registry, reviewed image digests, secret management and actual Kata/CNI verification. Kubernetes files provide guardrails and templates, not proof of installed isolation. Read operations.md for local steps and production boundaries.