aoa-stats

aoa-stats is the central statistical measurability organ of OS Abyss. It defines shared statistical compatibility, federates owner-local root stats/ ports, and turns bounded source-owned evidence into deterministic read models. Those models help humans and tools see populations and movement; they do not become workflow, proof, route, memory, KAG, runtime, identity, or owner truth.

Current release: v0.2.0. See CHANGELOG for release notes.

Start here

1. AGENTS.md — operating law and route boundaries
2. DESIGN.md — durable source/mechanics architecture
3. stats/README.md — authored stats source home
4. mechanics/README.md — operation and payload map
5. skills/README.md — admitted owner-local callable procedure
6. docs/BOUNDARIES.md — authority stop-lines
7. docs/ARCHITECTURE.md — derived-view layers
8. ROADMAP.md and README.md#current-v0-surface — current contour
9. docs/decisions/ — durable rationale, not status
10. VALIDATION.md — on-demand focused and full checks

Authority map

Concern	Authoritative surface	Weaker companions
shared measurement and outcome-observation grammar	stats/measurement-contract/	pure implementation, local packets, C10 producer adapters, MCP representation
local-port compatibility and owner coverage	stats/federation/	workspace scans and consumer caches
owner-local metric meaning	each owner's root stats/port.manifest.json	central inventory and cross-repo views
receipt admission	stats/intake-contract/ and schemas/stats-event-envelope.schema.json	examples, live registry, generated summaries
read-model lifecycle and meaning	stats/read-models/{active,deferred,retired}/*.profile.json	public catalog, generated output, MCP projection
non-catalog stats contracts	stats/operation-contracts/active/*.operation.json	part-local payload and root compatibility routes
operation and focused-validation ownership	mechanics/topology.json and its named package or part routes	root compatibility routes
repository callable procedure	skills/aoa-stats/SKILL.md and skills/port.manifest.json	managed OS user-profile copy
executable measurement semantics	stats/measurement-contract/ as source, src/aoa_stats_builder/measurement.py and src/aoa_stats_builder/outcome.py as pure implementations	validators and access adapters
stats read contract	stats/surface-catalog/CODEX_MCP.md	stack-owned aoa-stats-mcp implementation and project registration
public contracts	catalog schemas under schemas/	examples and docs
public derived output	generated/*.min.json	KAG indexes and consumer caches
local live output admission	stats/read-models/active/*.profile.json#live_state_capable	state/generated/, live catalog, watcher output
current operations	nearest mechanic part	compatibility docs and root launchers

Generated, compact, KAG, MCP, and installed surfaces remain subordinate to their authored source and named owner inputs.

Current v0 surface

The checked source home carries the shared measurement grammar, local-port federation contract and owner inventory, receipt admission, authored read-model and operation contracts, deterministic projection, stable public schemas, and read-only catalog access. Exact lifecycle state comes from the profiles under stats/read-models/; non-catalog maturity comes from stats/operation-contracts/; the compact public projection is generated/summary_surface_catalog.min.json.

Public-root contracts

The root is intentionally narrow:

• schemas/ — stable catalog and receipt contracts
• generated/ — committed public read models
• scripts/ — public, compatibility, and repo-wide commands
• skills/ — one admitted owner-local callable bundle and its port manifest
• tests/ — repository and public-contract checks
• docs/ — repository-wide architecture, boundaries, decisions, release guidance, and history
• examples/codex_plane_deployment_summary.example.json — retained external compatibility fixture
• manifests/artifact_bundles/ — public summary-catalog bundle

Operation-owned config, docs, examples, supporting schemas, manifests, systemd templates, builders, validators, and focused tests live under their mechanic parts. scripts/validate_mechanics_topology.py enforces this placement contract. A focused test shared by several parts may live at the mechanic-package level only when it constrains one shared importable core and that package payload root is declared in mechanics/topology.json. Its single package VALIDATION.md owner must be declared separately by the exact package_validation_surface field; an undeclared package procedure is not an owner.

The operation route starts at mechanics/README.md; its machine-readable inventory and source-family crosswalk live in mechanics/topology.json. The root README does not replay that changing part inventory.

Build, live use, and verification

Use the on-demand checks in VALIDATION.md, then follow the nearest changed family's AGENTS.md and topology-declared package or part VALIDATION.md. Script-specific working guidance stays in scripts/AGENTS.md.

For registered owner-local feeds and watcher use, follow the live-receipt-refresh operator guide and its adjacent VALIDATION.md.

The active registry and watcher templates live in mechanics/recurrence/parts/live-receipt-refresh/. Local refresh writes under ignored state/; committed public output stays under generated/. Local live materialization includes only active profiles with live_state_capable: true, and its catalog lists only outputs actually materialized. Reference-only profiles remain in the committed catalog and retired profiles remain explicit stale-cleanup inputs. The authored profiles and indexed decisions own the exact current admission and lifecycle rationale.

For read-only MCP use, follow stats/surface-catalog/CODEX_MCP.md. The stack-owned aoa-stats-mcp is the single MCP access implementation. The statistical core and its direct packet-read contract do not depend on MCP runtime.

Boundaries

• Source repositories own payload meaning and current domain truth.
• aoa-evals owns bounded proof and verdict interpretation.
• aoa-stats owns shared statistical compatibility, deterministic derivation, and the shape of its read models; local owners retain metric meaning.
• C10 outcome receipts remain content-minimized owner observations; they grant no causal, semantic, effect, or policy-training authority.
• Missing, stale, rejected, or unregistered evidence stays visible; it is not converted into success or zero.
• A count, trend, or window cannot by itself prove mastery, intent, causality, self-agency, or owner health.

Contribution and release

Use CONTRIBUTING.md, docs/RELEASING.md, and CHANGELOG.md. Release commands stay in the release guide; the normal repository gate stays in VALIDATION.md.