Skip to content

architecture.md

Latest commit

 

History

History
113 lines (80 loc) · 5.75 KB

architecture.md

File metadata and controls

113 lines (80 loc) · 5.75 KB
Raw

Architecture

Product boundary

Agent Capability Engine owns deterministic capability discovery, graph compilation, reachability, policy evaluation, blast-radius diffs, runtime overlays, exports, and reports.

It does not execute agent tasks, select prompts, resolve secrets, authorize users, or claim enforcement outside the facts it receives. ForgeOS remains responsible for routing, context selection, approvals, execution, receipts, evidence, recovery, and release decisions.

Pipeline

repository files / structured adapters / runtime documents
                         ↓
                validated normalized facts
                         ↓
                  canonical snapshot
                         ↓
                 immutable graph index
       ┌─────────────────┼──────────────────┐
       ↓                 ↓                  ↓
 bounded path        policy gate       blast-radius diff
       └─────────────────┼──────────────────┘
                         ↓
          CLI / JSON / SARIF / HTML / local API

Package boundaries

  • internal/atomicfile: durable temporary-write and atomic publish on Unix and Windows.
  • internal/model: portable nodes, edges, diagnostics, snapshots, validation, canonicalization, and hashing.
  • internal/snapshot: bounded snapshot persistence and tamper verification.
  • internal/scan: bounded generic discovery plus the structured ForgeOS adapter.
  • internal/bridge: ForgeOS runtime-document verification and translation.
  • internal/facts: strict NDJSON facts and monotonic runtime overlays.
  • internal/graph: immutable indexes, selectors, and bounded shortest-path search.
  • internal/policy: strict JSON and bounded-YAML policy loading and evaluation.
  • internal/diff: structural, state-regression, and new-critical-path comparison.
  • internal/exporter: JSON, DOT, Mermaid, SARIF, and HTML output.
  • internal/report: self-contained report and loopback HTTP API.
  • internal/cli: command parsing, stable output, and stable exit codes.

The graph/model packages do not import scanner, report, CLI, or ForgeOS-specific logic.

Data model

A node represents a source, agent, route, skill, technique, provider, tool, capability, control, secret reference, receipt, evidence record, finding, artifact, or asset.

An edge represents a directed relationship. Its state expresses certainty or enforcement:

possible < declared < routable < selected < allowed
         < observed < receipted < proven < blocked/denied

blocked and denied edges are excluded from normal traversal. State overlays are monotonic so late or reordered events cannot reduce certainty.

Determinism

  • Node IDs are stable strings.
  • Duplicate nodes and edges are merged independently of adapter order.
  • Nodes, edges, maps, source references, and diagnostics are canonicalized.
  • Conflicting descriptive scalars resolve lexicographically.
  • Machine-specific root paths and an existing content hash are excluded from snapshot hashing.
  • Repeated scans of identical content produce byte-identical snapshots.

Trust boundaries

Every ingress is validated before indexing or rendering:

  1. Repository structured documents are size-bounded and reject trailing JSON.
  2. Normalized facts reject unknown fields, malformed IDs, invalid states, and oversized data.
  3. ForgeOS self-addressed documents are canonical-hash verified before translation.
  4. Snapshots reject unknown fields, dangling edges, duplicates, invalid states, and tampered hashes.
  5. Policies reject unsupported fields, syntax, states, and traversal limits.
  6. Reports and APIs operate only on a validated snapshot.

Resource bounds

Defaults and hard maxima exist for:

  • repository file count, directory depth, and inspected file size;
  • structured ForgeOS file size;
  • snapshot bytes, nodes, edges, properties, source references, and diagnostics;
  • fact line bytes and total fact count;
  • runtime bridge bytes and translated facts;
  • policy bytes and traversal options;
  • path depth and visited nodes;
  • API query bytes and result limit;
  • embedded report payload bytes.

A bounded omission produces an incomplete snapshot and a diagnostic. An ambiguous structured contract fails closed.

Persistence

Snapshots and exported files are written to a temporary file in the target directory, flushed, and atomically published. Unix implementations also flush the parent directory when supported. Windows uses MoveFileExW with replacement and write-through flags.

Snapshot reads recompute the canonical hash. A stored hash mismatch is a hard failure.

ForgeOS static adapter

ForgeOS is detected only when both package identity and Capability Graph v2 are present. The adapter reads typed contracts and suppresses generic keyword inference for structured-owned directories. This prevents documentation text from accidentally acquiring runtime authority.

ForgeOS runtime bridge

Supported documents are discriminated by their contract fields, validated, and translated into the same normalized fact model. Route plans select techniques/providers/outcomes. Execution receipts raise provider-tool edges. Evidence and surface reports add attestation/report relationships.

Principal, tenant, prompt, payload, and secret content are not copied. Producer identity is represented only by a SHA-256 reference where useful.

HTTP surface

The built-in server is loopback-only. It accepts GET and HEAD without request bodies, enforces bounded query parameters, and sends CSP, nosniff, frame denial, no-referrer, no-store, and restrictive Permissions-Policy headers.

The offline report uses Base64-encoded JSON and writes untrusted visible values through DOM textContent.