amduat/docs/index-log-api-sketch.md

Index/Log API Surface (Sketch)

This document is a one-page sketch of the planned public API for ASL index/log support. It is non-normative and intended to guide header design.

ASL Index/Log Types (Draft)

typedef uint64_t amduat_asl_snapshot_id_t;
typedef uint64_t amduat_asl_log_position_t; // inclusive logseq upper bound

typedef struct {
  amduat_asl_snapshot_id_t snapshot_id;
  amduat_asl_log_position_t log_position;
} amduat_asl_index_state_t;

Core Store API (Draft)

// Initialization and config.
bool amduat_asl_store_index_init(...);

// PUT/GET with index state reporting.
amduat_asl_store_error_t amduat_asl_store_put_indexed(
    amduat_asl_store_t *store,
    amduat_artifact_t artifact,
    amduat_reference_t *out_ref,
    amduat_asl_index_state_t *out_state);

amduat_asl_store_error_t amduat_asl_store_get_indexed(
    amduat_asl_store_t *store,
    amduat_reference_t ref,
    amduat_asl_index_state_t state,
    amduat_artifact_t *out_artifact);

Index/Log Introspection (Draft)

// Snapshot/log position queries.
bool amduat_asl_index_current_state(amduat_asl_store_t *store,
                                    amduat_asl_index_state_t *out_state);

// Segment and log inspection (read-only).
bool amduat_asl_log_scan(amduat_asl_store_t *store, ...);
bool amduat_asl_segment_scan(amduat_asl_store_t *store, ...);

Expected Error Surfaces

• AMDUAT_ASL_STORE_ERR_INTEGRITY for malformed index segments or log records.
• AMDUAT_ASL_STORE_ERR_IO for underlying I/O faults.
• AMDUAT_ASL_STORE_ERR_NOT_FOUND for absent artifacts or missing segments.
• AMDUAT_ASL_STORE_ERR_UNSUPPORTED for unsupported encoding versions.

These are illustrative; exact error codes and mapping will be finalized when headers are introduced.