feat(ownir): bound source coordinates and nesting depth (Python-first)

ownlang/obligations.py

@@ -61,6 +61,33 @@
 # matcher vocabulary for `opens`/`closes`/`barriers`/`allow`.
 MATCHER_KINDS = frozenset({"assign", "call"})
 
+# ---------------------------------------------------------------------------
+# defensive limits on externally supplied structure (spec/OwnIR.md §4.2)
+# ---------------------------------------------------------------------------
+
+# The representable range of an OwnIR source-coordinate integer.
+#
+# Python integers are unbounded; a consumer's are not. Leaving the range open
+# means the fact vocabulary is only *implementable* in a language with bignums,
+# which is a contract accident rather than a decision — so the bound is stated
+# here and enforced, instead of being discovered downstream as a port bug.
+INT64_MIN = -(2 ** 63)
+INT64_MAX = 2 ** 63 - 1
+
+# Maximum nesting of `if`/`while` bodies in a flow body or an event tree.
+#
+# Chosen by measurement, from both ends:
+# * the deepest nesting in any OwnIR fixture in this repository is 3
+# (`tests/fixtures/lowered/hoist_neg_nested_depth.facts.json`);
+# * a JSON parser applying the common 128-level recursion cap stops accepting
+# these documents at 62 levels, because each `if` costs two JSON levels.
+# 32 sits an order of magnitude above anything a producer has emitted and
+# roughly half way to the ceiling every consumer can still parse.
+#
+# The limit is on the OwnIR *domain* — nested bodies — not on JSON nesting,
+# because that is the thing a frontend can reason about.
+MAX_NESTING_DEPTH = 32
+
 
 class ProtocolFactsError(ValueError):
  """A malformed protocol/event fact. `load()` wraps this in `OwnIRError`
@@ -212,6 +239,10 @@ def _opt_line(raw: dict[str, Any], ctx: str) -> int:
  v = raw.get("line", 0)
  if not isinstance(v, int) or isinstance(v, bool):
  raise ProtocolFactsError(f"{ctx}: 'line' must be an integer, got {v!r}")
+ if not INT64_MIN <= v <= INT64_MAX:
+ raise ProtocolFactsError(
+ f"{ctx}: 'line' must fit a signed 64-bit integer, got {v} "
+ f"(spec/OwnIR.md §4.2)")
  return v
 
 
@@ -296,9 +327,18 @@ def parse_protocol(raw: Any) -> Protocol:
  methods=tuple(methods_raw), description=desc)
 
 
-def parse_events(raw: Any, ctx: str) -> tuple[Event, ...]:
+def parse_events(raw: Any, ctx: str, depth: int = 0) -> tuple[Event, ...]:
  """Parse an ordered event list (recursive over `if`/`while`), fail-loud on
- an unknown `ev` — the same rule as an unknown flow op (OwnIR IR4)."""
+ an unknown `ev` — the same rule as an unknown flow op (OwnIR IR4).
+
+ `depth` counts enclosing `if`/`while` bodies; the top-level list is 0. The
+ bound is a defensive limit on external input (spec/OwnIR.md §4.2), not a
+ reachable property of real code — the deepest event tree in this
+ repository's fixtures is 2."""
+ if depth > MAX_NESTING_DEPTH:
+ raise ProtocolFactsError(
+ f"{ctx}: events nested deeper than {MAX_NESTING_DEPTH} levels "
+ f"(spec/OwnIR.md §4.2)")
  if not isinstance(raw, list):
  raise ProtocolFactsError(f"{ctx}: events must be an array, got {raw!r}")
  out: list[Event] = []
@@ -332,10 +372,11 @@ def parse_events(raw: Any, ctx: str) -> tuple[Event, ...]:
  out.append(ThrowEv(line=line))
  elif ev == "if":
  out.append(IfEv(line=line,
- then=parse_events(e.get("then", []), ctx),
- orelse=parse_events(e.get("else", []), ctx)))
+ then=parse_events(e.get("then", []), ctx, depth + 1),
+ orelse=parse_events(e.get("else", []), ctx, depth + 1)))
  else: # "while" — EVENT_KINDS is closed, checked above
- out.append(WhileEv(line=line, body=parse_events(e.get("body", []), ctx)))
+ out.append(WhileEv(
+ line=line, body=parse_events(e.get("body", []), ctx, depth + 1)))
  return tuple(out)
 
 

ownlang/ownir.py

@@ -148,6 +148,9 @@
 from .effects import find_effect_storms
 from .evidence import code_flow, di_path_steps
 from .obligations import (
+ INT64_MAX,
+ INT64_MIN,
+ MAX_NESTING_DEPTH,
  MethodEvents,
  Protocol,
  ProtocolFactsError,
@@ -536,6 +539,21 @@ def build_sarif(findings: list[Finding], severity: str = "error") -> dict[str, A
  }
 
 
+def _check_int_range(v: int, where: str, field: str = "line") -> None:
+ """The representable range of an OwnIR source coordinate (spec/OwnIR.md §4.2).
+
+ Python integers are unbounded; a consumer's are not. Without this bound the
+ fact vocabulary is only implementable in a language with bignums, which is a
+ contract accident rather than a decision — and it surfaces downstream as a
+ port rejecting a document the reference accepted. Stated and enforced here
+ instead, Python-first.
+ """
+ if not INT64_MIN <= v <= INT64_MAX:
+ raise OwnIRError(
+ f"{where} {field!r} must fit a signed 64-bit integer, got {v} "
+ f"(spec/OwnIR.md §4.2)")
+
+
 def _check_column(v: Any, where: str) -> None:
  """Fail-loud shape check for an optional source `column` (#317).
 
@@ -554,21 +572,38 @@ def _check_column(v: Any, where: str) -> None:
  if isinstance(v, bool) or not isinstance(v, int) or v < 1:
  raise OwnIRError(
  f"{where} 'column' must be a 1-based integer or absent, got {v!r}")
+ # …and bounded above, for the same reason `line` is (spec/OwnIR.md §4.2):
+ # a column no consumer can represent is not a usable coordinate.
+ _check_int_range(v, where, "column")
 
 
-def _check_flow_columns(nodes: Any, where: str) -> None:
- """Validate `column` on every flow op, including inside `if`/`while` bodies.
+def _check_flow_columns(nodes: Any, where: str, depth: int = 0) -> None:
+ """Validate `column` on every flow op, including inside `if`/`while` bodies,
+ and bound how deeply those bodies may nest.
 
  Recursive because a hoisted branch acquire - the path most likely to be
- forgotten - lives inside a nested body, not at the top level."""
+ forgotten - lives inside a nested body, not at the top level.
+
+ `depth` counts enclosing bodies; the top-level list is 0. The bound is a
+ defensive limit on external input (spec/OwnIR.md §4.2), not a property real
+ code reaches - the deepest flow body in this repository's fixtures is 3."""
+ # The early return comes FIRST. Every op is probed for `then`/`else`/`body`
+ # whether or not it has them, so checking depth before this would count the
+ # absent ones and reject a body at exactly the limit — measured, not
+ # reasoned: `body nesting 32 (at limit)` was rejected until this order was
+ # fixed. Only a list that actually exists is a level.
  if not isinstance(nodes, list):
  return
+ if depth > MAX_NESTING_DEPTH:
+ raise OwnIRError(
+ f"{where} nested deeper than {MAX_NESTING_DEPTH} levels "
+ f"(spec/OwnIR.md §4.2)")
  for n in nodes:
  if not isinstance(n, dict):
  continue
  _check_column(n.get("column"), f"{where} op {n.get('op')!r}")
  for key in ("then", "else", "body"):
- _check_flow_columns(n.get(key), where)
+ _check_flow_columns(n.get(key), where, depth + 1)
 
 
 def load(path: str) -> dict[str, Any]:
@@ -679,12 +714,14 @@ def load(path: str) -> dict[str, Any]:
  ln = s.get("line", 0)
  if not isinstance(ln, int) or isinstance(ln, bool):
  raise OwnIRError("service 'line' must be an integer")
+ _check_int_range(ln, "service")
  # the consuming-constructor location (optional, P-006 Q#1) is validated like file/line.
  if not isinstance(s.get("ctor_file", "?"), str):
  raise OwnIRError("service 'ctor_file' must be a string")
  cln = s.get("ctor_line", 0)
  if not isinstance(cln, int) or isinstance(cln, bool):
  raise OwnIRError("service 'ctor_line' must be an integer")
+ _check_int_range(cln, "service", "ctor_line")
  if not isinstance(s.get("ctor_type", ""), str):
  raise OwnIRError("service 'ctor_type' must be a string")
  # DI004 call-site metadata (optional): an array of {type, file, line} objects.
@@ -697,6 +734,8 @@ def load(path: str) -> dict[str, Any]:
  raise OwnIRError(
  "service 'root_resolve_sites' must be an array of "
  "{type:str, file:str, line:int} objects")
+ for site in sites:
+ _check_int_range(site.get("line", 0), "service root_resolve_site")
  # DI005 (scope-cached captive): types resolved from a self-created scope and cached
  # into a field, plus their field-store sites — validated like root_resolves / its sites.
  scope_cached = s.get("scope_cached", [])
@@ -712,6 +751,8 @@ def load(path: str) -> dict[str, Any]:
  raise OwnIRError(
  "service 'scope_cache_sites' must be an array of "
  "{type:str, file:str, line:int} objects")
+ for site in csites:
+ _check_int_range(site.get("line", 0), "service scope_cache_site")
  # Optional reactive-effect graph (EFF001 — effect storm, P-020). Additive and
  # optional: an older core simply ignores it. Each effect carries its render-scope
  # binding table; the core (ownlang/effects.py) decides identity stability.
@@ -728,6 +769,7 @@ def load(path: str) -> dict[str, Any]:
  eln = eff.get("line", 0)
  if not isinstance(eln, int) or isinstance(eln, bool):
  raise OwnIRError("effect 'line' must be an integer")
+ _check_int_range(eln, "effect")
  binds = eff.get("bindings", [])
  if not isinstance(binds, list) or not all(isinstance(b, dict) for b in binds):
  raise OwnIRError("effect 'bindings' must be a JSON array of objects")
@@ -742,6 +784,7 @@ def load(path: str) -> dict[str, Any]:
  bln = b.get("line", 0)
  if not isinstance(bln, int) or isinstance(bln, bool):
  raise OwnIRError("binding 'line' must be an integer")
+ _check_int_range(bln, "binding")
  # Optional per-method flow bodies (P-016 B0b/B2 — local IDisposable
  # acquire/use/release over a CFG). Additive/optional; an older core ignores it.
  fns = result.get("functions", [])
@@ -777,6 +820,7 @@ def load(path: str) -> dict[str, Any]:
  if not isinstance(pl, int) or isinstance(pl, bool):
  raise OwnIRError(
  f"parameter 'line' must be an integer, got {pl!r}")
+ _check_int_range(pl, "parameter")
  _check_column(p.get("column"), "parameter")
  peff = p.get("effect")
  if peff is not None and peff not in _PARAM_EFFECTS:

spec/OwnIR.md

@@ -172,6 +172,64 @@ when a real `startLine` is present. It is what OwnAudit's `finding-occurrence/v1
 physical anchor reads (Own.NET#317, PhysShell/OwnAudit#58); a finding without one
 is anchored line-only, which is a degradation rather than a failure.
 
+### 4.2 Defensive limits on externally supplied structure (normative)
+
+`OwnIR` is untrusted input: a file a frontend wrote, that `load()` reads. Two of
+its shapes were unbounded, and an unbounded contract is only *implementable* in
+a language that happens to have the same capabilities the reference does. Both
+are now bounded, and the bound is part of the vocabulary rather than a property
+of whichever consumer reads it first.
+
+**Source-coordinate integers fit a signed 64-bit integer.**
+
+- every **validated** `line` — `services[].line`, `services[].ctor_line`,
+ `services[].root_resolve_sites[].line`, `services[].scope_cache_sites[].line`,
+ `effects[].line`, `effects[].bindings[].line`, `functions[].params[].line`,
+ `protocol_functions[].events[].line` — lies in `[-2^63, 2^63 - 1]`;
+- every `column` (§4.1) is `1..=2^63 - 1`, or absent, or `null`.
+
+The word *validated* is load-bearing, and the exception is recorded rather than
+papered over. Two line-bearing fields are checked **nowhere** by `load()` — not
+for range, and not even for type: `components[].subscriptions[].line` and the
+`line` on a flow op inside `functions[].body`. Measured, `{"line": "x"}` and
+`{"line": true}` are accepted on both. That predates this section, and both
+implementations agree about it — neither the reference nor the Rust port types
+those fields — so it is **not** a parity gap and closing it is not part of
+removing one. It is a separate contract question: whether a coordinate that no
+rule reads should nevertheless be well-formed. Until it is answered, the bound
+above claims exactly the fields it covers.
+
+Python integers are unbounded, so the reference accepted coordinates no other
+consumer could represent. That is not a generosity worth keeping: a coordinate
+nothing downstream can hold is not a usable coordinate, and leaving it legal
+turns every port into a source of "the reference accepted this and I cannot".
+The bound is stated here and enforced in `load()`.
+
+**Flow bodies and protocol event trees nest at most 32 levels.**
+
+`functions[].body` and `protocol_functions[].events` nest through `then`,
+`else` and `body`. The limit counts those enclosing bodies — the top-level list
+is level 0 — so a document nesting exactly 32 is accepted and 33 is rejected.
+
+32 is chosen from measurement at both ends:
+
+- the deepest nesting in any `OwnIR` fixture in this repository is **3**
+ (`tests/fixtures/lowered/hoist_neg_nested_depth.facts.json`); the deepest
+ event tree is **2**;
+- a JSON parser applying the widespread 128-level recursion cap stops accepting
+ these documents at **62** levels, because each `if` costs two JSON levels
+ (an object and an array).
+
+So the limit sits an order of magnitude above anything a producer has emitted
+and roughly half way to the ceiling a consumer can still parse. It is expressed
+in the `OwnIR` domain — nested bodies — and not in JSON levels, because nested
+bodies are the thing a frontend can reason about; the ratio between the two is
+an encoding detail.
+
+Both limits are **rejections at the strict door**, not coercions. `check_facts()`
+on un-validated facts keeps its existing degrade-to-absent behaviour: two entry
+points, two contracts, as with `column` in §4.1.
+
 ## 5. Flow bodies (`functions[]`)
 
 A flow function has a `name`, a `file`, and a `body`: an ordered list of flow

spec/ownir.schema.json

@@ -48,8 +48,15 @@
  "$defs": {
  "sourceColumn": {
  "description": "1-based source column of the SAME node `line` anchors on. Optional and additive, so OWNIR_VERSION stays 0 (spec/OwnIR.md §2): a producer that does not report one omits it and no consumer substitutes a value — not 0, not 1, and never recovered by re-reading the source line. Rides to SARIF as region.startColumn, where the OwnAudit occurrence anchor reads it (Own.NET#317).",
+ "type": ["integer", "null"],
+ "minimum": 1,
+ "maximum": 9223372036854775807
+ },
+ "sourceLine": {
+ "description": "A source line. Bounded to a signed 64-bit integer (spec/OwnIR.md \u00a74.2): Python integers are unbounded and the reference used to accept coordinates no other consumer could represent, which made the vocabulary implementable only in a language with bignums. A coordinate nothing downstream can hold is not a usable coordinate. Pinned to ownlang/obligations.py::INT64_MIN/INT64_MAX.",
  "type": "integer",
- "minimum": 1
+ "minimum": -9223372036854775808,
+ "maximum": 9223372036854775807
  },
  "resourceKind": {
  "description": "The resource-kind discriminator (spec/OwnIR.md §4). It selects the analysis path, so a present-but-unknown value is rejected at load (fail-loud) and a new kind must bump OWNIR_VERSION. Pinned to ownlang/ownir.py::_KNOWN_RESOURCE_KINDS.",
@@ -82,7 +89,7 @@
  "properties": {
  "type": { "type": "string" },
  "file": { "type": "string" },
- "line": { "type": "integer" }
+ "line": { "$ref": "#/$defs/sourceLine" }
  }
  },
  "component": {
@@ -168,7 +175,7 @@
  "required": ["name"],
  "properties": {
  "name": { "type": "string" },
- "line": { "type": "integer" },
+ "line": { "$ref": "#/$defs/sourceLine" },
  "column": { "$ref": "#/$defs/sourceColumn" },
  "effect": { "$ref": "#/$defs/paramEffect" }
  }
@@ -295,9 +302,9 @@
  "weak_deps": { "type": "array", "items": { "type": "string" } },
  "root_resolves": { "type": "array", "items": { "type": "string" } },
  "file": { "type": "string" },
- "line": { "type": "integer" },
+ "line": { "$ref": "#/$defs/sourceLine" },
  "ctor_file": { "type": "string" },
- "ctor_line": { "type": "integer" },
+ "ctor_line": { "$ref": "#/$defs/sourceLine" },
  "ctor_type": { "type": "string" },
  "root_resolve_sites": { "type": "array", "items": { "$ref": "#/$defs/site" } },
  "scope_cached": { "type": "array", "items": { "type": "string" } },
@@ -311,7 +318,7 @@
  "description": "Whether the effect performs I/O (default false).",
  "type": "boolean"
  },
- "line": { "type": "integer" },
+ "line": { "$ref": "#/$defs/sourceLine" },
  "deps": {
  "description": "The effect's dependency-array names.",
  "type": "array",
@@ -333,7 +340,7 @@
  "type": "string"
  },
  "refs": { "type": "array", "items": { "type": "string" } },
- "line": { "type": "integer" }
+ "line": { "$ref": "#/$defs/sourceLine" }
  }
  },
  "protocolMatcher": {
@@ -420,7 +427,7 @@
  "ev": { "const": "assign" },
  "target": { "type": "string", "minLength": 1 },
  "value": { "type": ["boolean", "null"] },
- "line": { "type": "integer" }
+ "line": { "$ref": "#/$defs/sourceLine" }
  },
  "required": ["ev", "target"]
  },
@@ -431,7 +438,7 @@
  "ev": { "const": "call" },
  "callee": { "type": "string", "minLength": 1 },
  "arg": { "type": ["string", "null"] },
- "line": { "type": "integer" }
+ "line": { "$ref": "#/$defs/sourceLine" }
  },
  "required": ["ev", "callee"]
  },
@@ -440,7 +447,7 @@
  "description": "A normal method exit.",
  "properties": {
  "ev": { "const": "return" },
- "line": { "type": "integer" }
+ "line": { "$ref": "#/$defs/sourceLine" }
  },
  "required": ["ev"]
  },
@@ -449,7 +456,7 @@
  "description": "An exceptional method exit. Frontends thread finally bodies onto exits, like the flow lowering (§5).",
  "properties": {
  "ev": { "const": "throw" },
- "line": { "type": "integer" }
+ "line": { "$ref": "#/$defs/sourceLine" }
  },
  "required": ["ev"]
  },
@@ -458,7 +465,7 @@
  "description": "A branch with both arms lowered.",
  "properties": {
  "ev": { "const": "if" },
- "line": { "type": "integer" },
+ "line": { "$ref": "#/$defs/sourceLine" },
  "then": { "type": "array", "items": { "$ref": "#/$defs/protocolEvent" } },
  "else": { "type": "array", "items": { "$ref": "#/$defs/protocolEvent" } }
  },
@@ -469,7 +476,7 @@
  "description": "A loop; the checker solves the body to a local fixpoint.",
  "properties": {
  "ev": { "const": "while" },
- "line": { "type": "integer" },
+ "line": { "$ref": "#/$defs/sourceLine" },
  "body": { "type": "array", "items": { "$ref": "#/$defs/protocolEvent" } }
  },
  "required": ["ev"]