@particle-academy/fancy-conformance 0.6.0 → 0.9.1

package/suites/dark-slide/table-cell-model/manifest.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "dark-slide/table-cell-model",
+  "title": "How a loose agent-authored table element resolves into per-cell decisions",
+  "since": "0.7.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "summary": "DarkSlide's three engines (PHP, Node, Python) turn one JSON table element into a pptx table. Between the two sits a pure resolver that decides, per CELL, every value the writer then serialises: fill, text colour and weight, alignment, vertical anchor, font size, letter spacing, capitalisation, the four insets, the four borders, and the two span directions. This suite pins that RESOLVER, not the XML. It exists because per-cell control was unreachable from the model in every engine — a:tcPr carried a fill and nothing else, header fill and zebra were hardcoded constants, and a declared column width was thrown away and replaced with an equal split. The resolver is where a port silently diverges, because two engines can emit well-formed XML from different decisions and no byte comparison of DIFFERENT inputs will notice.",
+    "functions": {
+      "resolvedCell": "resolvedCell(element, theme, row, col) -> the fully-resolved cell at that grid position. `row` counts the HEADER as row 0 when the table has one, so it addresses the emitted grid rather than the input's `rows` array.",
+      "gridWidthsEmu": "gridWidthsEmu(element, totalEmu) -> the <a:gridCol w> values, in order, as strings."
+    },
+    "runShape": {
+      "everyValueIsAString": "No golden in this file is a number. Fractional quantities are converted to the INTEGER unit the writer emits — font size and letter spacing in hundredths of a point, padding and border width in EMU — and then stringified. That removes float comparison from the suite entirely, which matters because the four fancy-conformance loaders do NOT agree on how a float golden is compared (PHP, Python and Rust use a scaled 1e-12 epsilon; the TypeScript loader uses exact Object.is). A suite whose verdict depends on which loader ran it is not a conformance suite.",
+      "resolvedCell": "{ text, bold, italic, underline, color, fill, align, anchor, fontSizeHundredths, letterSpacingHundredths, caps, padding: {left,right,top,bottom}, borders: {left,right,top,bottom}, colSpan, rowSpan, merged }. Booleans are \"1\" / \"0\". `fill` is null when the cell has none. Each border is null when the cell has none on that side, otherwise { widthEmu, color, style }.",
+      "gridWidthsEmu": "An ordered array of strings."
+    },
+    "reference": "php",
+    "referenceNote": "particle-academy/dark-slide is the reference: it shipped first and the trio's contract is 'the same document whichever backend runs it'. Every golden here is the output of RUNNING that engine, never what the value obviously ought to be — the width rows in particular are the accumulate-and-difference result rather than an independent division, and those differ.",
+    "implementations": [
+      { "language": "php", "package": "particle-academy/dark-slide", "symbol": "Table\\TableResolver::resolve" },
+      { "language": "node", "package": "@particle-academy/dark-slide", "symbol": "table/table-resolver.ts TableResolver.resolve" },
+      { "language": "python", "package": "fancy-dark-slide", "symbol": "dark_slide.table.table_resolver.resolve" }
+    ]
+  },
+  "notes": [
+    "PRECEDENCE IS THE POINT, and it is the half a byte comparison cannot reach. The chain is cell > row > column > band (header|stripe|body) > table > theme > default, and the rows here walk it one layer at a time (0009 through 0013) so a port that collapses two layers fails a NAMED case instead of shifting a colour somewhere in a large document. Byte parity across the three engines on a whole reference deck already covers the emission; it covers exactly ONE path through this chain.",
+    "AN ABSENT KEY AND A FALSE KEY ARE DIFFERENT, and conflating them is the most likely port bug in the whole model. Absent falls through to the next layer; `false` STOPS the chain and means off. `borders: false` on a table with a header must therefore beat the header band's own borders, and a row that sets `borders: {bottom: false}` must keep the other three sides. Cases 0005, 0006 and 0016 pin all three directions; a port written with `??` / `or` / `.get(k, default)` passes the first and fails the others.",
+    "COLUMN WIDTHS ARE TWO MODES CHOSEN BY THE VALUES. Every declared width <= 1 makes them FRACTIONS of the table and undeclared columns share the remainder; any declared width > 1 makes them WEIGHTS and undeclared columns weigh 1. No width anywhere is an equal split. Case 0018 pins the boundary at exactly 1.0, which is the value that decides the mode.",
+    "THE WIDTHS MUST SUM TO THE TABLE EXACTLY, so they are accumulated and differenced rather than each rounded independently. Case 0017's goldens are NOT totalEmu * frac rounded per column — 0019 exists specifically because independent rounding gives a different, plausible-looking answer that leaves the grid a few EMU off the frame.",
+    "SPANS ARE CLAMPED TO THE GRID, never emitted as written. A colSpan of 99 on a two-column table is a 2 (case 0020). A row with fewer <a:tc> than the grid declares is a corrupt file rather than a narrow table, so the covered cells are still emitted, carrying `merged` and an empty text.",
+    "THE SIBLING SUITE IS last-word/docx-constructs, and the two packages fail on the SAME axis — per-cell borders, insets, vertical alignment, merging — because both models were narrower than the XML their writers already emitted. That suite pins WordprocessingML output; this one pins a resolver. They are deliberately not the same shape: the XML cannot be shared (w:tcBorders / w:tcMar / w:vAlign against a:lnL..lnB / marL..marB / @anchor) but the DECISIONS can, and this file is expressed in points-and-hex for that reason. Promoting it to `shared/` is the right move the day last-word resolves through the same model; declaring it shared before then would list an implementation that does not run it, which is the failure this repository exists to prevent."
+  ]
+}

package/suites/flow/subflow-registry/cases.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "../../../schema/cases.schema.json",
+  "suite": "flow/subflow-registry",
+  "cases": [
+    {
+      "id": "0001-host-kind-survives-nesting",
+      "title": "A kind the HOST registered is still resolvable inside the child.",
+      "since": "0.8.0",
+      "tags": ["inheritance", "regression"],
+      "input": {
+        "parent": { "@particle-academy/output": "builtin", "host_kind": "host" },
+        "injected": null,
+        "graphConfig": null
+      },
+      "expected": { "@particle-academy/output": "builtin", "host_kind": "host" }
+    },
+    {
+      "id": "0002-bare-builtins-are-not-enough",
+      "title": "A parent carrying several host kinds passes all of them down, not just the builtins.",
+      "since": "0.8.0",
+      "tags": ["inheritance", "regression"],
+      "input": {
+        "parent": {
+          "@particle-academy/output": "builtin",
+          "@particle-academy/transform": "builtin",
+          "agent": "host",
+          "invoice_lookup": "host",
+          "tenant_notify": "host"
+        },
+        "injected": null,
+        "graphConfig": null
+      },
+      "expected": {
+        "@particle-academy/output": "builtin",
+        "@particle-academy/transform": "builtin",
+        "agent": "host",
+        "invoice_lookup": "host",
+        "tenant_notify": "host"
+      }
+    },
+    {
+      "id": "0003-host-override-of-a-builtin-reaches-the-child",
+      "title": "A host that REPLACED a builtin keeps its own version inside the child.",
+      "since": "0.8.0",
+      "tags": ["inheritance", "override", "regression"],
+      "input": {
+        "parent": { "@particle-academy/llm_call": "host", "@particle-academy/output": "builtin" },
+        "injected": null,
+        "graphConfig": null
+      },
+      "expected": { "@particle-academy/llm_call": "host", "@particle-academy/output": "builtin" }
+    },
+    {
+      "id": "0004-graph-config-adds-to-the-inherited-set",
+      "title": "A registry the graph declares on the node is layered ON TOP of the inherited one.",
+      "since": "0.8.0",
+      "tags": ["config"],
+      "input": {
+        "parent": { "@particle-academy/output": "builtin", "host_kind": "host" },
+        "injected": null,
+        "graphConfig": { "child_only": "child-specific" }
+      },
+      "expected": {
+        "@particle-academy/output": "builtin",
+        "host_kind": "host",
+        "child_only": "child-specific"
+      }
+    },
+    {
+      "id": "0005-graph-config-wins-on-a-conflict",
+      "title": "An executor the graph names for its child beats the inherited one of the same kind.",
+      "since": "0.8.0",
+      "tags": ["config", "precedence"],
+      "input": {
+        "parent": { "@particle-academy/output": "builtin", "host_kind": "host" },
+        "injected": null,
+        "graphConfig": { "host_kind": "child-specific" }
+      },
+      "expected": { "@particle-academy/output": "builtin", "host_kind": "child-specific" }
+    },
+    {
+      "id": "0006-an-injected-registry-replaces-the-inherited-one",
+      "title": "A registry handed to the executor at construction is used INSTEAD of the parent's.",
+      "since": "0.8.0",
+      "tags": ["injection", "precedence"],
+      "input": {
+        "parent": { "@particle-academy/output": "builtin", "host_kind": "host" },
+        "injected": { "@particle-academy/output": "builtin", "sandboxed_kind": "host" },
+        "graphConfig": null
+      },
+      "expected": { "@particle-academy/output": "builtin", "sandboxed_kind": "host" }
+    },
+    {
+      "id": "0007-graph-config-still-layers-over-an-injected-registry",
+      "title": "Injection replaces the inherited registry; the graph's own still layers on top of that.",
+      "since": "0.8.0",
+      "tags": ["injection", "config", "precedence"],
+      "input": {
+        "parent": { "host_kind": "host" },
+        "injected": { "@particle-academy/output": "builtin" },
+        "graphConfig": { "child_only": "child-specific" }
+      },
+      "expected": { "@particle-academy/output": "builtin", "child_only": "child-specific" }
+    },
+    {
+      "id": "0008-an-empty-graph-config-changes-nothing",
+      "title": "An empty config registry is not the same as an absent one, and neither empties the child.",
+      "since": "0.8.0",
+      "tags": ["config", "edge"],
+      "input": {
+        "parent": { "@particle-academy/output": "builtin", "host_kind": "host" },
+        "injected": null,
+        "graphConfig": {}
+      },
+      "expected": { "@particle-academy/output": "builtin", "host_kind": "host" }
+    },
+    {
+      "id": "0009-an-empty-parent-yields-an-empty-child",
+      "title": "Inheritance copies what is there; it never invents builtins the parent did not have.",
+      "since": "0.8.0",
+      "tags": ["edge"],
+      "input": { "parent": {}, "injected": null, "graphConfig": null },
+      "expected": {}
+    }
+  ]
+}

package/suites/flow/subflow-registry/manifest.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "../../../schema/suite-manifest.schema.json",
+  "suite": "flow/subflow-registry",
+  "title": "What executors a subflow's child runs against",
+  "since": "0.8.0",
+  "caseFormat": "table",
+  "cases": "cases.json",
+  "contract": {
+    "function": "childRegistry(parent: object, injected: object|null, graphConfig: object|null) -> object",
+    "summary": "Compose the executor registry a `subflow` node runs its CHILD graph against. `parent` is the registry the parent run is executing with, keyed by kind id, whose values stand in for executors. `injected` is a registry handed to the subflow executor at construction, or null. `graphConfig` is the registry the graph itself declares on the subflow node's `config.executors`, or null. The result is the registry the child must resolve against, keyed by kind id.",
+    "reference": "node",
+    "referenceNote": "Designed here rather than lifted from an implementation, because at the time this suite was written all four runtimes were WRONG in the same way and none could serve as the reference. `node` is recorded as the reference because @particle-academy/fancy-flow's run-flow.ts is the behavioural source of truth for the engine generally.",
+    "implementations": [
+      { "language": "node", "package": "@particle-academy/fancy-flow", "symbol": "subflowExecutor" },
+      { "language": "php", "package": "particle-academy/fancy-flow-php", "symbol": "FancyFlow\\Nodes\\Structural\\SubflowExecutor" },
+      { "language": "python", "package": "fancy-flow", "symbol": "fancy_flow.nodes.structural.SubflowExecutor" },
+      { "language": "rust", "package": "fancy-flow", "symbol": "fancy_flow::nodes::structural::SubflowExecutor" }
+    ]
+  },
+  "notes": [
+    "This table exists because ALL FOUR runtimes had the same defect at once, and each of the three that were fixed carried its own hand-written test for it. Three copies of an assertion agree right up until someone changes one of them, and nothing anywhere reports the divergence — which is the same shape as the bug the table describes.",
+    "Reported against the PHP twin as fancy-flow-php#7 by a consumer running a real graph: a child containing a host-registered kind failed with `No executor registered for kind=<host-kind>`, while the identical graph run at top level succeeded. Same workflow, two behaviours depending on nesting depth.",
+    "The TypeScript engine had it with a WORSE default. Its child ran against `config.executors ?? {}` — an EMPTY registry unless the graph happened to carry one — so nesting a graph did not merely lose the host's kinds, it lost everything. PHP and Python fell back to the bare builtins. None of the three warned, because an unregistered kind fails closed with no outputs, which is the correct default and exactly what makes this silent.",
+    "The costly case is not a MISSING kind but a REPLACED one. A host that overrides `llm_call` to add tenancy, budgeting or token accounting gets its own version in the parent and the package's version in the child: the same graph billing two different ways depending on where it was invoked from, with nothing failing. Case 0003 is that case.",
+    "The contract is deliberately a function over REGISTRIES rather than a graph run. `flow/graph-runs` cannot ship a discrimination probe because the implementation under test there is an entire workflow engine, which this package does not carry and should not grow. Registry composition is a pure function over maps, so this suite CAN be probed — and is, in tests/discrimination.test.ts, by the exact mutant that shipped in production: a child that sees only the builtins.",
+    "Values in these maps are marker strings, not executors. `builtin`, `host` and `child-specific` stand for whichever callable a runtime would bind; what the table pins is WHICH one survives into the child, not what it does."
+  ]
+}