SEIF Docs

Architecture

flowchart TB
  subgraph WS[SEIF Context Workstation · C# / .NET 10 / Avalonia]
    Hub[Project Hub] --> Session[ProjectSession<br/>saved design · draft · coordinate]
    Session --> Views[DESIGN · TEST · BUILD · OBSERVE<br/>Browser · Canvas · Mixer · Inspector · Trajectory]
    Session --> EngineClient[ContextEngine client<br/>JSON over stdio]
    Session --> Host[RuntimeHost<br/>loopback child process]
    Advanced[Advanced: SEIF Workspace inspector<br/>Product CLI · product-host · governed action]
  end
  EngineClient --> Engine
  Host --> Server
  subgraph Engine[Context Engine · runtime/engine · Node 24]
    Sources[sources.mjs · git.mjs<br/>folder · Git · file · inline] --> Resolve[resolve.mjs]
    Resolve --> SEIF[(SEIF packages<br/>resolveTurn · selectContextWithPolicy<br/>DagContextRuntime · prepareTurn<br/>EmbeddedProvider · observation wire)]
    Resolve --> Render[render.mjs · budget]
    Build[build.mjs · digest · immutability] --> Tests[tests.mjs]
    Diff[diff.mjs] 
    Trace[trace.mjs]
  end
  Engine --> ProjectFiles[(context-project.json<br/>builds/build-NNNN)]
  Server[server.mjs · seif.context-runtime.v1] --> Resolve
  Server --> Traces[(traces/*.json)]
  Bundle[Runtime bundle<br/>run.sh · bin/node · lib · build] --> Server
  App[Customer application] -- resolve / expand / consumption --> Server

Responsibilities

C# (presentation and orchestration). Workstation.Core holds the typed Context Project model and store, templates, recent projects, the engine and runtime clients, read views over engine JSON (Resolution, LayerState, TestRun, BuildSummary, TraceView), and ProjectSession — the saved design, the non-destructive draft, the coordinate (environment, consumer, objective, preview input), preview/baseline/diff, expansions, tests, builds, runtime and traces. Workstation.Desktop is the native shell: Hub, mode views, Canvas, Inspector editors, dialogs, command palette, keyboard shortcuts, and the in-process acceptance journey. C# never re-implements selection, rendering, budgets or digests.

Context Engine (semantics on SEIF mechanics). Plain ES modules run by the pinned Node binary. One implementation serves design-time preview (cli.mjs), tests, Build validation, the local runtime and exported bundles (server.mjs). Resolution compiles profile rules into the SEIF Context Kernel policy, materializes bounded material, projects facets through DagContextRuntime via the embedded SEIF Application paved road, renders with the consumer's budget and records the canonical Application turn observation. See ADR 002.

Advanced SEIF Workspace inspector. The previous application, unchanged in semantics: bundled seif CLI for Workspace/Product reads, the thin Go product-host for ProductOperation, the Node application-host.mjs for public Application proposal/acceptance contracts. It is reachable only from Advanced. See ADR 001 and integration.md.

Invariants

  • A Context Project, Build, Runtime and Trace are application concepts, not SEIF Protocol ontology; the Workstation is not a semantic owner.
  • Desired (UI/draft) ≠ selected (Context Kernel) ≠ materialized ≠ projected (DagContextRuntime) ≠ rendered (consumer renderer) ≠ consumed (consumer report). Each is computed or reported by its own step; none is inferred.
  • UNKNOWN (applicability, currentness, availability, consumption) is preserved through Mixer, tests, Builds, runtime responses and traces.
  • Sources are read-only data; source connection is not authority. ADR 006 adds an optional tool gateway that validates and delegates declared calls to application-owned HTTP executors. Writes require exact operator approval; backend authorization and domain invariants remain owned by the application. Advanced SEIF effects retain their canonical owner.
  • Path is a locator: project, source, layer and material identities are explicit ids and content digests.
  • Secrets are refused in projects and Builds and redacted in traces; logs carry no content.

Bounds

Sources: 2,000 files, 512 KiB/file, 32 MiB/source, 50,000 Git tree entries. Runtime: 1 MiB bodies, 256 KiB input, 500-trace listing, retention-capped trace store. Canvas: 8 consumers, 12 objectives, 8 profiles, 24 layers, 24 sources, 10 materials per expanded layer. Engine calls: 120 s deadline, 4 MiB responses.

Packaging

The .app contains the self-contained .NET app, runtime/node, runtime/engine, runtime/node_modules/@and2carvalho/*, runtime/examples, licenses, the example project under Resources/Examples, and the Advanced tooling (seif, product-host, application-host.mjs). Exported bundles contain only the runtime subset.

Commercial control plane (0.3.0, extended in 0.4.0)

trust.mjs verifies/signs immutable artifacts; registry-store.mjs owns indexed SQLite/filesystem persistence; control-plane.mjs owns authorization, environment policy, approval and promotion; deployments.mjs owns isolated process execution/health/collection; registry-server.mjs exposes authenticated versioned APIs. regression.mjs compares actual engine behavior over retained corpus obligations. context.mjs provides headless CI. These are Workstation product concepts, not additions to SEIF Protocol authority.

connectors.mjs observes external data; retrieval.mjs ranks eligible material; existing resolve/project/kernel/trace semantics remain the authority for context execution. Native Deploy/Regression/Observe surfaces consume the same APIs as external apps. Python/TypeScript clients are thin instrumentation boundaries. See ADR 003.

Storage and deployment classes define replaceable boundaries, with only real SQLite/filesystem/process implementations shipped. Hosted adapters, SSO and HA remain future. Schema version 1 initializes atomically; newer Registry schema versions refuse startup. Project/Build v1 semantics are preserved and tested.

Investigation and typed decisions (0.5.0)

Workstation.Core/Investigation.cs holds the investigation contract: an explicit InvestigationState projection of one trace (counts, booleans, and only a typed question), InvestigationDecision (goal, panels, optional confidence — no actions), the ITypedDecisionProvider boundary with local rules and an opt-in TypeSafe System One adapter, local subject matching, a credential guard and the validating composer with explicit fallback. WorkstationWindow.Focus.cs renders application-owned panels from the trace itself. See ADR 005 and Investigation.

Runtime context, identities and delivery trust (0.4.0)

flowchart LR
  subgraph Dev[Context development]
    Project[Context Project<br/>sources · providers (requirements) · tests + fixtures] --> Build[Context Build<br/>immutable, signed]
  end
  subgraph Delivery[Context delivery · Registry context-registry.v2]
    Build --> Register[Register · CAS objects]
    Register --> Promote[Promote · regression gate · approval]
    Binding[Deployment Binding rev N<br/>endpoints · secret refs · retention · timeouts] --> Deploy
    Promote --> Deploy[Deploy · readiness · atomic route switch]
  end
  subgraph Ops[Context operations]
    App[Application<br/>scw_app credential] -->|/projects/P/environments/E/context| Route[Stable environment route]
    Route --> Runtime[Context Runtime<br/>exact Build + binding]
    Runtime -->|lookup value only| Provider[(Runtime Context Provider<br/>HTTP · SQLite)]
    Runtime --> Trace[Context Trace<br/>provider provenance · keyed digests]
    Trace --> Search[Dimensional search · reproduction]
  end
  Deploy --> Runtime

Modules: identity.mjs (principal classes, capability catalogue, credentials), registry-server.mjs (route table; every route declares a capability), control-plane.mjs (promotion, approval with optional separation of duties, break-glass, bindings, ingestion, reproduction, audit), bindings.mjs (binding contract, compatibility, secret allowlist, runtime binding file, keyed fingerprints), providers.mjs (provider contract, HTTP and read-only SQLite clients, fixtures, bounds, provenance), deployments.mjs (adapter contract, isolated process adapter, controller: readiness, timeout classes, routing, draining, delivery), registry-store.mjs (schema v2: credentials, CAS objects, trace term dictionary and read models, GC, backup, v1 migration), ci.mjs (pull-request Context CI). Resolution still runs entirely on the existing SEIF mechanics; providers only add candidate material with explicit availability.

Invariants added: APPLICATION IDENTITY ≠ HUMAN IDENTITY; CONSUMER CAPABILITY ≠ RELEASE AUTHORITY; BUILD ≠ DEPLOYMENT BINDING; SOURCE CONNECTOR ≠ RUNTIME CONTEXT PROVIDER; DEPLOYMENT_STARTED ≠ HEALTHY (route moves only after readiness); CAS ≠ AUTHORITY; TRACE INDEX ≠ TRACE AUTHORITY; LIVE ≠ CURRENT (currentness is reported by the provider or items, never assumed). See ADR 004.

Platforms: desktop macOS arm64 (executed); server distribution macOS arm64, Linux x64 and Linux arm64 (executed); desktop Linux/Windows x64 compile only.

Historical investigation (0.6.0)

The capability matrix in historical-baseline.md drove reuse of immutable Builds, the Registry CAS and observation envelopes. historical.mjs derives investigation, source availability, comparison and regression-draft projections; it executes replay through the same resolveContext engine. It never invokes source connectors, live provider clients or domain effects. Historical execution, available observations, new reproduction and candidate correction remain separate objects.

A new request record adds full artifact identity, execution fingerprint, runtime instance and content-expiration instant. execution-identity.mjs hashes the shared portable runtime execution closure and SEIF modules separately from Build content; exported bundles carry that same closure. Existing trace readers accept the additional fields. No Registry schema migration or second material store is required. Legacy missing fields stay UNKNOWN. Only reproduction receipts are newly persisted, using bounded existing records/local operational storage; payloads are omitted.

Temporal comparison joins verified historical and candidate definitions and, when possible, resolves the historical input on the candidate at the historical evaluation instant. Semantic rows show rule/profile/budget/retrieval/source/material and resolution changes; observation and inference remain distinct. Compact source cards and verified lineage references explain one execution without introducing a global graph explorer.

The 0.5.0 exactness criterion was insufficient: matching rendered output could hide different budgets or a different runtime. Replay now compares semantic decisions and runtime identity as well as text. Provider structural fields (for example estimated token counts) must survive retention unchanged; redaction applies to content fields and any change invalidates the complete retained-item digest. A production trace cannot authorize a test expectation or deployment.

Context and tool contracts

ADR 006 extends the immutable artifact with tool schemas, profile disclosure and deterministic obligations. tools.mjs owns bounded structural validation; tool-runtime.mjs owns executor compatibility, expiring approval, serialized dispatch intent and receipts. This gateway does not replace the client’s agent/model loop. Delivery contract.

Living Studio (0.7 development)

studio.mjs projects Agent Factory drafts, Context Project rules, capability bindings/checks, releases/routes, retained turns/traces and application-reported outcomes into seif.studio-scene.v1; it writes no graph and does not become authority. studio-collaborator.mjs exposes a bounded WORLD summary to the configured model and validates its response into read-only queries or inert proposal commands. Accepted proposals delegate to agent-workspace.mjs; scenario expectations and shared-profile impacts require separate human acknowledgement, while publish and Tool approval are not proposal commands.

The Avalonia surface separates StudioScene (typed read model), StudioLayout (deterministic bounded placement), LivingCanvas/TimelineStrip (presentation/input only) and WorkstationWindow.Studio (orchestration over the authenticated local service). Live motion consumes a bounded content-free event feed; historical replay is reconstructed only from retained turn/trace records and cannot execute a model, connector or Tool. See Living Studio.