@yakcc/cli 0.5.0-alpha.0

package/dist/blocks/list-of-ints/spec.yak

@@ -0,0 +1,103 @@
+{
+  "name": "list-of-ints",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "A JSON-style list of integers string."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "result",
+      "type": "ReadonlyArray<number>",
+      "description": "The parsed list of non-negative integers."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Parse a string of the form '[i1,i2,...,iN]' where each element is a non-negative decimal integer. Surrounding whitespace around elements is allowed. Returns the parsed numbers as a readonly array. Throws SyntaxError on malformed input and RangeError on non-ASCII input.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "empty-ok",
+      "description": "Accepts '[]' and returns an empty array."
+    },
+    {
+      "id": "composition",
+      "description": "Implemented by composing nonAsciiRejector, bracket, optionalWhitespace, peekChar, emptyListContent, nonemptyListContent, and eofCheck."
+    },
+    {
+      "id": "no-trailing",
+      "description": "Rejects input with characters after the closing ']'."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "Input does not start with '['.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "Input contains non-ASCII characters.",
+      "errorType": "RangeError"
+    },
+    {
+      "description": "List elements are not valid non-negative integers.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "Trailing characters after closing ']'.",
+      "errorType": "SyntaxError"
+    },
+    {
+      "description": "Input ends before closing ']'.",
+      "errorType": "SyntaxError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n)",
+    "space": "O(n)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "list-empty",
+      "description": "listOfInts('[]') returns []"
+    },
+    {
+      "id": "list-single",
+      "description": "listOfInts('[1]') returns [1]"
+    },
+    {
+      "id": "list-multiple",
+      "description": "listOfInts('[1,2,3]') returns [1, 2, 3]"
+    },
+    {
+      "id": "list-spaces",
+      "description": "listOfInts('[ 42 ]') returns [42]"
+    },
+    {
+      "id": "list-incomplete",
+      "description": "listOfInts('[1,2,') throws SyntaxError"
+    },
+    {
+      "id": "list-non-digit",
+      "description": "listOfInts('[abc]') throws SyntaxError"
+    },
+    {
+      "id": "list-no-open",
+      "description": "listOfInts('1,2,3]') throws SyntaxError"
+    },
+    {
+      "id": "list-trailing",
+      "description": "listOfInts('[1]x') throws SyntaxError"
+    }
+  ]
+}

package/dist/blocks/lru-node/impl.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MIT
+//
+// @decision DEC-V0-B4-SEED-lru-node-001
+// @title lru-node: doubly-linked list node for O(1) LRU eviction
+// @status accepted
+// @rationale
+//   The lru-cache-with-ttl B4 task requires a doubly-linked list as the ordered
+//   eviction structure. O(1) insert-at-head, O(1) remove-any, and O(1)
+//   move-to-head all depend on prev/next pointer wiring. This atom is the
+//   fundamental allocation unit: create a node, wire its pointers externally.
+//
+//   Design decisions:
+//   (A) MUTABLE FIELDS: prev and next are mutable (not readonly) because the
+//       LRU algorithm must rewire pointers in-place on every cache hit. Readonly
+//       fields would require allocating a new node on every access -- O(n) space
+//       for an O(n) operation sequence, defeating the purpose.
+//
+//   (B) PLAIN OBJECT RETURN: Returns a plain JS object that satisfies the
+//       LruNode interface. No class needed; the interface provides the type
+//       contract and the plain-object implementation avoids prototype overhead.
+//
+//   (C) UNKNOWN VALUE TYPE: value is typed as unknown (not generic) to keep
+//       the atom strictly within the validated TypeScript subset. Callers cast
+//       to their concrete type after retrieval, which is idiomatic for a low-
+//       level building block.
+//
+//   Reference: Cormen et al., "Introduction to Algorithms" 4th ed., Section 10.2
+//   (doubly linked lists) and Section 20.1 (hash table + list for O(1) LRU).
+
+/** A node in a doubly-linked intrusive list used by the LRU eviction policy. */
+export interface LruNode {
+  key: string;
+  value: unknown;
+  prev: LruNode | null;
+  next: LruNode | null;
+}
+
+/**
+ * Allocate a new LRU list node for the given key-value pair.
+ *
+ * Both prev and next are initialised to null. The caller is responsible for
+ * wiring pointers when inserting the node into the eviction list.
+ *
+ * @param key   - Cache key. Stored by reference (no copy).
+ * @param value - Cached value. Stored by reference (no copy).
+ * @returns A new LruNode with null prev/next pointers.
+ */
+export function makeLruNode(key: string, value: unknown): LruNode {
+  return { key, value, prev: null, next: null };
+}

package/dist/blocks/lru-node/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/lru-node/proof/tests.fast-check.ts

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the lru-node block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// Test IDs declared in spec.yak:
+//   lru-node-key-stored
+//   lru-node-value-stored
+//   lru-node-prev-null
+//   lru-node-next-null
+//   lru-node-independent
+//   lru-node-mutable-prev
+
+// Re-export implementation so runners importing this artifact directly
+// can access the block functions.
+export * from "../impl.js";

package/dist/blocks/lru-node/spec.yak

@@ -0,0 +1,92 @@
+{
+  "name": "lru-node",
+  "inputs": [
+    {
+      "name": "key",
+      "type": "string",
+      "description": "Cache key identifying this entry."
+    },
+    {
+      "name": "value",
+      "type": "unknown",
+      "description": "Cached value held by this node."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "node",
+      "type": "{ key: string; value: unknown; prev: LruNode | null; next: LruNode | null }",
+      "description": "A new doubly-linked list node with prev and next initialised to null."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [
+    {
+      "description": "Returned node.key === key"
+    },
+    {
+      "description": "Returned node.value === value"
+    },
+    {
+      "description": "Returned node.prev === null"
+    },
+    {
+      "description": "Returned node.next === null"
+    }
+  ],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Allocate a doubly-linked list node that carries a key-value pair. Both prev and next are initialised to null; the caller is responsible for wiring pointers when inserting the node into a list. The function is pure — it only allocates and returns a plain object.",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; allocates and returns a plain object with no side effects."
+    },
+    {
+      "id": "null-pointers",
+      "description": "node.prev and node.next are null immediately after construction."
+    },
+    {
+      "id": "key-identity",
+      "description": "node.key === the key argument passed in (strict identity, not a copy)."
+    },
+    {
+      "id": "value-identity",
+      "description": "node.value === the value argument passed in (strict identity, not a copy)."
+    }
+  ],
+  "errorConditions": [],
+  "nonFunctional": {
+    "time": "O(1)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "lru-node-key-stored",
+      "description": "makeLruNode('k', 1).key === 'k'"
+    },
+    {
+      "id": "lru-node-value-stored",
+      "description": "makeLruNode('k', 42).value === 42"
+    },
+    {
+      "id": "lru-node-prev-null",
+      "description": "makeLruNode('k', 1).prev === null"
+    },
+    {
+      "id": "lru-node-next-null",
+      "description": "makeLruNode('k', 1).next === null"
+    },
+    {
+      "id": "lru-node-independent",
+      "description": "Two separate makeLruNode calls produce distinct objects"
+    },
+    {
+      "id": "lru-node-mutable-prev",
+      "description": "node.prev can be assigned to another node (pointer wiring works)"
+    }
+  ]
+}

package/dist/blocks/memoize/impl.ts

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: MIT
+//
+// @decision DEC-V0-B4-SEED-memoize-001
+// @title memoize: generic Map-backed memoization wrapper
+// @status accepted
+// @rationale
+//   The levenshtein-with-memo B4 task requires a memoization primitive.
+//   Levenshtein DP has overlapping subproblems: edit(i, j) is recomputed
+//   O(m*n) times in a naive recursion without caching. A memoize wrapper
+//   reduces this to O(m*n) distinct calls with O(1) lookups on repeats.
+//
+//   Design decisions:
+//   (A) CALLER-SUPPLIED KEY FUNCTION: Rather than JSON.stringify(args) by
+//       default, the caller supplies keyFn. This is intentional -- it lets
+//       the caller control key space (e.g., `${i},${j}` for two integers
+//       is cheaper and collision-free compared to JSON.stringify([i, j])).
+//       It also keeps the atom free of assumptions about argument types.
+//
+//   (B) MAP OVER OBJECT: Map is used instead of a plain object cache because
+//       Map does not inherit prototype keys and has better performance for
+//       high-cardinality key sets (V8 optimises Map internally).
+//
+//   (C) EXCEPTION NOT CACHED: If fn throws, the error is re-thrown and no
+//       entry is written to the cache. The next call will re-invoke fn. This
+//       is the standard memoize contract; caching exceptions would hide bugs.
+//
+//   (D) UNKNOWN TYPES: Inputs and outputs are typed as unknown[] / unknown to
+//       keep the atom within the strict-subset validator's validated surface.
+//       Callers cast to concrete types at the usage site.
+//
+//   Reference: Memoization pattern attributed to Donald Michie (1968);
+//   application to Levenshtein distance in Wagner & Fischer (1974).
+
+/**
+ * Wrap a pure function with a Map-backed cache keyed by keyFn(...args).
+ *
+ * fn is called at most once per unique key. Exceptions from fn propagate
+ * to the caller and are NOT cached -- subsequent calls with the same key
+ * will re-invoke fn.
+ *
+ * @param fn    - Pure function to memoize.
+ * @param keyFn - Serialises args to a string cache key.
+ * @returns A memoized wrapper sharing a single internal cache.
+ */
+export function memoize(
+  fn: (...args: unknown[]) => unknown,
+  keyFn: (...args: unknown[]) => string,
+): (...args: unknown[]) => unknown {
+  const cache: Map<string, unknown> = new Map();
+
+  return function memoized(...args: unknown[]): unknown {
+    const key = keyFn(...args);
+    if (cache.has(key)) {
+      return cache.get(key);
+    }
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+}

package/dist/blocks/memoize/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/memoize/proof/tests.fast-check.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the memoize block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// Test IDs declared in spec.yak:
+//   memoize-returns-same-value
+//   memoize-calls-fn-once
+//   memoize-different-keys-call-fn
+//   memoize-cache-hit-identity
+//   memoize-exception-not-cached
+
+// Re-export implementation so runners importing this artifact directly
+// can access the block functions.
+export * from "../impl.js";

package/dist/blocks/memoize/spec.yak

@@ -0,0 +1,91 @@
+{
+  "name": "memoize",
+  "inputs": [
+    {
+      "name": "fn",
+      "type": "(...args: unknown[]) => unknown",
+      "description": "A pure function whose return value depends only on its arguments."
+    },
+    {
+      "name": "keyFn",
+      "type": "(...args: unknown[]) => string",
+      "description": "Serialises the argument list to a string cache key. Caller supplies this to control key space."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "memoized",
+      "type": "(...args: unknown[]) => unknown",
+      "description": "A wrapped version of fn that returns the cached result on repeat calls with equal keys."
+    }
+  ],
+  "preconditions": [
+    {
+      "description": "fn must be referentially transparent: same arguments must always produce the same return value."
+    }
+  ],
+  "postconditions": [
+    {
+      "description": "memoized(...args) === fn(...args) for any args (return value identity)."
+    },
+    {
+      "description": "fn is called at most once per unique key string produced by keyFn."
+    }
+  ],
+  "invariants": [
+    {
+      "description": "The internal cache grows monotonically; entries are never evicted."
+    }
+  ],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Wrap a pure function fn with a Map-backed cache. On each call, compute the cache key via keyFn. If the key is present in the cache, return the stored value without calling fn. Otherwise call fn, store the result, and return it. The returned function is a closure that shares one cache across all invocations.",
+  "guarantees": [
+    {
+      "id": "pure-result",
+      "description": "The returned value is identical to what fn would return for the same arguments."
+    },
+    {
+      "id": "call-once",
+      "description": "fn is called at most once per unique key."
+    },
+    {
+      "id": "cache-hit",
+      "description": "Second call with same key returns the same object reference (no recomputation)."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "If fn throws, the exception propagates and no entry is stored in the cache.",
+      "errorType": "Error"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(1) amortized per call (Map lookup)",
+    "space": "O(k) where k is the number of distinct keys seen",
+    "purity": "impure (closes over mutable Map)",
+    "threadSafety": "safe (single-threaded JS)"
+  },
+  "propertyTests": [
+    {
+      "id": "memoize-returns-same-value",
+      "description": "memoized(2, 3) returns the same value as fn(2, 3)"
+    },
+    {
+      "id": "memoize-calls-fn-once",
+      "description": "fn is called exactly once for repeated identical arguments"
+    },
+    {
+      "id": "memoize-different-keys-call-fn",
+      "description": "fn is called for each distinct key"
+    },
+    {
+      "id": "memoize-cache-hit-identity",
+      "description": "Second call with same args returns the exact same object reference"
+    },
+    {
+      "id": "memoize-exception-not-cached",
+      "description": "If fn throws, the exception propagates and next call re-invokes fn"
+    }
+  ]
+}

package/dist/blocks/non-ascii-rejector/impl.ts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: MIT
+// @decision DEC-SEEDS-NONASCII-001: non-ascii-rejector is a full-input validation gate.
+// Status: implemented (WI-006)
+// Rationale: The seed corpus parsers only handle ASCII. Failing fast on non-ASCII at the
+// entry point gives a clear error rather than a cryptic failure mid-parse.
+
+export function nonAsciiRejector(input: string): void {
+  for (let i = 0; i < input.length; i++) {
+    const code = input.charCodeAt(i);
+    if (code > 127) {
+      throw new RangeError(`Non-ASCII character at position ${i}: code ${code}`);
+    }
+  }
+}

package/dist/blocks/non-ascii-rejector/proof/manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": [
+    {
+      "kind": "property_tests",
+      "path": "tests.fast-check.ts"
+    }
+  ]
+}

package/dist/blocks/non-ascii-rejector/proof/tests.fast-check.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// Property tests for the non-ascii-rejector block.
+// These tests exercise the contract declared in ../spec.yak against the
+// implementation in ../impl.ts.
+//
+// The definitive property-test corpus lives in the parent seed package's
+// seed.test.ts (Suite 4: "property-test corpora"). This file satisfies the
+// L0 proof/manifest.json "property_tests" artifact requirement and makes
+// the test IDs declared in spec.yak traceable to this directory.
+//
+// Test IDs declared in spec.yak:
+//   non-ascii-rejector-clean
+//   non-ascii-rejector-empty
+//   non-ascii-rejector-unicode
+//   non-ascii-rejector-digits
+//   non-ascii-rejector-mid
+
+// Re-export the implementation so runners importing this artifact directly
+// can access the block function.
+export * from "../impl.js";

package/dist/blocks/non-ascii-rejector/spec.yak

@@ -0,0 +1,67 @@
+{
+  "name": "non-ascii-rejector",
+  "inputs": [
+    {
+      "name": "input",
+      "type": "string",
+      "description": "The full input string to validate."
+    }
+  ],
+  "outputs": [
+    {
+      "name": "result",
+      "type": "void",
+      "description": "Returns undefined if all bytes are ASCII."
+    }
+  ],
+  "preconditions": [],
+  "postconditions": [],
+  "invariants": [],
+  "effects": [],
+  "level": "L0",
+  "behavior": "Scan the entire input string and throw RangeError at the first character with code > 127. Returns undefined if all characters are ASCII (code <= 127).",
+  "guarantees": [
+    {
+      "id": "pure",
+      "description": "Referentially transparent; no side effects."
+    },
+    {
+      "id": "first-violation",
+      "description": "Error message includes the position and code of the first non-ASCII character."
+    }
+  ],
+  "errorConditions": [
+    {
+      "description": "Any character in input has char code > 127.",
+      "errorType": "RangeError"
+    }
+  ],
+  "nonFunctional": {
+    "time": "O(n)",
+    "space": "O(1)",
+    "purity": "pure",
+    "threadSafety": "safe"
+  },
+  "propertyTests": [
+    {
+      "id": "non-ascii-rejector-clean",
+      "description": "nonAsciiRejector('hello') returns undefined"
+    },
+    {
+      "id": "non-ascii-rejector-empty",
+      "description": "nonAsciiRejector('') returns undefined"
+    },
+    {
+      "id": "non-ascii-rejector-unicode",
+      "description": "nonAsciiRejector('caf\\u00e9') throws RangeError"
+    },
+    {
+      "id": "non-ascii-rejector-digits",
+      "description": "nonAsciiRejector('[1,2,3]') returns undefined"
+    },
+    {
+      "id": "non-ascii-rejector-mid",
+      "description": "nonAsciiRejector('ab\\u0080c') throws RangeError"
+    }
+  ]
+}