From cfc784e45ae1410826f0665cbf0a33a1ce6b142e Mon Sep 17 00:00:00 2001 From: giles Date: Sun, 7 Jun 2026 12:34:07 +0000 Subject: [PATCH] =?UTF-8?q?artdag:=20public=20API=20facade=20lib/artdag/ap?= =?UTF-8?q?i.sx=20=E2=80=94=20load=20list=20+=20surface=20index?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reference index (matching datalog/persist convention): canonical load order and the full public surface across all 10 modules, plus artdag/version. Wired into the conformance load list. Total 158/158 unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- lib/artdag/api.sx | 91 +++++++++++++++++++++++++++++++++++++++ lib/artdag/conformance.sh | 1 + 2 files changed, 92 insertions(+) create mode 100644 lib/artdag/api.sx diff --git a/lib/artdag/api.sx b/lib/artdag/api.sx new file mode 100644 index 00000000..39520b0e --- /dev/null +++ b/lib/artdag/api.sx @@ -0,0 +1,91 @@ +; lib/artdag/api.sx — public API index for the artdag content-addressed dataflow +; DAG engine. Reference-only: `load` is an epoch-protocol command, not an SX +; function, so this file cannot reload the modules from inside another `.sx`. To +; set up a session, issue these loads in order (after spec/stdlib.sx + lib/r7rs.sx, +; the lib/datalog/* modules, and the lib/persist/* modules): +; +; (load "lib/artdag/dag.sx") +; (load "lib/artdag/analyze.sx") ; requires lib/datalog/* +; (load "lib/artdag/plan.sx") +; (load "lib/artdag/execute.sx") ; requires lib/persist/* +; (load "lib/artdag/optimize.sx") +; (load "lib/artdag/federation.sx") +; (load "lib/artdag/cost.sx") +; (load "lib/artdag/serialize.sx") +; (load "lib/artdag/stats.sx") +; (load "lib/artdag/fault.sx") +; +; (lib/artdag/conformance.sh runs this load list automatically.) +; +; ── Public API surface ───────────────────────────────────────────── +; +; Model / content addressing (dag.sx): +; (artdag/node op inputs params) node spec (non-commutative) +; (artdag/cnode op inputs params) commutative node spec +; (artdag/content-id node) structural digest "node:..." +; (artdag/build entries) {:ok :nodes :names :order} | {:ok false :error} +; entry = (name op (input-names...) params [commutative?]) +; (artdag/dag-id dag name) local name -> content-id +; (artdag/dag-get dag id) content-id -> node +; (artdag/dag-node-by-name dag name) name -> node +; (artdag/dag-order dag) topo-ordered content-ids +; (artdag/node-count dag) distinct node count +; +; Analyze on Datalog (analyze.sx): +; (artdag/analyze dag) -> datalog db +; (artdag/deps-of db id) direct dependencies +; (artdag/dependents-of db id) direct dependents +; (artdag/reachable-from db id) transitive dependents +; (artdag/ancestors-of db id) transitive dependencies +; (artdag/dirty-closure dag changed) changed nodes + all dependents +; +; Plan (plan.sx): +; (artdag/plan dag cap) topo batches under width cap (0 = unlimited) +; (artdag/plan-dirty dag changed cap) incremental plan over the dirty closure +; (artdag/plan-batches/-width/-size/-flatten plan) +; +; Execute (execute.sx): +; (artdag/op-table-runner table) runner from op-name -> (fn (params inputs)) +; (artdag/run dag runner cache) full memoized run +; (artdag/run-dirty dag changed runner cache) +; (artdag/execute dag plan runner cache) -> {:results :recomputed :hits} +; (artdag/result-of/recompute-count/hit-count/recomputed exec) +; cache = a lib/persist kv backend (persist/open) +; +; Optimize (optimize.sx): +; (artdag/dce dag outputs) drop nodes not feeding the outputs +; (artdag/cse entries) == build (sharing is free from content ids) +; (artdag/fuse entries fusible?) collapse fusible unary chains -> pipeline nodes +; (artdag/fusing-runner base-runner) runner that replays pipeline stages +; (artdag/optimize entries outputs fusible?) fuse then dce +; +; Federation (federation.sx): +; (artdag/fed-open) {:cache :prov} +; (artdag/fed-run fed dag runner) run against the instance cache +; (artdag/fed-export fed peer-id) bundle of {:cid :result :peer} +; (artdag/fed-import fed bundle trusted?) trust-gated import + provenance +; (artdag/fed-pull fed fetch-fn peer-id trusted?) pull via injected transport +; (artdag/fed-invalidate fed peer-id) drop a peer's results (peer-scoped) +; +; Cost / scheduling (cost.sx): +; (artdag/const-cost) (artdag/op-cost table) cost-fn (op params) -> number +; (artdag/critical-path dag cost-fn) longest weighted path +; (artdag/makespan dag plan cost-fn) estimated wall-clock under a plan +; (artdag/total-work dag cost-fn) (artdag/speedup dag plan cost-fn) +; +; Serialize (serialize.sx): +; (artdag/dag->wire dag) (artdag/wire->dag records) portable record form +; (artdag/wire-verify records) content-id integrity check +; (artdag/dag->string dag) (artdag/string->dag s) text transport +; +; Stats (stats.sx): +; (artdag/hit-ratio exec) +; (artdag/work-recomputed/work-saved exec dag cost-fn) +; (artdag/savings-ratio exec dag cost-fn) (artdag/exec-summary exec dag cost-fn) +; +; Fault tolerance (fault.sx): +; (artdag/fail reason) (artdag/failed? v) +; (artdag/run-safe dag runner cache) -> {:results :recomputed :hits :failed} +; (artdag/failed-nodes/failure-count/all-ok? exec) + +(define artdag/version "1.0") diff --git a/lib/artdag/conformance.sh b/lib/artdag/conformance.sh index 7efa9077..f71d193a 100755 --- a/lib/artdag/conformance.sh +++ b/lib/artdag/conformance.sh @@ -51,6 +51,7 @@ run_suite() { (load "lib/artdag/serialize.sx") (load "lib/artdag/stats.sx") (load "lib/artdag/fault.sx") +(load "lib/artdag/api.sx") (epoch 2) (eval "(define artdag-test-pass 0)") (eval "(define artdag-test-fail 0)")