# Repository Context BOM

`renma bom` emits a declared repository manifest for review and CI consumers.
Renma currently emits only the v3 BOM schema. V2 was the first supported
long-term contract; v3 changes the embedded Readiness check contract described
below. Earlier v1 output was an experimental pre-contract surface removed
before broader adoption. Renma does not provide a legacy output mode, although
the published v2 schema remains available for consumers validating archived
artifacts.

The BOM is not a runtime usage report. It does not describe what an LLM actually consumed, assemble prompts, choose task-specific context, inject context into agents, execute agents, call an LLM, import consumed-context evidence, or collect telemetry.

The User Manual's
[authoritative metadata reference](user-manual.md#authoritative-metadata-reference)
defines which declarations feed BOM projections. This document owns the BOM
schema, snapshot, ordering, and reproducibility semantics rather than a
separate metadata field inventory.

```mermaid
flowchart TD
  Sources["Repository files and configuration"]
  Snapshot["One collected in-memory repository snapshot"]
  Catalog["Catalog and dependency graph"]
  Diagnostics["Diagnostics and Readiness"]
  Governance["Lifecycle and ownership evidence"]
  Security["Security posture and policy inventory"]
  Bom["Repository Context BOM v3"]
  Json["Authoritative JSON"]
  Markdown["Markdown review projection"]
  Revision["Git, CI, or PR context supplies revision identity"]
  Runtime["Runtime consumed-context evidence — separate artifact"]
  Sources --> Snapshot
  Snapshot --> Catalog
  Snapshot --> Diagnostics
  Snapshot --> Governance
  Snapshot --> Security
  Catalog --> Bom
  Diagnostics --> Bom
  Governance --> Bom
  Security --> Bom
  Bom --> Json
  Bom --> Markdown
  Revision -.-> Bom
```

The diagram separates collection from projection: every BOM section is derived
from one collected snapshot, JSON is authoritative, and Markdown is a review
view. `--omit-generated-at` removes generation-time noise only. Revision
identity stays in the surrounding Git, CI, or pull-request context, and any
runtime consumed-context evidence remains a separate artifact.

## Snapshot Contract

One BOM execution is derived from one in-memory repository snapshot:

1. Resolve configuration once.
2. Discover and read repository artifacts once.
3. Parse documents once.
4. Build the catalog once.
5. Derive graph, findings, diagnostics, Context Lens evidence, readiness, security posture, security policy inventory, and executable-surface inventory from that same snapshot.
6. Format JSON or Markdown only after the complete report has been built.

Renma does not freeze the working tree while another process is modifying it. If files change during collection, the BOM reflects the artifacts Renma read for that execution; after collection, all report sections are derived from the collected snapshot.

## Output Authority

JSON is the authoritative BOM output. Markdown is a compact review projection for pull requests and humans; it is not the canonical serialization.

Array ordering is deterministic, locale-independent ECMAScript UTF-16
code-unit order and is part of Renma's output contract. Asset `sourcePath`
values remain repository-relative. `root` and `configPath` remain absolute
paths from the current environment.

Assets use `ownership.declaredOwner`, `ownership.effectiveOwner`,
`ownership.source`, and optional `ownership.inheritedFrom`. Readiness uses the
effective owner.

## Reproducibility

`--omit-generated-at` means only:

- omit the run-time `generatedAt` field;
- remove clock-based differences caused by that field.

It does not mean:

- ignore `lastReviewedAt`, `reviewCycle`, or `expiresAt`;
- suppress freshness diagnostics;
- normalize `root` or `configPath`;
- make output portable across different checkout directories;
- hide file moves;
- guarantee identical output across different evaluation dates;
- freeze a repository while another process is modifying it.

Supported guarantee:

> With the same checkout path, config path, repository contents, Renma version, and UTC evaluation date, repeated `--omit-generated-at` runs should produce byte-identical JSON.

Freshness evaluation uses the UTC calendar date. Metadata dates remain part of the snapshot and must not be removed as timestamp noise. A real file move is a meaningful BOM change because `sourcePath` is repository evidence. Portable byte-for-byte output across different checkout paths is not a v3 guarantee; locale differences alone do not change ordering.

## Schema Evolution

`schemaVersion` represents the consumer-facing BOM schema. `generator.version` represents the Renma implementation version and is not the schema version.

V2 was the first supported long-term contract for normalized ownership,
first-class support assets, and static support relationships. V3 carries those
fields forward and changes the embedded Readiness check collection. Consumers
must inspect `schemaVersion` independently from `generator.version`. An
incompatible contract must use a new schema version.

Within a schema, changes should be backward-compatible and additive:

- existing fields must not be removed, renamed, or given incompatible types or meanings;
- new optional fields may be added when a real consumer requires them;
- enum additions are consumer-visible changes and must be documented;
- a breaking contract requires a new schema version rather than silently changing existing semantics.

Treat `owns_local_resource`, `statically_references`, `inherits_owner`, and
`inherits_policy` as static repository evidence, not runtime behavior. Branch
on `schemaVersion`; `generator.version` is provenance only.

The published [BOM v3 JSON Schema](schemas/repository-context-bom-v3.schema.json)
is the machine-readable contract. `generatedAt` is required when `outputMode`
is `default` and forbidden when `outputMode` is `omit_generated_at`.
`configPath` remains optional and is absent when no configuration file was
loaded. `executableSurfaceInventory` remains optional at the BOM v3 schema
boundary, preserving the v2 field requirements. Current Renma versions emit it
unconditionally. All other top-level
fields are required. Optional lifecycle, version, status, target-resolution,
and inherited-ownership fields appear only when their evidence exists. Owner
values are explicitly nullable; missing optional fields are omitted rather
than serialized as `null`.

BOM v3 carries forward v2's lifecycle status vocabulary and additively accepts
`revoked`. Asset and `lifecycle` projections may include optional
`statusReason` and `statusChangedAt` strings adjacent to status. These are
current declaration evidence only: BOM does not store transition history,
infer dates, schedule expiry, restore an asset, or propagate revocation.
Archived v2 documents without the optional fields remain valid under the
published v2 schema; the same fields remain optional in v3.

Arrays are deterministically ordered by their identity/path keys, and count
fields are non-negative integers. Count maps contain every declared enum
member, including zero counts. Policy source ordering is `local`,
`security_profile`, `repository_config`, `owning_skill`. Static support
relationships use `owns_local_resource`, `statically_references`,
`inherits_owner`, and `inherits_policy`.

The additive `executableSurfaceInventory` field retains its own explicit schema
identifier, `renma.executable-surface-inventory.v1`. Its summary counts,
path-identified surface rows, line-level invocation rows, content and inventory
fingerprints, reachability depth, interpreter hints, and bounded effective
policy correlation are complete in JSON. Current output also includes
invocation governance on every invocation and an invocation-governance
aggregate on every surface, complete executable dependency rows, and strict
per-surface incoming/outgoing and direct/transitive/unreached summaries.
Surface policy evidence remains separate and is never replaced by caller or
dependency evidence.

The inventory's closed analyzer enum additively includes `powershell` and
`batch`, and its launcher enum additively includes `pwsh`, `powershell`, `cmd`,
and their `.exe` spellings. Existing fields, analyzer values, launcher values,
relation meanings, and ordering are unchanged from v2. The nested
executable-surface inventory remains v1. Consumers that exhaustively switch on
closed enum values must accept these additions before processing repositories
with newly recognized Windows evidence.

Invocation governance retains prepared `source-artifact` and `owning-skill`
policy relationships without merging fields or applying precedence. Its
effective fingerprints are a sorted set of visible variants, not conflicts or
safety verdicts. The Markdown BOM renders separate surface-policy,
invocation-context-policy, and multiple-variant summaries plus compact
per-surface dependency counts and compact dependency rows; it does not print
complete fingerprints or source content. Surface rows are sorted by repository
path; invocation rows are sorted by source path, line, launcher, and target;
dependency rows are sorted by source path, line, analyzer, relation, target
candidates, and raw specifier.

Invocation rows combine the established fenced helper-command evidence with
bounded inline `Run`/`Run:` evidence. The inline command must be a single-line
mdast `inlineCode` node directly under a paragraph, immediately after the exact
structurally textual cue, and outside blockquotes. Text plus text-only emphasis
or strong formatting may form the cue; links, images, inline code, non-comment
HTML, reference-like nodes, and unsupported descendants may not. Both forms use
the same launcher, target resolution, occurrence ordinal, governance, and
direct/transitive reachability semantics. BOM v3 adds no syntax-origin field
and does not distinguish fenced from inline presentation. Ordinary inline code,
quoted examples, broader prose, other verbs or languages, and chained secondary
code spans do not create invocation rows.

When a recognized command path is also a static text reference, reference
evidence remains deduplicated by source path, source line, and target. One
inline `Run` occurrence therefore contributes one reference and one invocation,
not two references.

Repeated declarations, including identical declarations on one source line,
remain separate dependency rows and contribute separately to dependency
totals. Public BOM evidence exposes their shared line and distinct occurrence
ordinals, not the private source offsets used during collection. Per-surface
incoming/outgoing counts and static reachability instead use one canonical
graph edge for each unique source path and normalized target among `resolved`
and `noncanonical` rows. Import and re-export syntax for the same source-target
pair therefore stays auditable without multiplying graph topology.

BOM consumers must first branch on the presence of
`executableSurfaceInventory`, then inspect its nested `schema` identifier
before consuming its nested fields. The inventory remains additive v1. V3
carries forward the optional field boundaries introduced for Renma 0.27.0: the summary counts,
surface `invocationGovernance`, and invocation `governance` fields are optional
in the published schema. Executable `dependencies`, new dependency summary
counts, and surface `dependencyEvidence` are likewise optional for earlier
0.27.x BOM compatibility. Current Renma output emits all of them
unconditionally. Whenever a new governance, dependency, analyzer-count,
relation-count, or dependency-summary object is present, all of its nested
fields are required and unknown nested fields are rejected. Existing inventory
fields retain their established requirements.

The Readiness summary is a closed contract for asset, ownership, graph,
diagnostic, workflow, Context Lens, security posture, and security policy
inventory evidence. Coverage and readiness percentages are constrained to
`0..100`. Security posture top-finding entries require an ID, non-negative
count, and maximum severity. Security policy `assetKinds` is a complete count
map containing every generated artifact kind, including zero values.
Current output additively emits `externalUploadGovernance` in each security
policy inventory. Its five required counts distinguish denied upload, upload
allowed with approval required, upload allowed with approval not required,
upload allowed with the approval requirement unspecified, and unspecified
upload permission. The field remains optional in v3; archived v2 documents are
validated against the retained v2 schema. When present, its nested shape is
closed and all five counts are required.

### V2 to v3 migration

V3 removes the producerless `layout.disallowed_skill_assets` Readiness check
and adds `skills.support_integrity`. The new check represents explicitly
referenced Skill support that cannot be resolved or inspected. It uses
authoritative `inspectionCoverage` issues whose `expectationSource` is
`static-support-reference` for excluded, symlinked, unreadable, oversized,
depth-limited, and unsupported support, plus missing-reference Finding evidence
where inspection coverage intentionally has no missing-path issue. Suppression
may remove an ordinary Finding from the active Finding list, but cannot make
the embedded Readiness check claim that authoritative support inspection is
complete. Unrelated repository inspection issues and unreferenced Skill-local
files do not affect this check, and it creates no placement policy. Consumers
that key, count, compare, or allowlist embedded Readiness checks must migrate to
the new ID and meaning. No other BOM field, type, or nested schema identifier
changes. Locale-independent ordering fixes restore the already documented
deterministic ordering contract and therefore do not independently require
another schema version.

Representative top-level JSON (nested objects are shortened for readability;
the schema defines every nested field):

```json
{
  "schemaVersion": "renma.repository-context-bom.v3",
  "outputMode": "omit_generated_at",
  "generator": { "name": "renma", "version": "<installed-version>" },
  "root": "/checkout/repository",
  "scope": { "type": "declared_repository_manifest", "runtimeUsage": false, "telemetryCollected": false },
  "summary": { "scannedFileCount": 0, "assetCount": 0, "dependencyCount": 0, "resolvedDependencyCount": 0, "unresolvedDependencyCount": 0, "ownedAssetCount": 0, "unownedAssetCount": 0, "readinessScore": 100, "readinessLevel": "ready", "diagnosticCounts": { "error": 0, "warning": 0, "info": 0 } },
  "assets": [],
  "dependencies": [],
  "readiness": { "score": 100, "level": "ready", "checks": [], "summary": {} },
  "securityPosture": { "totalSecurityFindings": 0, "riskClasses": { "violation": 0, "suspicious": 0, "advisory": 0, "unclassified": 0 }, "severities": { "critical": 0, "high": 0, "medium": 0, "low": 0 }, "highOrCritical": 0, "topFindingIds": [] },
  "securityPolicyInventory": {},
  "executableSurfaceInventory": { "schema": "renma.executable-surface-inventory.v1", "summary": {}, "surfaces": [], "invocations": [], "dependencies": [] },
  "diagnostics": []
}
```

Generated representative reports are validated against the published schema in
the contract test suite.

`--omit-generated-at` does not make the report a generic canonical JSON format or a portable artifact.

## Source Provenance

BOM v3 provenance is deliberately repository-local:

- repository-relative source paths;
- per-asset content hashes;
- generator name and version;
- current absolute `root` and `configPath` information when available;
- lifecycle, dependency, diagnostic, readiness, security posture, security policy inventory, and executable-surface evidence.

Executable-surface evidence is static repository visibility, not a claim about
runtime use or safety. Static dependency reachability does not prove runtime
execution, and an uninvoked surface is not necessarily unused. It does not
execute files, follow symbolic links, inspect
permission bits, or scan package manifests, GitHub Actions, Dockerfiles, Git
hooks, remote scripts, ordinary external commands, or unrelated repository
files. Such sources remain intentionally unsupported in this inventory slice.

Renma does not automatically invoke Git or add Git commit, branch, tag, or
dirty-state fields. Git revision identity comes from the surrounding Git, CI,
artifact, or pull-request context.

## Consumed-Context Evidence

The BOM v3 schema describes declared repository state. Consumed-context evidence
must not redefine or mutate that meaning.

Runtime evidence should be a separate artifact or explicitly separate
attachment. Such a record should relate back to a BOM using stable values such
as a BOM digest or snapshot identity, asset ID, asset content hash, producer
identity and version, and observation timestamp.

External agents, editor integrations, wrappers, or CI tools may produce those
signals. They remain outside the BOM contract and Renma's role as a static
repository analyzer; Renma is not a telemetry collector, runtime wrapper,
dashboard, or provider gateway.