docs: add Contract sections + tag tests to contract items (Tier 2 — 10 files)

org/core-memory.org

@@ -34,6 +34,17 @@ Git tracks changes to files. Passepartout tracks changes to live memory state. T
 
 The tradeoff is memory usage: each snapshot is a deep copy of every object in active memory. 20 snapshots means 20x the active memory size. For a typical knowledge base of 10,000 objects, this is manageable (~100MB for 20 snapshots).
 
+** Contract
+
+1. (ingest-ast ast &key scope): stores AST nodes in ~*memory-store*~.
+   Detaches children, gives each an ID, computes Merkle hash. Returns the
+   root ID string.
+2. (memory-object-hash object): returns the SHA-256 Merkle hash of the
+   object's content. Hash is deterministic — same content → same hash.
+3. (memory-object-get id): retrieves a stored object by ID, or nil.
+4. (snapshot-memory): deep-copies ~*memory-store*~ to ~*memory-snapshots*~.
+5. (rollback-memory snap-index): restores ~*memory-store*~ from a snapshot.
+
 * Implementation
 
 ** Package Context
@@ -358,6 +369,7 @@ Verifies that the Merkle hash is deterministic and consistent across independent
 (in-suite memory-suite)
 
 (test merkle-hash-consistency
+  "Contract 2: identical ASTs produce identical Merkle hashes."
   (let* ((ast1 '(:type :HEADLINE :properties (:ID "test-1" :TITLE "Node 1") :contents nil)))
     (clrhash passepartout::*memory-store*)
     (let ((id1 (ingest-ast ast1)))
@@ -367,7 +379,7 @@ Verifies that the Merkle hash is deterministic and consistent across independent
           (is (equal hash1 (memory-object-hash (memory-object-get id2)))))))))
 
 (test merkle-hash-different
-  "Different ASTs should produce different hashes."
+  "Contract 2: distinct ASTs produce different Merkle hashes."
   (clrhash passepartout::*memory-store*)
   (let* ((ast1 '(:type :HEADLINE :properties (:ID "a" :TITLE "Alpha") :contents nil))
          (ast2 '(:type :HEADLINE :properties (:ID "b" :TITLE "Beta") :contents nil))