# Context Fabric

Context Fabric is a local compiler for software-system context. Milestones 0 through 10 are implemented and audited against all 175 SRS requirement IDs. See [Implementation Status](docs/ImplementationStatus.md) for measured gates and [Requirement Coverage](docs/RequirementCoverage.md) for the complete traceability matrix.

Implemented layers include compiler-resolved TypeScript, explicit project-wide JavaScript ESM/CommonJS resolution, syntax-aware Python intelligence, and deterministic PHP symbol/include/call resolution; workspace/framework detection; bounded dependency source roots; HTTP, Confluence, OpenAPI, GraphQL, SQLite, PostgreSQL, external MCP, Figma, and Storybook sources; cross-layer domain concepts with human correction; and design-system intelligence with screenshot evidence.

Project discovery excludes generated dependency and cache trees by default, including JavaScript package/build caches and PHP Composer `vendor`, PHPUnit cache, Laravel compiled/cache directories, and Symfony `var/cache`. A separately configured dependency source can still deliberately index a bounded package root. The universal 50 MiB ceiling keeps oversized files metadata-only.

Runtime intelligence ingests OpenTelemetry, HAR, Playwright JSON traces, application and SQL logs, and Istanbul coverage. It keeps static `may-call` edges separate from observed execution, retains bounded aggregate traces, and exposes generic graph tracing through the shared Knowledge API and MCP.

The Context Engine combines indexed exact/prefix, full-text, graph, concept, and optional local-semantic channels under compact/standard/deep budgets. Evidence strength, confidence, and freshness affect ranking. Optional reasoning providers are disabled by default and persist only grounded proposals with provider/model/task provenance. Production hardening adds WAL, integrity recovery, compaction, bounded background workers with crash detection and capped exponential-backoff restarts, compatibility checks, source/rebuild controls, pipeline metrics, and a 2.25-million-record qualification benchmark.

## Run

```sh
npm install
npm test
npm run benchmark -- 1000
npm run benchmark:scale
npm run start:headless
npm run start:desktop
npm run start:headless -- index C:\path\to\project
npm run start:headless -- search MySymbol
npm run start:headless -- mcp-stdio
npm run start:headless -- mcp-http 7341
npm run start:headless -- watch C:\path\to\project
npm run package:desktop
npm run package:matrix
```

The headless runtime, background indexing worker, desktop renderer, and MCP adapters consume the same core services. Plugins receive a validated `KnowledgeEmitter`; they never receive database write access.

The Electron application automatically runs a read-only MCP Streamable HTTP server for the active project. It binds only to loopback, normally at `http://127.0.0.1:7341/mcp`; the exact endpoint is shown in Settings. In MCP Inspector, select `streamable-http` and enter that endpoint. Switching projects restarts it against the newly active Knowledge API, and quitting the app stops it.

The desktop also stays available from the system tray. Closing the dashboard hides it while indexing and MCP continue; hovering the tray icon shows current indexing activity, and its menu can open the dashboard, start an indexing run, restart the application, or close it completely.

Project discovery hard-excludes dotfiles, agent workspace directories (`.claude`, `.agents`, `.codex`, `.cursor`, and equivalent tool state), and transient `*.lock` files. Recognized dependency locks such as `yarn.lock`, `Cargo.lock`, and `composer.lock` remain part of the project corpus.

Incremental fingerprinting retains SHA-256 content identities but uses persisted size/index time as a no-read fast path for files that have not changed. Up to 16 bounded read/hash lanes operate concurrently, scaled down against the indexing memory policy and maximum file size. When configured, isolated dependency and external-source workers run beside the primary filesystem stage through separate WAL connections; all three lanes drain before derivation begins. Filesystem watch events force a content hash, and fingerprint activity ends before parsing/extraction begins.

On first launch, the desktop asks for a project working directory before it
creates configuration or index data. Settings remembers and can change that
directory. Filesystem/drive roots are rejected; choose a bounded repository,
monorepo, or project directory. Switching roots closes the previous project runtime and opens the
selected root as a separate identity universe. Use **Index project** to perform
the first local sync, or **Clear all app data** to remove Context Fabric-owned
state and return to first-run selection without touching project source files.
The **Storage location** control can move the SQLite index and blob store to a
different drive; Context Fabric uses a dedicated per-project subdirectory and
migrates existing data before reopening the project.

The desktop **Live** view streams bounded, real indexing lifecycle events, including an in-place files-scanned count during project discovery, and a
clickable recent-connection graph without simulated activity. Startup explicitly
reports whether the system is starting, indexing, refining, idle, or in error.
Context Fabric progressively streams the complete labeled interactive graph
through bounded, keyset-paginated Knowledge API pages. GPU buffers grow
geometrically and are reused as pages arrive instead of imposing a fixed node or
edge cap. New nodes use their incrementing graph index and the known
total to spawn around a complete radial turn before simulation. During genuine
idle time, small deterministic refinement batches
add evidence-backed containment connections, persist their cursor, converge, and
pause whenever foreground indexing begins. The
default `shadow` resource policy lazy-starts the TypeScript parser, releases it
after three idle seconds, caps background worker memory, limits foreground
concurrency, and lazy-loads heavyweight dashboard projections. Hot per-file
signals are sampled at 12 events per second while reporting the exact number of
real actions coalesced between visible updates.

The Live view's **Boost** pill switches the current project between the
persistent `shadow` background profile and `performance` active profile without
restarting the app. Boost uses the project's full configured concurrency while
retaining the same worker-memory and file-safety ceilings; the control is locked
while an indexing operation is in flight.

Plugin artifact traversal is streamed in small database pages and retains at
most 64 MiB of content for legacy bulk consumers. TypeScript deep resolution is
isolated in batches of at most 128 files or 8 MiB, with bounded result payloads;
generated bundles, minified scripts, and source maps are excluded by default.

Optional OAuth reasoning providers can also be added and signed into from
Settings using the provider's device-authorization endpoints and public client
ID. Sessions are encrypted with Electron's operating-system credential facility,
stored outside project data, refreshed when supported, and removable with
**Sign out**. API-key environment variables remain supported.

`package:desktop` builds and structurally verifies the current host bundle.
`package:matrix` additionally creates x64 Windows, Linux, and unsigned macOS
transfer bundles and writes `release/packaging-manifest.json`. On Windows hosts
without symlink privilege, the macOS bundle uses materialized framework aliases;
final macOS execution, signing, and notarization still belong on a macOS runner.

Filesystem discovery applies a built-in global exclusion policy before project
rules. Common VCS, dependency, framework output, build, coverage, and cache
directories such as `.git`, `node_modules`, `.next`, `dist`, `target`,
`release`, `.electron-package-cache`, `__pycache__`, and `.cache` are skipped automatically. Project `.gitignore` and
configured ignore rules are layered on top; dependency trees can still be
indexed intentionally by configuring their directory as an explicit bounded
dependency root.

Project discovery is additionally capped at 250,000 files by default to prevent
an unexpectedly broad tree from exhausting the indexing worker. Set
`projectSource.maxFiles` in `.context-fabric/config.json` to tune the ceiling
(the runtime clamps it to 1–1,000,000).

Individual files are capped at 50 MiB. Larger artifacts are retained
as searchable file metadata (path, size, extension, and revision fingerprint),
but their bytes are never loaded into the indexing worker. Set
`projectSource.maxFileBytes` to choose a lower limit; configured values are
clamped to 64 KiB through the absolute 50 MiB ceiling.

External sources are declared in `.context-fabric/config.json`. Secret-bearing headers reference environment variables rather than storing values:

```json
{
  "sources": [
    {
      "id": "product-api",
      "type": "openapi",
      "name": "Product API",
      "enabled": true,
      "config": {
        "urls": ["https://example.test/openapi.yaml"],
        "headerEnv": { "authorization": "PRODUCT_API_AUTH" }
      }
    }
  ]
}
```

PostgreSQL credentials and reasoning-provider credentials are environment
references, not stored values. Optional dependencies and local semantic ranking
can be enabled independently:

```json
{
  "embeddings": { "enabled": true, "model": "context-local-v1", "dimensions": 384 },
  "dependencySources": [
    { "id": "shared-sdk", "path": "vendor/shared-sdk", "enabled": true, "maxFiles": 10000 }
  ],
  "sources": [
    {
      "id": "commerce-db",
      "type": "postgres",
      "name": "Commerce PostgreSQL",
      "enabled": true,
      "config": { "connectionStringEnv": "COMMERCE_DATABASE_URL", "schemas": ["public"] }
    }
  ]
}
```

## Specification traceability

- Canonical model and stable IDs: TAS sections 4–18
- Plugin lifecycle and scoped services: TAS sections 30–37
- Core-owned scheduling and failure isolation: TAS sections 62–65
- Candidate validation and identity: TAS sections 67–75
- SQLite, transactions, and deduplication: TAS sections 86–90
- Worker/backpressure rules: TAS sections 114–121
- Milestone 0 scope and exit criteria: SRS section 21
- Filesystem discovery and snapshots: SRS requirements FR-010–FR-017
- TypeScript symbols and dependencies: SRS requirements FR-030–FR-036
- Incremental pipeline and fingerprints: TAS sections 76–80
- Search and bounded context packs: TAS sections 81–84
- Milestone 1 scope and exit criteria: SRS section 21
- SourceProvider lifecycle: TAS sections 38–41
- Source freshness and caching: SRS requirements FR-010–FR-028
- Milestones 2–10 scope and exit criteria: SRS section 21
- Concept identity, claims, annotations, and knowledge gaps: TAS sections 19–24
- Figma/code ambiguity and rendering reliability: Risks R-027–R-029
- Runtime incompleteness, volume, and retention: Risks R-020–R-021