amos 9d633e9e67 Batch 15 (20261023-C-hwe-scale-15): 320 HWE-derived repair tasks
One user-space repair task per eligible HWE debug-diag / compile-deploy base
ID: 320 admitted (C 218, C++ 97, build scripts 5), 1 skipped by the content
filter. Each ships a public spec with a check-to-basis table, at least two
defects with single-fix fixtures, a symptom-masking fixture and an alternative
correct implementation. Claude re-checked all 320: structure, the HWE quality
items and trace6 Docker calibration receipts against current digests
(320/320 USABLE). Difficulty is unmeasured. Known follow-up: 212 tasks use 120
ad-hoc family names; the next batch maps them to the canonical list.
The batch's 1,256-line progress log stays in its factory report and the
36-local branch batch15-hwe.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 01:55:56 +08:00

6.8 KiB

Resource key cache contract

C01. C++17 API in include/resource.hpp. Cache capacities are 1..8. There are two independent cache instances sharing one Store and Pool. Thread safety is not required. All public operations must compile and terminate normally for the valid input domain below. The API and raw stdout protocol remain unchanged; stderr may contain arbitrary diagnostic bytes.

C02. Keys have exactly two components separated by one slash. Each component has 1..24 ASCII characters from letters, digits, underscore, hyphen and dot. ASCII letters are case insensitive; canonical keys are lowercase. Invalid keys return bad_key without changing cache entries or LRU. get still increments requests. Source put/erase invalid keys leave source unchanged.

C03. Store.put replaces bytes and increments that key's revision, including identical bytes. Erase present increments revision and leaves a tombstone; erase absent returns missing without a revision change. Re-creation increments the retained revision. Source values are binary strings, including empty strings and embedded NUL. Test workloads use at most 4096 bytes per string and 2000 operations, avoiding revision/clock integer overflow.

C04. Cache.get borrows a cache-owned byte range and returns status=ok, length and current source revision. That view may be used only until the next mutating operation on that cache. Store operations do not directly alter existing cache allocations. Every get consults current source presence/revision: absent source removes an old cached entry and returns missing; a changed revision is refreshed; a same-revision hit performs no allocation. Failure views have null data, zero length and zero revision. Do not free a source's borrowed storage.

C05. Cache entries consume one Pool block each, charged bytes.size()+1 for a trailing NUL (the NUL is outside the view). Cache owns these blocks. Same-revision hits become most recently used. Successful cold loads and refreshes become most recently used. A full cache evicts its least recently used entry only after the new allocation succeeds. A refresh allocates before releasing the old block. An allocation failure returns no_memory and preserves entry bytes/revisions/LRU, including an obsolete old entry. Source absence removes its entry without allocating.

C06. Requests counts every get, including calls inside snapshot. A valid-key same-revision get increments hits; all other valid-key gets increment misses, including absent source and allocation failure. Invalid keys increment neither hits nor misses. Refreshes counts only successful changed-revision replacements; evictions counts capacity removals on successful cold loads and resize shrink (C12). Invalidate and clear do not increment counters. clear preserves counters and removes all entries; destructor releases all entries as well. Repeated clear is harmless. New cache starts with zero counters.

C07. Invalidate canonicalizes the key and removes/releases just that entry; returns ok if found, missing otherwise, bad_key for invalid key. It does not touch the source or other caches. Clear/destruction release exactly the owned cache blocks; independent OwnedValue snapshots remain valid. All valid flows have zero bad releases. Pool destructor's safety reclamation does not excuse outstanding cache blocks before Pool destruction.

C08. snapshot calls get, then allocates a separate Pool block containing exactly that view. It replaces/releases the previous OwnedValue only after the copy allocation succeeds. If get or copy allocation fails, the old OwnedValue remains unchanged; a successful get may already have changed cache/LRU/counters. A successful snapshot of an empty string is present and owns a one-byte block. OwnedValue move transfers ownership; reset/destructor release exactly once. Snapshots survive subsequent source/cache changes.

C09. Pool limit is a live-byte allocation budget shared by caches and snapshots. Lowering it does not release existing blocks; allocate fails while existing+requested exceeds it. Failed allocate neither adds a block nor changes live bytes. Block IDs and addresses are unspecified. Inspect only public valid entries, not unused storage.

C10. src/observe.cpp is the public raw observation tool, with one JSON array per nonempty command. It has no assertions or expected values. Initial cache capacities are 3 and 2; snapshots 0..2 are empty. PUT key hex (or - for empty), ERASE key, GET cache key, SNAP cache snapshot key, OWNED snapshot, DROP snapshot, INVALIDATE cache key, CLEAR cache, RESET cache capacity, LIMIT bytes, STATE cache, END are valid commands. Cache indexes are 0..1. END destroys all caches and snapshots and prints Pool [live_blocks,live_bytes,bad_releases] before Pool destruction. RESET destroys one cache, then creates one with zero counters. Observe's formats are defined by its printing code: GET [status,hex,revision]; SNAP [status,[present,hex,revision]]; STATE [sorted_entries,lru_oldest_first,[requests,hits,misses,refreshes,evictions],pool_accounting]. PUT/ERASE print [status,source_revision], INVALIDATE [status]. OWNED prints [present,hex,revision]; CLEAR/RESET/DROP/LIMIT print pool_accounting. Only stdout protocol and normal exit are constrained.

C12. resize accepts capacities 1..8, otherwise returns bad_capacity=4 without change. Successful shrink evicts oldest entries until size fits, incrementing evictions for each removal; growth does not change entries or order. prune removes and releases every entry whose source is absent or has a different revision, preserving relative LRU of survivors and every counter; returns number removed. Neither operation allocates Pool blocks. Public commands RESIZE cache capacity and PRUNE cache print [status] and [removed] respectively. MOVE source_snapshot destination_snapshot invokes OwnedValue move assignment and prints [source_owned,destination_owned]. Self move changes nothing; other moves empty the source and release the previous destination. All preserve ownership independence.

C13. invalidate_namespace takes a single valid key component (same alphabet/length/case rules as C02). It releases/removes every entry in that canonical namespace only, preserving survivor order and all counters, and does not affect source or snapshots. It returns {ok,removed}, including zero if none; invalid namespace returns {bad_key,0} without changes. NAMESPACE cache component prints [status,removed].

C11. Build: make observe. Demonstration: make demo. To exercise source changes and independent copies, feed commands such as PUT cfg/name 61, GET 0 cfg/name, SNAP 0 0 cfg/name, PUT CFG/NAME 6262, GET 0 cfg/name, OWNED 0, CLEAR 0, DROP 0, END to ./observe, one command per line. The full delivery must satisfy every clause above, including arbitrary valid keys, both caches, changing revisions, capacities 1..8, allocation budgets and binary payloads. Only src/cache.cpp is submitted; public support is frozen for grading.