|
| 1 | +// @ts-check |
| 2 | +/** |
| 3 | + * content.js — RAID Sandbox: the content algebra (specs/planned/degenerate-levels.md §6). |
| 4 | + * |
| 5 | + * TESTS ONLY. The game never loads this file (no script tag in index.html): |
| 6 | + * the declared `collapsesTo` rules run at runtime, and this is the independent |
| 7 | + * derivation that checks them (§7: "the test is the computation done in advance"). |
| 8 | + * |
| 9 | + * layout.js gives every cell a ROLE (data / P / Q / mirror) and a segment. This |
| 10 | + * file gives every cell its symbolic CONTENT — a vector over the data segments |
| 11 | + * of its stripe: |
| 12 | + * |
| 13 | + * data, segment 3 → {3: 1} |
| 14 | + * P of a stripe holding 0, 1, 2 → {0: 1, 1: 1, 2: 1} the XOR |
| 15 | + * Q of the same stripe → {0: g⁰, 1: g¹, 2: g²} |
| 16 | + * P of a stripe holding 0 alone → {0: 1} it IS D0 |
| 17 | + * Q of the same → {0: g⁰} = {0: 1} it IS D0 |
| 18 | + * a mirror cell of segment 3 → {3: 1} |
| 19 | + * |
| 20 | + * No Galois-field arithmetic: only that g⁰ = 1, that gⁱ ≠ gʲ for i ≠ j, and that a |
| 21 | + * combination of two or more terms is never a single block. From the contents: |
| 22 | + * |
| 23 | + * - two cells on different disks with the same content are COPIES — by content, |
| 24 | + * not by position, so `far` is a mirror exactly like `near`; |
| 25 | + * - the number of copies per segment and the cells with two or more terms (real |
| 26 | + * parity) describe the array's behaviour with no names at all. |
| 27 | + * |
| 28 | + * `behaviour(node)` turns that description into the shape it amounts to — the |
| 29 | + * same {segmentation, redundancy} vocabulary the level files use — so the oracle |
| 30 | + * (collapses-oracle.test.js) can hold the declared rules to it in both directions. |
| 31 | + * |
| 32 | + * Its limit, kept explicit (§6): equivalence of content is not identity. The |
| 33 | + * algebra proves "the data lands identically"; what a real system does with that |
| 34 | + * is the `source:` on the declared rule, not this file's business. |
| 35 | + * |
| 36 | + * The core (contents, equality, copy counting) knows nothing about RAID. The |
| 37 | + * RAID-specific part — how a role derives its content — is `contentOf`, and it |
| 38 | + * sits next to layout.js for the same reason layout.js is ADR-002's declared |
| 39 | + * exception: the golden tables bind both to the kernel. |
| 40 | + */ |
| 41 | + |
| 42 | +(function (/** @type {any} */ root) { // the UMD host: window, or Node's global |
| 43 | + 'use strict'; |
| 44 | + |
| 45 | + const Layout = (typeof require !== 'undefined') ? require('./layout.js') : root.RaidLayout; |
| 46 | + |
| 47 | + // --------------------------------------------------------------------------- |
| 48 | + // CONTENTS — one symbolic vector per cell |
| 49 | + // --------------------------------------------------------------------------- |
| 50 | + |
| 51 | + /** A term's coefficient: 1, or gⁱ for i ≥ 1 (g⁰ is written 1 — that is the whole point). */ |
| 52 | + const coef = (i) => (i === 0 ? '1' : `g^${i}`); |
| 53 | + |
| 54 | + /** |
| 55 | + * The content of every cell of a placement, row by row: a Map segment → coefficient, |
| 56 | + * or null for a cell that holds nothing (parity over an empty stripe). |
| 57 | + * @param {Placement} placement |
| 58 | + * @returns {(Map<number, string> | null)[][]} |
| 59 | + */ |
| 60 | + function contents(placement) { |
| 61 | + if (!('stripes' in placement)) return []; |
| 62 | + return placement.stripes.map((row) => { |
| 63 | + // The data segments of THIS stripe, in segment order — what P sums and Q weights. |
| 64 | + const segs = row.filter((c) => c.role === 'data' && c.seg !== null) |
| 65 | + .map((c) => /** @type {number} */ (c.seg)).sort((a, b) => a - b); |
| 66 | + return row.map((cell) => { |
| 67 | + if (cell.role === 'data' || cell.role === 'mirror') |
| 68 | + return cell.seg === null ? null : new Map([[cell.seg, '1']]); |
| 69 | + if (segs.length === 0) return null; // parity of nothing |
| 70 | + const m = new Map(); |
| 71 | + segs.forEach((s, i) => m.set(s, cell.role === 'Q' ? coef(i) : '1')); |
| 72 | + return m; |
| 73 | + }); |
| 74 | + }); |
| 75 | + } |
| 76 | + |
| 77 | + /** Canonical string of a content, so equal contents compare equal. */ |
| 78 | + const key = (content) => |
| 79 | + [...content.entries()].sort((a, b) => a[0] - b[0]).map(([s, c]) => `${s}:${c}`).join(','); |
| 80 | + |
| 81 | + const isSingleBlock = (content) => content.size === 1 && [...content.values()][0] === '1'; |
| 82 | + |
| 83 | + // --------------------------------------------------------------------------- |
| 84 | + // BEHAVIOUR — what the contents say the array does, with no names |
| 85 | + // --------------------------------------------------------------------------- |
| 86 | + |
| 87 | + /** |
| 88 | + * @param {ArrayNode} node a LEAF array (members are disks); nested nodes are |
| 89 | + * out of scope — their collapse composes structurally (§3) |
| 90 | + * @param {{ stripes?: number, chunks?: number }} [opts] |
| 91 | + * @returns {{ disks: number, segments: number, copies: { min: number, max: number }, |
| 92 | + * parityPerStripe: number, rows: number, |
| 93 | + * shape: { segmentation: Segmentation, redundancy: Redundancy } | null, |
| 94 | + * note: string | null }} |
| 95 | + */ |
| 96 | + function behaviour(node, opts = {}) { |
| 97 | + const placement = Layout.computePlacement(node, opts); |
| 98 | + const n = node.members.length; |
| 99 | + if (!('stripes' in placement)) |
| 100 | + return { disks: n, segments: 0, copies: { min: 0, max: 0 }, parityPerStripe: 0, rows: 0, |
| 101 | + shape: null, note: placement.reason }; |
| 102 | + |
| 103 | + const grid = contents(placement); |
| 104 | + |
| 105 | + // copies(s): the DISTINCT disks holding a cell whose content is exactly {s: 1}. |
| 106 | + /** @type {Map<number, Set<number>>} */ |
| 107 | + const holders = new Map(); |
| 108 | + let parityPerStripe = 0; |
| 109 | + grid.forEach((row) => { |
| 110 | + let parityHere = 0; |
| 111 | + row.forEach((content, disk) => { |
| 112 | + if (!content) return; |
| 113 | + if (isSingleBlock(content)) { |
| 114 | + const s = [...content.keys()][0]; |
| 115 | + if (!holders.has(s)) holders.set(s, new Set()); |
| 116 | + holders.get(s).add(disk); |
| 117 | + } else { |
| 118 | + parityHere++; |
| 119 | + } |
| 120 | + }); |
| 121 | + parityPerStripe = Math.max(parityPerStripe, parityHere); |
| 122 | + }); |
| 123 | + |
| 124 | + const segments = holders.size; |
| 125 | + if (segments === 0) |
| 126 | + return { disks: n, segments, copies: { min: 0, max: 0 }, parityPerStripe, rows: grid.length, |
| 127 | + shape: null, note: 'holds no data — every cell is parity over an empty stripe' }; |
| 128 | + |
| 129 | + const counts = [...holders.values()].map((set) => set.size); |
| 130 | + const copies = { min: Math.min(...counts), max: Math.max(...counts) }; |
| 131 | + |
| 132 | + /** @type {{ segmentation: Segmentation, redundancy: Redundancy } | null} */ |
| 133 | + let shape = null; |
| 134 | + let note = null; |
| 135 | + if (parityPerStripe >= 3) { |
| 136 | + note = 'three or more parity terms per stripe — no shape in the two-axis model'; |
| 137 | + } else if (parityPerStripe > 0) { |
| 138 | + shape = { segmentation: 'striped', redundancy: parityPerStripe === 1 ? 'parity1' : 'parity2' }; |
| 139 | + } else if (copies.min >= 2) { |
| 140 | + // Every disk holds every segment → a plain mirror, whatever the drawn rows say |
| 141 | + // (far puts the copies in other rows; by content it is a mirror all the same). |
| 142 | + shape = copies.min === n |
| 143 | + ? { segmentation: 'linear', redundancy: 'mirror' } |
| 144 | + : { segmentation: 'striped', redundancy: 'mirror' }; |
| 145 | + } else { |
| 146 | + // No redundancy at all. Striped vs linear is the one distinction the contents |
| 147 | + // cannot make (a segment is a segment); it is read off the placement's rows — |
| 148 | + // a concatenation is drawn as a single row, one segment per disk. |
| 149 | + shape = grid.length > 1 || n === 1 |
| 150 | + ? { segmentation: 'striped', redundancy: 'none' } |
| 151 | + : { segmentation: 'linear', redundancy: 'none' }; |
| 152 | + } |
| 153 | + return { disks: n, segments, copies, parityPerStripe, rows: grid.length, shape, note }; |
| 154 | + } |
| 155 | + |
| 156 | + // --------------------------------------------------------------------------- |
| 157 | + // EXPORT |
| 158 | + // --------------------------------------------------------------------------- |
| 159 | + |
| 160 | + const RaidContent = { contents, behaviour, key, isSingleBlock }; |
| 161 | + |
| 162 | + if (typeof module !== 'undefined' && module.exports) module.exports = RaidContent; |
| 163 | + else root.RaidContent = RaidContent; |
| 164 | + |
| 165 | +})(typeof globalThis !== 'undefined' ? globalThis : this); |
0 commit comments