Add index-init aware daemon startup helper and docs updates

.gitignore

@@ -1,7 +1,11 @@
 # Local daemon/store runtime state
 .amduat-asl/
+.amduat-asl-*/
 amduatd.sock
+.amduatd-*.sock
 .cursor
+.amduatd-*.pid
+.amduatd-*.log
 
 # Local configuration overrides
 config/env.local

README.md

@@ -16,19 +16,25 @@ Starter project scaffold for building an app against `amduatd` v2.
 cp config/env.example config/env.local
 ```
 
-2. Run startup checks against a running `amduatd` socket:
+2. Start a local daemon:
+
+```sh
+./scripts/dev_start_daemon.sh
+```
+
+3. Run startup checks against the daemon socket:
 
 ```sh
 ./scripts/bootstrap_check.sh
 ```
 
-3. Run sample idempotent batch ingest:
+4. Run sample idempotent batch ingest:
 
 ```sh
 ./scripts/ingest_example.sh
 ```
 
-4. Run sample changes sync loop:
+5. Run sample changes sync loop:
 
 ```sh
 ./scripts/sync_loop.sh
@@ -40,9 +46,9 @@ Use the integrated v2 app flow wrapper:
 
 ```sh
 ./scripts/v2_app.sh startup-check
-./scripts/v2_app.sh ingest '{"idempotency_key":"k1","mode":"continue_on_error","nodes":[{"name":"doc:1"}]}'
+./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 retrieve 'doc:1' 'ms.within_domain'
+./scripts/v2_app.sh retrieve 'doc-1' 'ms.within_domain'
 ./scripts/v2_app.sh tombstone '<edge_ref>'
 ```
 

config/env.example

@@ -1,8 +1,14 @@
 # Copy to config/env.local and edit as needed
-SOCK="../amduatd.sock"
+SOCK="amduatd.sock"
 BASE="http://localhost"
 SPACE="app1"
 
+# Optional daemon startup defaults (used by scripts/dev_start_daemon.sh)
+STORE_ROOT=".amduat-asl"
+STORE_BACKEND="index"
+# AMDUATD_BIN="/path/to/amduatd"
+# ASL_BIN="/path/to/amduat-asl"
+
 # Incremental sync configuration
 SYNC_LIMIT="200"
 SYNC_WAIT_MS="15000"

docs/v2-app-developer-guide.md

@@ -14,10 +14,13 @@ For machine-readable contracts, see `registry/amduatd-api-contract.v2.json`.
 Minimal local run:
 
 ```sh
-./vendor/amduat/build/amduat-asl init --root .amduat-asl
+./vendor/amduat/build/amduat-asl index init --root .amduat-asl
 ./build/amduatd --root .amduat-asl --sock amduatd.sock --store-backend index
 ```
 
+If you run with `--store-backend index`, initialize the root with `index init`
+instead of `init`.
+
 ## 2) Request Conventions
 
 - Use `X-Amduat-Space: <space_id>` for app isolation.

scripts/dev_start_daemon.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="${ROOT_DIR}/config/env.local"
+if [[ ! -f "${ENV_FILE}" ]]; then
+  ENV_FILE="${ROOT_DIR}/config/env.example"
+fi
+# shellcheck source=/dev/null
+source "${ENV_FILE}"
+
+STORE_ROOT="${STORE_ROOT:-${ROOT_DIR}/.amduat-asl}"
+STORE_BACKEND="${STORE_BACKEND:-index}"
+SPACE="${SPACE:-app1}"
+SOCK="${SOCK:-${ROOT_DIR}/amduatd.sock}"
+if [[ "${STORE_ROOT}" != /* ]]; then
+  STORE_ROOT="${ROOT_DIR}/${STORE_ROOT}"
+fi
+if [[ "${SOCK}" != /* ]]; then
+  SOCK="${ROOT_DIR}/${SOCK}"
+fi
+
+# Try common local build paths first, then PATH.
+AMDUATD_BIN="${AMDUATD_BIN:-}"
+if [[ -z "${AMDUATD_BIN}" ]]; then
+  for cand in \
+    "${ROOT_DIR}/vendor/amduat-api/build/amduatd" \
+    "${ROOT_DIR}/vendor/amduat-api/build-asan/amduatd"; do
+    if [[ -x "${cand}" ]]; then
+      AMDUATD_BIN="${cand}"
+      break
+    fi
+  done
+  if [[ -z "${AMDUATD_BIN}" ]] && command -v amduatd >/dev/null 2>&1; then
+    AMDUATD_BIN="$(command -v amduatd)"
+  fi
+fi
+
+ASL_BIN="${ASL_BIN:-}"
+if [[ -z "${ASL_BIN}" ]]; then
+  for cand in \
+    "${ROOT_DIR}/vendor/amduat-api/vendor/amduat/build/amduat-asl" \
+    "${ROOT_DIR}/vendor/amduat-api/build/vendor/amduat/amduat-asl"; do
+    if [[ -x "${cand}" ]]; then
+      ASL_BIN="${cand}"
+      break
+    fi
+  done
+  if [[ -z "${ASL_BIN}" ]] && command -v amduat-asl >/dev/null 2>&1; then
+    ASL_BIN="$(command -v amduat-asl)"
+  fi
+fi
+
+if [[ -z "${AMDUATD_BIN}" || ! -x "${AMDUATD_BIN}" ]]; then
+  echo "missing amduatd binary; set AMDUATD_BIN" >&2
+  exit 1
+fi
+if [[ -z "${ASL_BIN}" || ! -x "${ASL_BIN}" ]]; then
+  echo "missing amduat-asl binary; set ASL_BIN" >&2
+  exit 1
+fi
+
+mkdir -p "${STORE_ROOT}"
+
+if [[ "${STORE_BACKEND}" == "index" ]]; then
+  if ! "${ASL_BIN}" index state --root "${STORE_ROOT}" >/dev/null 2>&1; then
+    echo "initializing index-backed ASL store at ${STORE_ROOT}" >&2
+    "${ASL_BIN}" index init --root "${STORE_ROOT}"
+  fi
+else
+  if ! "${ASL_BIN}" log inspect --root "${STORE_ROOT}" >/dev/null 2>&1; then
+    echo "initializing ASL store at ${STORE_ROOT}" >&2
+    "${ASL_BIN}" init --root "${STORE_ROOT}"
+  fi
+fi
+
+echo "starting amduatd: root=${STORE_ROOT} sock=${SOCK} backend=${STORE_BACKEND} space=${SPACE}" >&2
+exec "${AMDUATD_BIN}" --root "${STORE_ROOT}" --sock "${SOCK}" --store-backend "${STORE_BACKEND}" --space "${SPACE}"

scripts/ingest_example.sh

@@ -8,12 +8,12 @@ source "${ROOT_DIR}/src/client.sh"
 payload='{
   "idempotency_key":"app1-seed-0001",
   "mode":"continue_on_error",
-  "nodes":[{"name":"doc:1"},{"name":"topic:alpha"}],
+  "nodes":[{"name":"doc-1"},{"name":"topic-alpha"}],
   "edges":[
     {
-      "subject":"doc:1",
+      "subject":"doc-1",
       "predicate":"ms.within_domain",
-      "object":"topic:alpha",
+      "object":"topic-alpha",
       "provenance":{
         "source_uri":"urn:app:seed",
         "extractor":"app-loader",

src/config.sh

@@ -35,7 +35,7 @@ amduat_config_load() {
   if [[ -n "${override_connect_timeout}" ]]; then CURL_CONNECT_TIMEOUT_SECONDS="${override_connect_timeout}"; fi
   if [[ -n "${override_max_time}" ]]; then CURL_MAX_TIME_SECONDS="${override_max_time}"; fi
 
-  SOCK="${SOCK:-../amduatd.sock}"
+  SOCK="${SOCK:-amduatd.sock}"
   BASE="${BASE:-http://localhost}"
   SPACE="${SPACE:-app1}"
 

tests/integration_v2.sh

@@ -36,8 +36,8 @@ assert_contains "${startup_out}" '"ok"'
 run_id="$(date +%s)"
 trace_id="trace-it-${run_id}"
 idempotency_key="it-seed-${run_id}"
-doc_name="doc:it${run_id}"
-topic_name="topic:italpha${run_id}"
+doc_name="doc-it${run_id}"
+topic_name="topic-italpha${run_id}"
 payload="$(cat <<JSON
 {
   "idempotency_key":"${idempotency_key}",