CodeAtlas

CodeAtlas is a local CLI for repository evidence and policy. It maps public code APIs, classifies source reachability, inspects bounded dependency neighborhoods, checks declared architecture, inventories tests, and analyzes HTTP and PostgreSQL contracts.

CodeAtlas preserves unresolved and dynamic boundaries instead of turning incomplete static evidence into false certainty. It does not mutate project source or claim to replace runtime, integration, or property tests.

Setup

CodeAtlas is used from its source repository and is not published. Clone it over SSH, keep Cargo output outside the checkout, and build the locked source:

git clone git@github.com:goobits/codeatlas.git
cd codeatlas

export CARGO_TARGET_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/codeatlas/target"
pnpm install --frozen-lockfile
cargo build --locked

"$CARGO_TARGET_DIR/debug/codeatlas" --help

The npm wrapper can run an exact local binary when a Node-based caller is more convenient:

CODEATLAS_BINARY_PATH="$CARGO_TARGET_DIR/debug/codeatlas" node bin/codeatlas.js --version

Node.js 22 or newer is required by the wrapper. PostgreSQL live tests also require psql. HTTP planning fingerprints the locked Schemathesis contract without installing or starting it; managed execution fails closed unless the required kernel enforcement is available.

CLI

codeatlas [--root <path>] [--config <path>] <command> <subject> [options]

--root defaults to the current directory. --config selects a specific codeatlas.json; otherwise CodeAtlas reads the file at the selected root when present.

Command	Purpose
scan code|http|postgres|architecture|tests	Gather current subject evidence
check code|http|postgres|architecture|tests	Apply static rules and contract checks
baseline code|http|postgres|architecture	Save reviewed comparison evidence
diff code|http|postgres|architecture	Compare evidence with a baseline
usage code|http|postgres|tests	Classify known consumers or select affected tests
inspect code|http|postgres|architecture	Explain an exact target and its bounded neighborhood
lexicon code|repository	Report deterministic naming and conceptual evidence
docs code|http|postgres	Generate or check sourced reference documentation
fuzz code|http	Persist or execute a bounded isolated fuzz plan
test postgres	Replay migrations and prepare queries in a disposable database
init code|http|postgres	Discover and optionally write conservative subject configuration

Run codeatlas <command> <subject> --help for the complete option set.

Capability boundaries

Evidence	JavaScript/TypeScript	Svelte	Python	Rust
Public API scan and docs	yes	yes	yes	yes
Reachability, usage, context, and test impact	yes	yes	yes	yes
Static HTTP route inventory	yes	yes	yes	yes
Static PostgreSQL application-query extraction	yes	no	no	no

HTTP fuzz planning operates at a configured transport boundary and makes zero target calls. PostgreSQL live testing validates database contracts; it is not SQL fuzzing. Callable fuzz planning currently creates a runnable native harness only for supported Python free functions; Rust, JavaScript, and TypeScript remain explicit zero-call adapter blocks until their parity gates pass. Python execution requires the verified shared isolation backend and a digest-pinned checked-in target image.

Code Evidence

Public and maintained surfaces

scan code follows configured entrypoints or discovered package exports by default:

codeatlas --root packages/example init code
codeatlas --root packages/example scan code
codeatlas --root packages/example scan code --format json

Use a source scan to inspect every maintained source file. --all adds private and internal declarations:

codeatlas --root packages/example scan code --scope source --all --format json
codeatlas --root packages/example scan code --scope source --format mermaid

Package exports remain attached to source-scope symbols, so the report still distinguishes importable API from implementation-only declarations. Default discovery excludes dependencies, generated output, conventional tests, and fixture-data trees unless configuration explicitly selects them.

JSON scan reports use schema version 4. A callable symbol carries one optional structured CallableContract with ordered signatures, receivers, parameter roles and types, result shape, conservative effects, and exact block reasons. The display signature remains presentation evidence; policy consumers do not reparse it. A missing effect is never presented as proof of purity. Source policy evidence is attached separately so it cannot masquerade as a type or effect oracle.

Static fuzzability and one-way exclusions

check code builds and validates a zero-call fuzzability inventory for every discovered public Rust, Python, JavaScript, and TypeScript callable. Each internal entry has the shared callable contract, deterministic boundary descriptors and bounded pairwise prefix, supported result-shape evidence, or exact block reasons. scan code exposes the callable and source-policy evidence, while check code emits malformed-directive findings. The complete fuzzability inventory has a registered schema for planning but is not a standalone CLI report. fuzz code consumes that same inventory; it does not reparse display signatures or silently omit unsupported public APIs.

Maintainers can place one subtractive directive beside the declaration:

@codeatlas-fuzz deny: <maintainer reason>

Rust doc comments, JavaScript/TypeScript JSDoc, and Python docstrings attach it through their existing syntax adapters. deny means never fuzz that target, even under verified isolation. Ordinary mutation and effects stay in typed effect evidence and target classification. There is no allow: a stale source comment may reduce authority but can never expand what runs. Malformed, duplicate-conflicting, and unsupported directives are gating check code findings.

Strict config provides the same exact fallback without wildcards:

{
  "fuzz": {
    "code": {
      "targets": [{
        "id": "python-fixtures",
        "project": "python-fixtures",
        "language": "python",
        "image": "ghcr.io/example/codeatlas-python-fuzz@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "preauthorized": true
      }]
    },
    "exclude": {
      "code": ["src/publisher.rs#ArtifactPublisher.publish"],
      "http": ["POST /admin/export"],
      "postgres": ["query_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]
    }
  }
}

One code target binds an existing analysis project and one language runtime; it does not duplicate the callable inventory. Target and replay forms are zero-call previews, while execution always uses the persisted plan and shared kernel:

codeatlas --root . fuzz code --target python-fixtures \
  --symbol src/parser.py#parse_token --seed 42
codeatlas --root . fuzz code --plan plan_ABC --execute
codeatlas --root . fuzz code --replay reproducer_ABC

Single-shot --execute is available only for a checked-in preauthorized local, disposable target after runtime isolation is verified. The planned harness, engine fingerprint, deterministic prefix, seed, limits, and CODEATLAS_FUZZ=1 marker are immutable plan evidence. The marker grants no authority; a callable that branches on it is reported as alternate_behavior.

Code selectors use path#symbol and qualify members as Type.method when needed. HTTP plans persist the canonical excluded-operation set and reject an excluded --operation. PostgreSQL exclusions use content-addressed query IDs. An unresolved code or PostgreSQL exclusion fails closed instead of silently doing nothing.

For handwritten static .sql files, a leading SQL comment may carry the same directive as a convenience. PostgreSQL remains config-first: embedded ORM and dynamic SQL do not acquire comment attachment through a second parser.

Reachability and consumers

Use named contexts to describe production, test, and tooling roots:

{
  "projects": [
    {
      "id": "web",
      "root": ".",
      "languages": ["js", "ts", "svelte"],
      "require_complete": true,
      "contexts": {
        "application": {
          "role": "production",
          "scope": "runtime",
          "entrypoints": ["src/index.ts", "src/App.svelte"]
        },
        "public-api": {
          "role": "production",
          "scope": "public_surface",
          "entrypoints": ["src/public.ts"]
        },
        "unit-tests": {
          "role": "test",
          "entrypoints": ["src/**/*.test.ts"],
          "subjects": [
            { "project": "web" },
            { "source": "src/brushes/**" }
          ]
        },
        "build-tools": {
          "role": "tooling",
          "entrypoints": ["scripts/**/*.ts"]
        }
      },
      "assume_reachable": ["src/runtime/plugins/**/*.ts"]
    }
  ]
}

runtime contexts follow executed dependencies. public_surface contexts also expand exports from their roots. Test subjects record black-box intent; they supplement observed graph evidence rather than replacing it.

CodeAtlas also derives supported roots from package exports, executable scripts, framework entrypoints, conventional tests, Rust targets, Python project scripts, and configured HTTP or PostgreSQL tools. Dynamic imports, reflection, macros, generated targets, unresolved aliases, and unsupported syntax remain explicit analysis boundaries. Configured directory aliases remain scoped to their owning project and never suffix-match an unrelated workspace member.

codeatlas --root . usage code --workspace
codeatlas --root . usage code --workspace --format json --out usage.json
codeatlas --root . check code --workspace --gates-only

Text output prioritizes gating findings and groups advisories for triage. JSON is the exhaustive machine-readable report. check code returns nonzero for eligible findings and for a project whose require_complete assertion is not satisfied.

Public consumer analysis is deliberately separate because external consumers may be invisible:

codeatlas --root packages/library usage code --scope public
codeatlas --root packages/library usage code \
  --scope public \
  --consumer-root ../application

It recognizes static imports, re-exports, and literal dynamic imports from JavaScript, TypeScript, and Svelte consumer trees. Namespace, default, and runtime-dependent imports are handled conservatively.

Code usage/check report v6

usage code --format json and check code --format json emit schema version 6. The report keeps project completeness separate from individual findings; check-only policy findings do not change the question answered by usage code.

Project summaries include:

• completeness: complete, partial, or unsupported
• completeness_reasons: the exact boundary kind, effect, message, and source evidence that limits the project
• require_complete: whether incomplete evidence is a check failure
• deterministic file, language, and symbol counts

Every finding includes a stable id, optional exact node_id, contexts and roots, confidence, source evidence, and these review fields:

Field	Values	Meaning
evidence_class	direct	High-confidence structural contract evidence
	inferred	High-confidence reachability classification
	boundary_limited	Public, dynamic, medium-confidence, or low-confidence evidence
source_disposition	maintained, generated, fixture, test, tooling	Source role inferred from the maintained path
gates	boolean	Whether this exact finding can fail check code

Only high-confidence unreachable files, unused private symbols, workspace export or source-bypass violations, unresolved internal imports, and malformed fuzz directives can gate. Malformed directives appear only in check code. Public symbols with no known consumer, dynamic boundaries, test-only code, and tooling-only code remain visible evidence, not automatic deletion authority.

Focused context

inspect code accepts one or more exact node IDs, repository-relative paths, project::path selectors, or path#symbol selectors:

codeatlas --root . inspect code \
  core::src/compiler.rs#compile \
  packages/web/src/routes.ts \
  --depth 2 \
  --direction outgoing \
  --max-nodes 128 \
  --out context-page-1.json

Direction is incoming, outgoing, or both. The default is both. Ambiguous project-relative targets fail with a qualification hint.

Context reports use schema version 5 and preserve the same callable contract and source-policy evidence on symbol nodes. Each page includes:

• graph_digest, direction, depth, and max_nodes
• page_offset, remaining_nodes, and omitted project, node, edge, context, and boundary counts
• an opaque continuation cursor when another page exists
• exact target resolutions and the page-owned graph evidence

Resume with the same targets, depth, direction, and node budget:

codeatlas --root . inspect code \
  core::src/compiler.rs#compile \
  packages/web/src/routes.ts \
  --depth 2 \
  --direction outgoing \
  --max-nodes 128 \
  --cursor '<continuation from context-page-1.json>' \
  --out context-page-2.json

The cursor binds the request and source-graph digest. A changed request is rejected, and a changed graph makes the cursor stale. Combining every page by stable identity reconstructs the complete directed slice. Source context is kept separate from declared architecture because the graphs have different authority and semantics.

Test intelligence

Test analysis is read-only. It inventories and selects tests but never runs package scripts:

codeatlas --root . scan tests --workspace --format json
codeatlas --root . usage tests --workspace \
  --changed packages/brush/src/model.ts \
  --changed packages/paint/src/canvas.ts
codeatlas --root . usage tests --workspace
codeatlas --root . check tests --workspace --format json

• scan tests reports test contexts, roots, package scripts, recognized runners, no-op or allows-empty scripts, and duplicate commands.
• usage tests selects observed dependents and falls back conservatively for new, deleted, manifest, or unsupported paths. selection_complete exposes whether fallback was needed. Without --changed, it reads Git's staged, unstaged, and untracked paths. Explicit repeatable --changed values replace that default. Workspace manifests, lockfiles, toolchain files, and language project configuration use the conservative workspace fallback.
• check tests distinguishes observed, declared-only, unwitnessed, unknown, and detached evidence for public symbols. Text output omits already-witnessed detail and bounds the remaining findings; JSON embeds the same CallableContract model used by scan and inspection, including parameters, receivers, constructibility, and the effects available in the analyzed source-graph snapshot.

The three reports have separate published contracts: codeatlas.testing-inventory/v1, codeatlas.testing-impact/v1, and codeatlas.testing-witness/v2.

Lexicon review

codeatlas --root . lexicon code
codeatlas --root . lexicon code --workspace --format json

Lexicon analysis scans maintained source with private symbols included. It reports exact same-name/different-shape collisions, deterministic type-shape candidates, callable contract candidates, repeated identifier terms, and declared terminology policy. It also records package exposure.

Its programming-identifier grammar recognizes one bounded family of naming constructions: verb_object[_qualifier], object[_qualifier]_actor, and object[_qualifier]_result. Thus load_config / config_loader, validate_request / request_validator, and resolve_path / path_resolution can be compared without permuting arbitrary words. Object and qualifier order is preserved, and predicates (is, has, can, supports) remain semantically distinct from actions. A grammar pair is reported only when same-language, compatible symbol kinds also share a cross-file typed callable role shape, untyped callable shape, or structural type shape. Untyped evidence is clearly lower confidence.

The built-in grammar uses a reviewed, closed programming morphology table for actor/result forms of build, collect, convert, format, load, parse, plan, read, render, resolve, validate, and write. Its safe abbreviations are exactly cfg/config, ctx/context, req/request, resp/response, and repo/repository. It does not use Porter stemming, a general dictionary, or arbitrary token sorting. Projects may add bounded exact rules without overriding built-ins:

{
  "lexicon": {
    "grammar": {
      "abbreviations": [
        { "term": "svc", "expansion": "service" }
      ],
      "morphology": [
        { "term": "hydrator", "action": "hydrate", "role": "actor" }
      ]
    }
  }
}

Candidate generation is linear: each observed actor/result surface is compared with one deterministic action-form anchor, never every spelling pair. Exact same-name callable shapes carry direct structural evidence. Separate non-grammar callable candidates require a typed semantic-role shape, cohesive source scope, and meaningful object or qualifier terms after the leading intent word. Shapes are projected from structured callable contracts; display signatures are never reparsed as policy evidence. Untyped name-only matches and unrelated type coincidences are omitted because they do not provide enough evidence. CodeAtlas does not compare implementation bodies or claim behavioral equivalence, so structural candidates remain advisory. Results are read-only: they do not create gates, choose a refactor, authorize deletion, or update a source dataset.

Project policy is the authority. A concept can own preferred terms, exact aliases, and retired terms. distinct_from records that two declared concepts are intentionally different; never_suggest suppresses one exact unowned or partially owned term pair. Both exception forms require a durable reason.

{
  "lexicon": {
    "concepts": [
      {
        "id": "request_handler",
        "preferred_terms": ["request handler"],
        "exact_aliases": ["controller"],
        "retired_terms": ["request processor"],
        "distinct_from": [
          {
            "concept": "event_listener",
            "reason": "Handlers own requests; listeners observe domain events."
          }
        ]
      },
      {
        "id": "event_listener",
        "preferred_terms": ["event listener"]
      }
    ],
    "never_suggest": [
      {
        "terms": ["record", "row"],
        "reason": "A record is a domain value; a row is storage in this project."
      }
    ]
  }
}

Terms are matched exactly after case, punctuation, separator, and identifier word-boundary normalization. A term may belong to only one concept. A distinct_from declaration is symmetric even when it is written on only one concept. Contradictory, duplicate, unknown, or reasonless declarations fail before source scanning.

Evidence precedence is project policy, exact normalized concepts, local programming grammar/morphology, then pinned CSO relations. Project declarations are authoritative. Grammar and provider results remain explainable advisories; each JSON finding lists its canonical grammar, every abbreviation/morphology rewrite, compatible kind, and exact structural corroboration. An exact distinct_from or never_suggest rule always suppresses later evidence.

Offline thesaurus evidence

Optional sources are pinned offline evidence, never authority. Every provider manifest declares its version, SHA-256 digest, license, attribution, upstream URL, format, and whether the local data is complete or filtered. Missing files, changed bytes, malformed records, and unsupported schemas fail the command instead of silently producing a partial report.

Computer Science Ontology (CSO) is the primary supported programming/domain source. CSO 3.5 contains about 15,000 topics and 166,000 relationships and is licensed CC BY 4.0. CodeAtlas reads the official, extracted CSV directly and considers only preferentialEquivalent and relatedEquivalent; hierarchy and contribution edges are not synonym evidence. CSO itself defines relatedEquivalent as contextual equivalence, not skos:exactMatch, so every sourced result remains advisory.

Source acquisition and refresh stay outside analysis. This reproducible example pins the CSO 3.5 release archive and the extracted CSV bytes used by the provider:

lexicon_source_root=/opt/codeatlas/lexicon
mkdir -p "$lexicon_source_root"
curl -fsSL \
  https://cso.kmi.open.ac.uk/download/version-3.5/CSO.3.5.csv.zip \
  -o "$lexicon_source_root/CSO.3.5.csv.zip"
printf '%s  %s\n' \
  5b16a3902e90b704bc90536034665022b2b3d074c7bf3fbf4291e5d6cc0aae20 \
  "$lexicon_source_root/CSO.3.5.csv.zip" | sha256sum --check
unzip -p "$lexicon_source_root/CSO.3.5.csv.zip" \
  > "$lexicon_source_root/CSO.3.5.csv"
printf '%s  %s\n' \
  564fb62dcc638c655bd9936247f45d740417e5786f6892f0341f606cfbbba98f \
  "$lexicon_source_root/CSO.3.5.csv" | sha256sum --check

{
  "lexicon": {
    "providers": [
      {
        "id": "cso",
        "tier": "domain",
        "format": "cso_csv",
        "coverage": "complete",
        "version": "3.5",
        "path": "/opt/codeatlas/lexicon/CSO.3.5.csv",
        "sha256": "sha256:564fb62dcc638c655bd9936247f45d740417e5786f6892f0341f606cfbbba98f",
        "license": "CC-BY-4.0",
        "attribution": "Computer Science Ontology, Knowledge Media Institute, The Open University",
        "url": "https://cso.kmi.open.ac.uk/downloads"
      }
    ]
  }
}

Relative provider paths resolve from the selected codeatlas.json. CodeAtlas does not distribute CSO, download it during analysis, or refresh a pin.

relations_json_v1 is the small pluggable format for a versioned domain source or a filtered general thesaurus. It has a closed schema:

{
  "schema_version": 1,
  "relations": [
    {
      "subject": "language model",
      "relation": "synonym",
      "object": "language models"
    }
  ]
}

Domain manifests may use preferential_equivalent, related_equivalent, or synonym. General manifests may use only synonym, require at least one domain provider, and are indexed only when the exact normalized pair already has domain evidence. Thus a normal thesaurus can corroborate a programming result but cannot originate one. Open English WordNet 2025 is the recommended general source: it is versioned and CC BY 4.0, but its roughly 120,000 sense-specific synsets are deliberately not embedded or guessed across code identifiers. Prepare a small attributed relation file in a separate source refresh process, mark its coverage filtered, and pin its resulting bytes.

JSON reports use lexicon schema version 5. They expose deterministic candidate IDs and ordering, source manifests and record counts, evidence relation and direction, available source ranges for observed symbols, project/domain tiers, qualitative confidence, stable rules and reasons, preferred terms when declared, the exact built-in/configured grammar-rule counts, applied suppressions, and the exact config key for permanently dismissing an advisory candidate. Text output shows the same review surface in compact form; JSON is the complete contract.

For naming evidence that crosses subject boundaries, use the separate repository report:

codeatlas --root . lexicon repository
codeatlas --root . lexicon repository \
  --subjects code,http,postgres \
  --format json \
  --out repository-lexicon.json

lexicon repository collects each selected subject once and emits codeatlas.repository-lexicon/v1. Every term retains its subject, owner, exact target, source spelling, confidence, and completeness. Exact normalized terms, declared concepts, and unsuppressed pinned domain relations may produce a related_evidence relationship; none proves semantic equivalence. Relationship targets and total output are bounded, and retained versus omitted evidence is reported explicitly. Missing HTTP or PostgreSQL inventory remains visible instead of silently becoming an empty, complete subject.

Public API baselines

codeatlas --root . baseline code \
  --workspace \
  --out .codeatlas/baselines/public-api.json

codeatlas --root . diff code \
  --workspace \
  --against .codeatlas/baselines/public-api.json \
  --exact

The compact baseline stores stable public identities and deterministic contract fingerprints. Without --exact, additions are reported while removals and contract changes fail. A fingerprint proves that a contract changed, not whether that language-specific change is source-compatible, so changed contracts are labeled REVIEW and remain fail-closed until reviewed or checked by a purpose-built compatibility tool. Exact mode also fails on additions and export moves. Baseline creation is explicit; checks never update reviewed evidence.

API documentation

codeatlas --root . --config codeatlas.json docs code
codeatlas --root . --config codeatlas.json docs code \
  --format html \
  --out docs/API-Reference.html
codeatlas --root . --config codeatlas.json docs code --check

Source documentation remains the description owner. CodeAtlas does not invent missing descriptions. declaration_contract follows the shipped declaration entrypoint, while include_dependency_types includes supporting local types needed to understand exported signatures. Documentation configuration also accepts home and canonical URLs, a public display name, description checks, and light or dark semantic color overrides.

{
  "docs": {
    "title": "Example API Reference",
    "description": "Public contracts for the Example package.",
    "public_name": "Example SDK",
    "declaration_contract": true,
    "include_dependency_types": true,
    "require_descriptions": true,
    "output": "docs/API-Reference.md"
  }
}

Declared Architecture

Restricted YAML is the sole editable architecture authority. Generated graphs, lockfiles, observations, and conformance reports are evidence and must not be edited by hand.

Save a canonical compilation baseline for one or more root modules:

codeatlas baseline architecture \
  architecture/root.atlas.yaml \
  --source-root . \
  --mode governing \
  --out .codeatlas/architecture.json \
  --lock-out .codeatlas/architecture.lock.json

governing includes active accepted declarations. review also includes proposed and unresolved declarations but remains non-governing.

Check current imports and accepted dependency constraints:

codeatlas --root . check architecture \
  architecture/root.atlas.yaml \
  --source-root . \
  --out .codeatlas/source-conformance.json

The source check reports unexported workspace imports, direct cross-package source bypasses, and dependency paths forbidden by accepted architecture.

Generate reproducible binding evidence and compare it with the governing graph:

codeatlas --root . scan architecture \
  architecture/root.atlas.yaml \
  --source-root . \
  --repository-id example.repository.source \
  --observation-id example.observation.current \
  --source-commit 0123456789abcdef0123456789abcdef01234567 \
  --observed-at 2026-07-23T00:00:00Z \
  --out .codeatlas/architecture-observation.json

codeatlas --root . diff architecture \
  --against .codeatlas/architecture.json \
  --observation .codeatlas/architecture-observation.json \
  --conformance-id example.conformance.current \
  --as-of 2026-07-23T00:00:00Z \
  --out .codeatlas/architecture-conformance.json

The caller supplies commit and time metadata explicitly. Diff loads the exact saved governing graph; it does not silently recompile current declarations. A review-mode baseline is inspectable but cannot govern conformance. Optional repeatable --policy inputs may change a finding's disposition but never the governing graph.

Query an approved provider classification:

codeatlas inspect architecture \
  capability:example.capability.context \
  architecture/root.atlas.yaml \
  --source-root . \
  --approval-scope organization

This projection does not evaluate runtime eligibility, select a provider, or authorize invocation. The accepted architecture language and trust boundaries are specified in spec/architecture/v0.1/.

HTTP Contracts

scan http inventories supported source routes without configuration. Add an OpenAPI 3.0 or 3.1 contract for request and response schemas, conformance, baselines, and schema-backed fuzzing.

{
  "http": {
    "contracts": [
      {
        "id": "public-api",
        "openapi": "openapi.json",
        "source_roots": ["src/http"],
        "source_include_paths": ["/v1/**", "/health"],
        "source_exclude_paths": ["/internal/**"],
        "source_complete": true
      }
    ],
    "fuzz": {
      "image": "ghcr.io/example/codeatlas-http-fuzz@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "targets": [
        {
          "id": "public-local",
          "contract": "public-api",
          "base_url": "http://127.0.0.1:3443",
          "environment_class": "disposable",
          "preauthorized": true,
          "operations": ["GET /health", "POST /v1/sessions"],
          "environment": {
            "NODE_ENV": "test",
            "PORT": "3443"
          },
          "secret_environment": {
            "API_TOKEN": "LOCAL_API_TOKEN"
          },
          "server": {
            "command": "node",
            "args": ["src/test-server.js"],
            "cwd": "."
          },
          "positive_coverage": {
            "max_operations_without_success": 0,
            "max_authentication_rejection_only_operations": 0
          }
        }
      ]
    }
  }
}

Leave source_complete false when runtime registration can escape static discovery. Exact operation filters use canonical METHOD /path keys. Dynamic dispatch may declare a narrow literal route with @codeatlas-http GET /items/{id} when static recovery is impossible.

codeatlas --root . init http
codeatlas --root . scan http --out http-inventory.json
codeatlas --root . scan http --format hqa-inventory --out hqa-routes.json
codeatlas --root . check http
codeatlas --root . usage http --format json --out http-usage.json
codeatlas --root . inspect http "GET /health" --out http-inspection.json
codeatlas --root . docs http --format markdown --out http-reference.md
codeatlas --root . baseline http --out http-baseline.json
codeatlas --root . diff http --against http-baseline.json
codeatlas --root . fuzz http --target public-local --seed 42
codeatlas --root . fuzz http --target public-local --profile stateful
# After reviewing the emitted plan:
codeatlas --root . fuzz http --plan plan_ABC --execute
# For a checked-in preauthorized local disposable target only:
codeatlas --root . fuzz http --target public-local --execute

Without --execute, the target and --replay forms only gather current evidence and persist an immutable content-addressed plan under the external state root. --plan ... --execute revalidates that exact plan before any target work. --target ... --execute uses the same persisted-plan executor and is eligible only when the kernel corroborates a checked-in target as preauthorized, local, disposable, and fully isolated. Remote, production, unknown-effect, and incompletely isolated targets require review or remain blocked. A missing isolation capability always produces a blocked zero-call receipt; review never waives it. Set CODEATLAS_STATE_DIR to choose the external private artifact base. Execution also requires the exact digest-pinned http.fuzz.image; managed server, preparation, adapter, and Schemathesis commands run inside that network-isolated workload image, never as host processes.

The repository owns the standard Schemathesis workload recipe and its one hash-locked Python dependency set. From a clean commit, build its canonical OCI archive through the same bounded image transaction as the isolation probe:

export CARGO_TARGET_DIR=/tmp/codeatlas-cargo-target
pnpm http-workload:build \
  --runtime /usr/bin/docker \
  --socket /var/run/docker.sock \
  --python-image python@sha256:<exact-python-image-digest> \
  --buildkit-image moby/buildkit@sha256:<exact-buildkit-image-digest> \
  --platform linux/amd64 \
  --network allow \
  --out /tmp/codeatlas-http-workload.oci.tar

The final image starts from scratch metadata, contains Schemathesis 4.24.3, and carries no inherited base-image environment. The build task accepts network access only for hash-verified dependency installation; runtime remains --network none. Publish the built image under its exact repository digest and use that reference as http.fuzz.image. A project needing extra managed-server dependencies derives and pins its own image from this recipe.

Isolation probes use one exact local container executable and Unix socket with a private, empty client configuration. Runtime version and security metadata are recorded as identity only; they are not isolation proof. A digest-pinned probe image must target-prove every required mount, network, process, resource, and cleanup control before the backend can grant a capability. A machine with no usable local runtime, including a development container without its host socket, remains plan-only.

The probe source and strict report model live in the focused codeatlas-isolation-conformance crate. Its OCI recipe builds a static binary into a scratch image. From a clean committed checkout, create an OCI archive and manifest digest with all state outside the repository:

export CARGO_TARGET_DIR=/tmp/codeatlas-cargo-target
pnpm probe:build \
  --runtime /usr/bin/docker \
  --socket /var/run/docker.sock \
  --build-image rust@sha256:<exact-musl-image-digest> \
  --buildkit-image moby/buildkit@sha256:<exact-buildkit-image-digest> \
  --platform linux/amd64 \
  --network allow \
  --out /tmp/codeatlas-isolation-probe.oci.tar

--network allow permits the builder stage to fetch locked dependencies; it does not constrain network destinations. deny is the offline form and works only when the pinned build image already contains those dependencies. The task never pulls or publishes implicitly. It refuses dirty source, checkout-local output, or a container runtime whose reported data root overlaps the checkout. Runtime commands have finite elapsed/output ceilings, it keeps private build logs beside the archive, and it prints the OCI manifest digest plus the resolved runtime data root. Importing or publishing that archive under an exact repository digest is a separate operator step. Neither the archive nor its digest grants execution: the live nonce-bound matrix must still pass, and its intentional write attacks use an external disposable sentinel workspace rather than analyzed source.

The repository's Live OCI isolation gate GitHub Actions workflow owns the complete capable-runner path. It is manual-only and default-branch-only, uses a fresh ubuntu-24.04 runner with read-only repository permission, builds from a clean exact commit through one digest-pinned disposable BuildKit builder, publishes the probe and HTTP workload only to one bounded loopback registry, runs the isolation matrix plus standard and stateful managed HTTP workloads through the same container owner, verifies cleanup, and uploads the receipt, evidence summary, both OCI artifacts, metadata, and private diagnostic logs. It never mounts the Docker socket into a child or accepts a caller-supplied command. The evidence records the built OCI manifest, loaded image ID, and published manifest separately; Docker media-type normalization is visible rather than misreported as digest preservation.

That workflow restores and saves one Cargo cache keyed by runner OS and architecture, the exact rustc -Vv digest, both Cargo lockfiles, and both manifests. The uncompressed payload is limited to 6 GB and reports hit/miss, restored bytes, save outcome, and saved payload bytes in the job summary. Image building deliberately retains --no-cache: cached Rust dependencies and test outputs accelerate reruns, while both committed runtime images are rebuilt through one disposable BuildKit owner for every live proof.

The hqa-inventory format projects the same bounded source and OpenAPI union into HQA application-inventory v1. Endpoint and OpenAPI-only operations are probe-only; source pages remain explorable. Dynamic {parameter} paths use a navigable static prefix, while detector-specific path patterns survive only as provenance tags. Partial source completeness stays explicit, and CodeAtlas never invents HQA roles, readiness targets, or transitions.

Without OpenAPI, check http preserves the source inventory and reports schema absence without pretending a schema exists. Source-transport fuzzing can check known operations for unhandled server errors and unsupported methods. Explicit OpenAPI adds schema conformance, authentication probes, declared status checks, and optional stateful traversal through OpenAPI Links.

The target's operation list is the fuzz authority. --operation may narrow it for local diagnosis but cannot expand it or select a checked-in fuzz.exclude.http operation. Every plan contains its excluded-operation set, concrete seed, and finite limits. Plans, receipts, and run reports exclude secret values, request and response bodies, sensitive headers, and URL query values.

HTTP configuration also supports:

• one bounded file-backed OpenAPI contract per configured contract
• exact source operation filters after path filters
• an explicit operation list or "operations": "contract"
• literal non-secret process environment plus secret_environment mappings from target variable name to ambient secret-reference name
• literal test headers or value_env secret references; planning records the reference and does not require or persist its value
• expected non-success operations and positive-coverage budgets
• ordered server.prepare commands before an owned local server starts
• a long-lived request adapter over the codeatlas.http-request-adapter/v3 JSONL protocol for project-owned fixture, signing, and authentication logic

Generated or remote OpenAPI evidence must be materialized to a file before CodeAtlas reads it. Pre-v1 object providers (kind: file|command|url|target) and target openapi_path were removed: they could start an unplanned host process or make a target call from a static evidence command. Replace an object provider with its materialized path string and remove openapi_path; there is no compatibility reader or host-execution fallback.

The profile ceilings are 75 cases for standard, 750 for thorough, and 25 stateful cases across explicit OpenAPI Links. Checked-in fuzz.limits.max_cases (50 by default) remains the hard ceiling, and --max-cases may only tighten it. The codeatlas.http-fuzz-report/v1 artifact separates positive successes, expected denials, negative rejections, server errors, authentication-only results, and stateful coverage and is linked to the exact plan and receipt.

PostgreSQL Contracts

init postgres discovers conservative PostgreSQL evidence and prints proposed configuration. --write is the only form that edits codeatlas.json.

{
  "postgres": {
    "contracts": [
      {
        "id": "accounts",
        "bootstrap_sources": [
          {
            "path": "src/db/schema.sql",
            "transaction": "always",
            "psql_meta_commands": "reject"
          }
        ],
        "migration_sources": [
          {
            "path": "src/db/migrations",
            "transaction": "always",
            "psql_meta_commands": "reject",
            "recursive": false
          }
        ],
        "query_roots": ["src"],
        "source_complete": true,
        "lint": {
          "pg_version": "17"
        }
      }
    ],
    "targets": [
      {
        "id": "accounts-local",
        "contract": "accounts",
        "admin_url_env": "ACCOUNTS_CODEATLAS_POSTGRES_URL"
      }
    ]
  }
}

Static inventory resolves supported SQL files, migration manifests, tagged templates, and database calls. Unresolved interpolation, identifier helpers, raw fragments, and dynamic SQL remain visible boundaries and are never executed.

PostgreSQL inventory v3 gives every discovered application query one stable query_<digest> identity and one typed query contract. It records placeholder order, statement class, known parameter and result shapes, referenced objects, constraints, effects, fuzz policy, eligibility, and exact block reasons. A source denial or exact config exclusion reports blocked_by_policy; malformed leading-comment markup is a gating finding and blocks the query contract. Static source alone does not invent catalog OIDs or prove answer correctness; unavailable catalog or result evidence remains explicit. Dynamic SQL, DDL, transaction control, privileged operations, filesystem/program access, external links, and unknown functions are blocked from generated execution.

Placeholder evidence is bounded: only observed positions are materialized, and position zero, missing positions, or a position above 1,024 hard-blocks the query contract. This prevents hostile or malformed SQL from turning one token into an unbounded allocation.

A target may name exact DML query IDs under query_policy.dml_query_ids. This records checked-in eligibility only: it does not make test postgres execute the query, does not waive the sandbox, and can never make mutating work eligible for single-shot execution.

codeatlas --root . init postgres
codeatlas --root . scan postgres --out postgres-inventory.json
codeatlas --root . check postgres --out postgres-check.json
codeatlas --root . usage postgres --format json --out postgres-usage.json
codeatlas --root . inspect postgres table:public.users --out postgres-inspection.json
codeatlas --root . docs postgres --format markdown --out postgres-reference.md

export ACCOUNTS_CODEATLAS_POSTGRES_URL='postgresql://postgres:password@127.0.0.1:5432/postgres'
codeatlas --root . test postgres --target accounts-local --out postgres-test.json
codeatlas --root . baseline postgres --target accounts-local --out postgres-baseline.json
codeatlas --root . diff postgres \
  --against postgres-baseline.json \
  --target accounts-local \
  --out postgres-diff.json

check postgres is static and runs the pinned Squawk version. test postgres creates a bounded database from template0, replays dependencies and migrations with declared transaction semantics, prepares supported static queries, and removes the database on success or failure. It does not execute data-changing application queries.

Baselines require complete source evidence, a clean live replay, and a supported server version. Diffs gate edited or reordered applied migrations, lost query coverage, breaking catalog changes, required columns without defaults, new constraints, and unique indexes. Safe appended migrations and additive catalog changes remain additive.

Published JSON Schemas

Every stable JSON report root has a generated Draft 2020-12 schema in schemas/. The schemas come from the same Rust models and serde attributes that write the reports. Normal tests regenerate them in memory and fail on byte drift; they never rewrite the checkout.

After an intentional report-contract change, update the registered files with an external Cargo target:

schema_cache_root="$(mktemp -d /tmp/codeatlas-schema-cache.XXXXXX)"
export CARGO_TARGET_DIR="$schema_cache_root/cargo-target"
pnpm run schemas:write

Existing reports retain their shipped integer and API version fields. Every new artifact instead uses one codeatlas.<lower-kebab-kind>/v<positive-integer> schema-version string and no parallel API version. CodeAtlas annotation keys are registered in the canonical lexicon before use. External schemas, including agentspeak.source-target/v1, are not vendored or re-published here. Explicit interop tests validate them from the neutral contracts repository. Schema publication adds packaged files, not a runtime schemas command.

With agentspeak-contracts beside this repository (or AGENTSPEAK_CONTRACTS_ROOT set explicitly), run pnpm test:interop:resolution. The separate pnpm test:interop:hqa gate stays blocked until the neutral application-inventory schema is published; it never falls back to an HQA checkout.

Configuration Rules

Configuration is strict JSON. Unknown fields fail validation so spelling errors cannot silently weaken analysis. Paths are relative to the config file unless a field explicitly requires an absolute host path. Container-runtime executable and socket paths are absolute so execution never depends on an ambient client context:

{
  "execution": {
    "isolation": {
      "backend": "container",
      "filesystem": "scratch_only",
      "network": "proxy_only",
      "processes": "planned_only",
      "container": {
        "executable": "/usr/bin/docker",
        "socket": "/var/run/docker.sock",
        "probe_image": "registry.example/codeatlas-probe@sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    }
  }
}

The image pin is a prerequisite, not a declaration that enables execution. Incomplete conformance blocks before the first target call.

Common top-level fields are:

• root: project root
• languages: any of js, ts, svelte, py, or rs
• entrypoints: explicit public or runtime roots
• include_private and include_types: code scan detail
• no_default_ignore: include normally ignored source classes
• package_exports: discover package entrypoints from package.json
• projects: named reachability projects and contexts
• execution: finite call, rate, concurrency, time, memory, process, output, artifact, and isolation ceilings
• fuzz: finite case, shrink, failure, and per-case time ceilings plus exact one-way code, http, and postgres exclusions shared by fuzz subjects
• docs, http, and postgres: domain-specific contracts

CLI limit flags may only tighten their checked-in values. Zero, unlimited sentinels, and command-line increases are rejected. The built-in defaults are materialized into every saved plan, so a later default change cannot alter a reviewed artifact.

Package exports are enabled by default. TypeScript declaration or JavaScript export targets are mapped back to maintained source when the project's TypeScript output configuration makes that mapping exact.

Source Index

Source-graph analysis uses a bounded external index by default. Set CODEATLAS_SOURCE_INDEX=0, false, or off to disable it.

Variable	Behavior
CODEATLAS_SOURCE_INDEX_DIR	Overrides the index root. The path must be absolute and disjoint from every analyzed project.
CODEATLAS_CACHE_DIR	Supplies the cache base when no source-index root is set. Otherwise CodeAtlas uses the platform or XDG cache location.
CODEATLAS_STATE_DIR	Supplies the external base for private content-addressed plans, receipts, and reproducers. The resulting execution root must be disjoint from the analyzed workspace.
CODEATLAS_SOURCE_INDEX_MAX_BYTES	Sets the byte limit. The default is 512 MiB; accepted values range from 16 MiB through 16 GiB.
CODEATLAS_METRICS=1	Writes one source-index metrics record as JSON to stderr after each source-graph analysis.

The default index root is codeatlas/source-index/v1 below the selected cache base. CodeAtlas rejects a root that contains an analyzed project or is contained by one.

The whole-graph key covers resolved project configuration, maintained source and control-file contents, the source-graph schema, and the analysis algorithm. An unchanged key reuses the complete graph. Content-addressed parser facts are also reused per file. A changed key still rebuilds the global graph, but that rebuild can reuse eligible facts for unchanged files.

Corrupt entries and entries with an invalid format or algorithm version are removed and rebuilt. There is no legacy cache reader. Successful reads refresh the entry's eviction timestamp, and pruning removes the least recently used entries after each run when the configured limit is exceeded.

The metrics record reports graph and parser-fact hits and misses, input files and bytes, writes and written bytes, current and maximum cache bytes, elapsed_ms, RSS when available, and any untracked inputs.

Local release-build measurements for the initial implementation were:

Workload	Cold	Warm	Output
CodeAtlas self-inspection	22.525 s	0.254 s	Identical SHA-256
Goobits code check	119.070 s	11.199 s	Identical SHA-256

These measurements show that identical warm reruns are fast for the measured checkouts. They are not universal performance guarantees. Changed runs reuse eligible parser facts but still rebuild the global graph, so their speedup is smaller and workload-dependent.

Evidence Posture

CodeAtlas distinguishes direct structural evidence, inferred reachability, and boundary-limited suspicion. Treat its output as evidence to verify:

• Public "no known consumer" findings are advisory because outside consumers may exist.
• Reflection, plugins, decorators, macros, dynamic imports, generated code, and dynamic SQL can limit completeness.
• A bounded context page is not a completeness claim unless all continuation pages are consumed.
• Static checks can replace redundant structural assertions, not behavioral tests whose contract is runtime behavior.

Local Development

Keep Cargo output outside the checkout, then run the complete local gate:

export CARGO_TARGET_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/codeatlas/target"
pnpm check

Useful focused checks:

pnpm test
pnpm run spec:check
pnpm run self:check
pnpm run test:postgres-live

pnpm test runs wrapper tests and the default Rust suite. The PostgreSQL live smoke is explicit because it requires a local service. The target-observed HTTP smoke belongs to the manual live OCI gate because it requires a capable container runtime; ordinary local checks do not dispatch it. pnpm run self:check writes its report below CARGO_TARGET_DIR.

Ordinary verification is local. The repository has no automatic hosted CI. The manual Live OCI isolation gate is reserved for the explicit capable-host continuation proof and should not be dispatched as part of ordinary development.

License

CodeAtlas is distributed under the terms in LICENSE.