t27f: frame_shard.t27 -- a generic frame partition for reel renders; token_floor uses it (Closes #10385)

.trinity/seals/t27f_frame_shard.json

@@ -0,0 +1,28 @@
+{
+  "built_by": "t27c-bootstrap@0.5.2+9448ab4be",
+  "closure": [],
+  "config": "gen=c,rust,verilog,zig;tests=zig",
+  "gen_hash_c": "sha256:cc399837fb34f4c10c54c90e26eaa6ccd9dfd11d29da56667addc8cb88bc1a18",
+  "gen_hash_rust": "sha256:e833a49af5b10636afb6b00a19abbea4802eca5b283f30bf19573498d9aae653",
+  "gen_hash_verilog": "sha256:9e98a30d7cd30430c01e7b27ffcad468d197af832d41af3969dbfa0f71b6a7d1",
+  "gen_hash_zig": "sha256:a0ad9a3ac459844ec8e22fad442e970712c10dd892c36fb40f3bef1620d547dc",
+  "module": "frame_shard",
+  "ring": 12,
+  "seal_schema": 2,
+  "sealed_at": "2026-10-18T10:43:57Z",
+  "sealed_by": "t27c-bootstrap@0.5.2",
+  "spec_hash": "sha256:1f04638a243b7a7f4d7a4480faf85f7878ca2e3365a2ec0f001a991fbd353da6",
+  "spec_path": "specs/t27f/frame_shard.t27",
+  "tests": {
+    "failed": 0,
+    "failing": [],
+    "forced": false,
+    "passed": 5,
+    "total": 5,
+    "vacuous": 0
+  },
+  "toolchain": {
+    "test_runner": "sha256:1982ae948e24d00c5d221ccec12dfce1eb01204b53e37b0f857f93b16d64629d",
+    "zig": "0.16.0"
+  }
+}

.trinity/seals/t27f_token_floor.json

@@ -1,10 +1,14 @@
 {
-  "built_by": "t27c-bootstrap@0.5.2+9448ab4be",
+  "built_by": "t27c-bootstrap@0.5.2+5e4d3b998",
   "closure": [
     {
       "spec": "specs/physics/physical_limits.t27",
       "spec_hash": "sha256:adb7092831e266f0e4bed92f74e7795c78c1bdb1051b5cd9a0c1be94b5e5b19a"
     },
+    {
+      "spec": "specs/t27f/frame_shard.t27",
+      "spec_hash": "sha256:1f04638a243b7a7f4d7a4480faf85f7878ca2e3365a2ec0f001a991fbd353da6"
+    },
     {
       "spec": "specs/t27f/outfit_atlas.t27",
       "spec_hash": "sha256:6fb47290e7fae3d22258b5a8dfe1282fd58b96790ecb357a9513683c4035cac6"
@@ -27,23 +31,23 @@
     }
   ],
   "config": "gen=c,rust,verilog,zig;tests=zig",
-  "gen_hash_c": "sha256:0f358d8ff0757768f04d35ecbecd679b091c43d6d268fa8c28366fa31a3f9167",
-  "gen_hash_rust": "sha256:d263a762901fc286cc2d2d20c8f6445f93561933d8bdd043ba079dfcd2e686aa",
-  "gen_hash_verilog": "sha256:b495c59195d25d5eb3addaaf9da41cf69117a4d2c6fcf4e9320d95cbc3df0314",
-  "gen_hash_zig": "sha256:4c978f26d1d0a358bde62e9ef6221ec01a06d02aca24c36ada41b3c12d4b85f4",
+  "gen_hash_c": "sha256:3206763fb219dd142baa945c3504da04d778bea33058bf72fd1b714320b8d309",
+  "gen_hash_rust": "sha256:2eb10bb19e8ccb8675e39b5344d78f5361e5f89057780dd57583a5b1e6b0a525",
+  "gen_hash_verilog": "sha256:f1c9e7aa57719f89baccdeb47d6b92d09ee8895ab63f8e8d2fa74f7b5009a895",
+  "gen_hash_zig": "sha256:c34169797b0d63a8f2c4156edfadf3ce40a0aaf73e77788a478d25fcaac1ece0",
   "module": "token_floor",
   "ring": 12,
   "seal_schema": 2,
-  "sealed_at": "2026-10-18T13:21:32Z",
+  "sealed_at": "2026-10-18T15:05:50Z",
   "sealed_by": "t27c-bootstrap@0.5.2",
-  "spec_hash": "sha256:82524e666fafe6098d85d86cfd93932e1e488f318e28ba0eff93c54cb656f8e8",
+  "spec_hash": "sha256:1d33dca783f83effabb8208a6bbdf311840fbbe6e23081713b009954605807e3",
   "spec_path": "specs/t27f/token_floor.t27",
   "tests": {
     "failed": 0,
     "failing": [],
     "forced": false,
-    "passed": 35,
-    "total": 35,
+    "passed": 32,
+    "total": 32,
     "vacuous": 0
   },
   "toolchain": {

.trinity/seals/t27f_token_floor_mux.json

@@ -1,5 +1,5 @@
 {
-  "built_by": "t27c-bootstrap@0.5.2+9448ab4be",
+  "built_by": "t27c-bootstrap@0.5.2+5e4d3b998",
   "closure": [
     {
       "spec": "specs/automation/owner_voice_reel.t27",
@@ -19,7 +19,7 @@
     },
     {
       "spec": "specs/t27f/token_floor.t27",
-      "spec_hash": "sha256:82524e666fafe6098d85d86cfd93932e1e488f318e28ba0eff93c54cb656f8e8"
+      "spec_hash": "sha256:1d33dca783f83effabb8208a6bbdf311840fbbe6e23081713b009954605807e3"
     },
     {
       "spec": "specs/t27f/token_floor_scenes.t27",
@@ -34,7 +34,7 @@
   "module": "token_floor_mux",
   "ring": 12,
   "seal_schema": 2,
-  "sealed_at": "2026-10-18T15:14:29Z",
+  "sealed_at": "2026-10-18T15:24:22Z",
   "sealed_by": "t27c-bootstrap@0.5.2",
   "spec_hash": "sha256:55c02c60e581640d2f3d6db3d9ba2cdfb21d74b172290b386023e8f264e59a04",
   "spec_path": "specs/t27f/token_floor_mux.t27",

docs/reports/t27b_expectations.json

@@ -12,7 +12,7 @@
   "reference-bug": "the reference passes it for the wrong reason; t27b is right not to",
   "n/a": "outside what t27b is for (say why in the PR that sets it)"
  },
- "max_not_pass": 132,
+ "max_not_pass": 134,
  "entries": [
   {"path": "specs/a/b_c.t27", "t27b": "pass"},
   {"path": "specs/a_b/c.t27", "t27b": "pass"},
@@ -188,6 +188,8 @@
   {"path": "specs/claw/gates.t27", "t27b": "pass"},
   {"path": "specs/claw/gates_pins.t27", "t27b": "pass"},
   {"path": "specs/claw/github_surface.t27", "t27b": "pass"},
+  {"path": "specs/claw/ledger_union.t27", "t27b": "pass"},
+  {"path": "specs/claw/model_route.t27", "t27b": "pass"},
   {"path": "specs/claw/preview.t27", "t27b": "pass"},
   {"path": "specs/claw/recipes.t27", "t27b": "pass"},
   {"path": "specs/claw/refresh.t27", "t27b": "pass"},
@@ -1436,7 +1438,9 @@
   {"path": "specs/t27f/build.t27", "t27b": "pass"},
   {"path": "specs/t27f/deck.t27", "t27b": "pass"},
   {"path": "specs/t27f/frame_cache.t27", "t27b": "pass"},
+  {"path": "specs/t27f/frame_shard.t27", "t27b": "blocked", "blocker": "type [N]T", "reason": "unimplemented"},
   {"path": "specs/t27f/hot.t27", "t27b": "pass"},
+  {"path": "specs/t27f/lesson_reel.t27", "t27b": "blocked", "blocker": "type [N]T", "reason": "unimplemented"},
   {"path": "specs/t27f/outfit_atlas.t27", "t27b": "pass"},
   {"path": "specs/t27f/particle_engine.t27", "t27b": "blocked", "blocker": "ExprCall(@sin)", "reason": "unimplemented"},
   {"path": "specs/t27f/particle_field.t27", "t27b": "pass"},
@@ -1448,6 +1452,7 @@
   {"path": "specs/t27f/reel_particles.t27", "t27b": "blocked", "blocker": "ExprCall(@sin)", "reason": "unimplemented"},
   {"path": "specs/t27f/reel_particles_mux.t27", "t27b": "pass"},
   {"path": "specs/t27f/reel_t27_basics.t27", "t27b": "pass"},
+  {"path": "specs/t27f/reel_topics.t27", "t27b": "pass"},
   {"path": "specs/t27f/spec_graph.t27", "t27b": "pass"},
   {"path": "specs/t27f/spec_graph_derive.t27", "t27b": "pass"},
   {"path": "specs/t27f/spec_graph_export.t27", "t27b": "pass"},
@@ -1465,6 +1470,7 @@
   {"path": "specs/t27mcp/examples.t27", "t27b": "pass"},
   {"path": "specs/t27mcp/find.t27", "t27b": "pass"},
   {"path": "specs/t27mcp/seal_verdict.t27", "t27b": "pass"},
+  {"path": "specs/t27mcp/service.t27", "t27b": "pass"},
   {"path": "specs/t27mcp/spec_brief.t27", "t27b": "pass"},
   {"path": "specs/t27mcp/telegram.t27", "t27b": "pass"},
   {"path": "specs/t27mcp/tool_schema.t27", "t27b": "codegen", "blocker": "t27b: unsupported construct FnDecl(frame or branch range) at line 0 (fn the round trip fixtures: a tuple, arrays, a boolean, nested objects: conditional branch out of range (function too large))", "reason": "unimplemented"},

specs/t27f/frame_shard.t27

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+; specs/t27f/frame_shard.t27 -- which frames of a reel one process renders, so N processes render
+; it in parallel and their outputs, concatenated, are the one-process output byte for byte.
+; --
+; Why: specs/t27f/token_floor.t27 renders 450 frames in 52 s on one of the lab's 48 cores. Shard k
+; of N renders the frames [shard_a(k, N, F), shard_b(k, N, F)) of a reel of F frames, and the shards
+; of one N tile [0, F) in order. 48 shards render token_floor in 3.43 s, same frames sha256.
+; --
+; The contract for a renderer whose frame f is the integral of its physics from frame 0 (most are):
+; step the physics from frame 0 up to the shard's last frame, and skip only the drawing of the
+; frames before its first one. A renderer opts in with three lines in its main:
+;   const fa = env_first(FRAMES);
+;   const fb = env_end(FRAMES);
+;   while (frame < fb) { ...physics...; if (frame < fa) { frame = frame + 1; continue; } ...draw... }
+; --
+; The shard is read from the environment: TF_SHARD (k) and TF_SHARDS (N). Unset, or a k or N that
+; names no shard, renders the whole reel, never an empty or a partial one. Only main may call
+; env_first and env_end: they reach getenv, so the binary links libc (`-lc`) and the tests, which
+; never link libc, do not reach them.
+; --
+; The frames themselves are cached by specs/t27f/frame_cache.t27, keyed by the renderer's seal.
+
+module frame_shard;
+
+; The first frame of shard k of n, for 0 <= k <= n; shard_a(n, n, frames) is frames. Shard k renders
+; [shard_a(k, n, frames), shard_a(k + 1, n, frames)), so shard k + 1 starts where shard k stops.
+pub fn shard_a(k: i32, n: i32, frames: i32) -> i32 {
+    return @divTrunc(k * frames, n);
+}
+
+pub fn shard_b(k: i32, n: i32, frames: i32) -> i32 {
+    return shard_a(k + 1, n, frames);
+}
+
+; The decimal number at the head of s, or dflt when s has no digit first. At most four digits are
+; read, so no input overflows.
+pub fn count_or(s: [*:0]const u8, dflt: i32) -> i32 {
+    var v : i32 = 0;
+    var i : usize = 0;
+    while (i < 4 && s[i] >= 48 && s[i] <= 57) {
+        v = v * 10 + @as(i32, @intCast(s[i] - 48));
+        i = i + 1;
+    }
+    if (i == 0) {
+        return dflt;
+    }
+    return v;
+}
+
+; The shard a renderer draws, from k and n as read: an n out of 1..frames, or a k out of 0..n - 1,
+; is the whole reel.
+pub fn shard_n(k: i32, n: i32, frames: i32) -> i32 {
+    if (n < 1 || n > frames || k < 0 || k >= n) {
+        return 1;
+    }
+    return n;
+}
+
+pub fn shard_k(k: i32, n: i32, frames: i32) -> i32 {
+    if (shard_n(k, n, frames) == 1) {
+        return 0;
+    }
+    return k;
+}
+
+; The first and the end frame of the shard (k, n) as read, checked.
+pub fn first_of(k: i32, n: i32, frames: i32) -> i32 {
+    return shard_a(shard_k(k, n, frames), shard_n(k, n, frames), frames);
+}
+
+pub fn end_of(k: i32, n: i32, frames: i32) -> i32 {
+    return shard_b(shard_k(k, n, frames), shard_n(k, n, frames), frames);
+}
+
+; The environment variable `name` as a count; dflt when it is unset. main only (getenv, libc).
+pub fn env_count(name: [*:0]const u8, dflt: i32) -> i32 {
+    const p = std.c.getenv(name);
+    if (p == null) {
+        return dflt;
+    }
+    return count_or(p.?, dflt);
+}
+
+pub fn env_first(frames: i32) -> i32 {
+    return first_of(env_count("TF_SHARD", 0), env_count("TF_SHARDS", 1), frames);
+}
+
+pub fn env_end(frames: i32) -> i32 {
+    return end_of(env_count("TF_SHARD", 0), env_count("TF_SHARDS", 1), frames);
+}
+
+test "the shards of every n from 1 to 64 tile a 450-frame reel in order, with no gap and no overlap" {
+    var n : i32 = 1;
+    while (n <= 64) {
+        assert(shard_a(0, n, 450) == 0);
+        assert(shard_b(n - 1, n, 450) == 450);
+        var total : i32 = 0;
+        var k : i32 = 0;
+        while (k < n) {
+            assert(shard_b(k, n, 450) > shard_a(k, n, 450));
+            if (k > 0) {
+                assert(shard_a(k, n, 450) == shard_b(k - 1, n, 450));
+            }
+            total = total + shard_b(k, n, 450) - shard_a(k, n, 450);
+            k = k + 1;
+        }
+        assert(total == 450);
+        n = n + 1;
+    }
+}
+
+test "48 shards of 450 frames are 9 or 10 frames each, and 450 shards are one frame each" {
+    assert(shard_b(0, 48, 450) - shard_a(0, 48, 450) == 9);
+    assert(shard_b(47, 48, 450) - shard_a(47, 48, 450) == 10);
+    var k : i32 = 0;
+    while (k < 450) {
+        assert(shard_a(k, 450, 450) == k);
+        assert(shard_b(k, 450, 450) == k + 1);
+        k = k + 1;
+    }
+}
+
+test "the tiling holds for reel lengths that n does not divide" {
+    assert(shard_a(1, 7, 100) == 14);
+    assert(shard_b(6, 7, 100) == 100);
+    assert(shard_a(2, 3, 10) == 6);
+    assert(shard_b(2, 3, 10) - shard_a(2, 3, 10) == 4);
+    assert(shard_n(0, 11, 10) == 1);
+    assert(shard_n(9, 10, 10) == 10);
+}
+
+test "a count is read from its leading digits, and anything else falls back" {
+    assert(count_or("", 7) == 7);
+    assert(count_or("x3", 7) == 7);
+    assert(count_or("12", 7) == 12);
+    assert(count_or("48\n", 7) == 48);
+    assert(count_or("0", 7) == 0);
+    assert(count_or("123456", 7) == 1234);
+}
+
+test "a shard that cannot be rendered as asked renders the whole reel" {
+    assert(shard_n(0, 1, 450) == 1);
+    assert(shard_n(48, 48, 450) == 1);
+    assert(shard_n(0, 0, 450) == 1);
+    assert(shard_n(0 - 1, 4, 450) == 1);
+    assert(shard_n(0, 451, 450) == 1);
+    assert(shard_k(48, 48, 450) == 0);
+    assert(shard_n(3, 48, 450) == 48);
+    assert(shard_k(3, 48, 450) == 3);
+    assert(first_of(9, 4, 450) == 0);
+    assert(end_of(9, 4, 450) == 450);
+    assert(first_of(3, 48, 450) == 28);
+    assert(end_of(3, 48, 450) == 37);
+}