amduat-app-next (Scaffold)

Starter project scaffold for building an app against amduatd v2.

Included handoff assets

• docs/v2-app-developer-guide.md (compact app guide)
• contracts/amduatd-api-contract.v2.json (machine contract)
• scripts/graph_client_helpers.sh (reusable shell helpers)

Quick start

1. Configure environment:

cp config/env.example config/env.local

2. Start a local daemon:

./scripts/dev_start_daemon.sh

dev_start_daemon.sh initializes the store for the selected backend and, when STORE_BACKEND=index, runs a quick startup write probe. If index writes are unhealthy, it first tries a one-time index store repair (backup + re-init) and then falls back to fs if still unhealthy (configurable via INDEX_BACKEND_PROBE, INDEX_BACKEND_REPAIR, and INDEX_BACKEND_FALLBACK in config/env.local).

3. Run startup checks against the daemon socket:

./scripts/bootstrap_check.sh

4. Run sample idempotent batch ingest:

./scripts/ingest_example.sh

5. Run sample changes consumer (recommended):

./scripts/v2_app.sh consume-changes

v2 Vertical Slice CLI

Use the integrated v2 app flow wrapper:

./scripts/v2_app.sh startup-check
./scripts/v2_app.sh ai-vertical-slice
./scripts/v2_app.sh ai-vertical-slice --skip-evals
./scripts/v2_app.sh ai-vertical-slice --auto-start-daemon
./scripts/v2_app.sh ai-agent 'doc-ai-1' 'What domain is doc-ai-1 in?' 'ms.within_domain'
./scripts/v2_app.sh ai-agent --json --require-evidence --max-steps 3 'doc-ai-1' 'What domain is doc-ai-1 in?' 'ms.within_domain'
./scripts/v2_app.sh ai-check
./scripts/v2_app.sh ai-generate 'Summarize retrieval behavior in one sentence.'
./scripts/v2_app.sh ai-generate --json 'Summarize retrieval behavior in one sentence.'
./scripts/v2_app.sh ai-answer 'doc-1' 'What topic is doc-1 in?' 'ms.within_domain'
./scripts/v2_app.sh ai-answer --json 'doc-1' 'What topic is doc-1 in?' 'ms.within_domain'
./scripts/v2_app.sh ai-answer --json --require-evidence 'doc-1' 'What topic is doc-1 in?' 'ms.within_domain'
./scripts/v2_app.sh ingest '{"idempotency_key":"k1","mode":"continue_on_error","nodes":[{"name":"doc-1"}]}'
./scripts/v2_app.sh sync-once
./scripts/v2_app.sh consume-changes --once
./scripts/v2_app.sh retrieve 'doc-1' 'ms.within_domain'
./scripts/v2_app.sh tombstone '<edge_ref>'

AI lane notes:

• Plan and scope guardrails: docs/ai-plan.md
• Deterministic seed payload: ai/fixtures/seed_batch.json
• Agent loop checkpoints: ai/runs/agent-run-*.json

Run integration coverage (requires running amduatd + jq):

./tests/integration_v2.sh

Run local cursor/handler semantics checks (no daemon required):

./tests/changes_consumer_410.sh
./tests/changes_consumer_handler.sh

Run AI connectivity and generation smoke eval (no daemon required):

./tests/ai_eval.sh
./tests/ai_answer_eval.sh

Run a fast end-to-end smoke (startup + ingest + sync + retrieve + tombstone):

./scripts/smoke_v2.sh

Notes

• This scaffold assumes local Unix-socket access to amduatd.
• Graph cursors are opaque and must be persisted exactly as returned.
• ./scripts/sync_loop.sh and sync-loop CLI are deprecated compatibility aliases.
• Keep contracts/amduatd-api-contract.v2.json in sync with upstream when you pull updates.