tjs-lang 0.8.7 → 0.9.0

package/docs/ambient-contracts.md

@@ -0,0 +1,261 @@
+# Ambient Contracts — probe reality, derive verified predicate contracts
+
+> **Status: design note / idea (2026-07-03).** Not built. Captures the direction
+> and a concrete first spike (CSS + DOM). Related: the predicate engine
+> (`src/lang/predicate.ts`), the `tjs-lang/css` library (`src/css/`), the
+> autocomplete introspection bridge (`demo/src/introspection-bridge.ts`,
+> `editors/introspect-value.ts`), and the VM capability model (`src/vm/`).
+
+## The itch
+
+Static types are pessimistic about ambient runtime environments (the DOM, Node
+globals, `window`, host objects) in ways that create ceremony without safety.
+The canonical example:
+
+```ts
+element.addEventListener('input', (e) => {
+  const value = e.target.value // ❌ TS: Property 'value' does not exist on 'EventTarget'
+})
+```
+
+`e.target` is typed `EventTarget | null`, and `EventTarget` has no `.value`, so
+TypeScript forces `(e.target as HTMLInputElement).value` or a `instanceof` dance.
+But the honest situation is: **at runtime the value is either there or it
+isn't, and if it isn't you find out immediately.** The cast doesn't make it
+safer — it just silences a compiler that can't see the real object. A runtime
+predicate is the truthful tool here:
+
+```tjs
+// pure, total, verifiable — reads props, no cast, no lie
+function hasValueTarget(e) {
+  return e != null && e.target != null && typeof e.target.value === 'string'
+}
+// usage: hasValueTarget(e) ? e.target.value : undefined  — no ceremony
+```
+
+That predicate is exactly what the verifier accepts (member access is pure;
+`typeof` → `TypeOf`), compiles to native, and — crucially — is **serializable**.
+So the thought: instead of hand-writing these, could tooling **probe a real
+ambient environment and derive the predicate contracts automatically?**
+
+## The payoff: author against an environment you're not running in
+
+The headline use (user, 2026-07-03): **type-checking and autocompletion against a
+non-ambient runtime — editing in a Node-based toolchain while _targeting_ the
+browser** (or the reverse, or Electron, or a specific Bun). Normally you have no
+target environment to introspect, so you fall back to a hand-maintained
+`.d.ts` (`lib.dom`) that drifts from what the engine actually does.
+
+Because a probed contract is a **serializable predicate**, it decouples _capture_
+from _consumption_ in time and space: probe the real target once (locally or in
+CI), bottle the contract, and a Node-side editor/typechecker consumes it with **no
+target present**. It beats a `.d.ts` on three axes:
+
+- **Grounded in reality, not a drifting spec** — it's what the target _actually_
+  exposes (we watched happy-dom diverge 678 vs 1 own-keys from real Chrome; a
+  captured contract is the real number).
+- **Target-specific and versioned** — capture from the _actual_ target (this
+  browser, this Electron, this Bun), selectable/pinned, not a lowest-common-
+  denominator lib.
+- **The same artifact validates at runtime** — a `.d.ts` evaporates; a predicate
+  contract can stay as a boundary guard, and its enumerable leaves feed
+  `suggest()` completions with real values.
+
+Why it's plausible _here_ and not a research project: the contract format already
+exists (`$predicate` / `tjs-lang/schema`), the autocomplete provider already has
+an introspection hook (`getMembers` — point it at a captured contract instead of a
+live object), and this is exactly the metadata the pinned "argument-type-driven
+completion" item wants (e.g. `createElement`'s tag→type return shapes), sourced
+from reality instead of hand-authored. See [[introspection-autocomplete]].
+
+## Contract vs. shim — the distinction that decides feasibility
+
+"A predicate that stands in for the DOM" can mean two very different things:
+
+1. **A contract / validator** — "does this value behave enough like an
+   `HTMLElement` / an input event / a `CSSStyleDeclaration`?" Predicates are
+   _pure validators_, so this is squarely in scope: shape, property presence,
+   method arity, pure invariants.
+2. **A behavioral substitute** — something that, when code calls
+   `document.createElement('div')`, actually _does_ it. Predicates **cannot** be
+   this (they're pure, stateless, effect-free). That's a shim — happy-dom/jsdom
+   territory.
+
+The valuable, on-thesis move is **#1 as the bridge to #2**: probe the real
+environment, emit a serializable predicate _contract_, and use it to **certify a
+stand-in** in whatever setting. The predicate isn't the DOM — it's the portable,
+verifiable spec a substitute must satisfy, auto-derived from reality and from the
+surface a given program actually touches.
+
+## Why it fits this project
+
+- **The introspection probe already exists.** The autocomplete work runs code in
+  a real iframe and reads live scope (`introspect-value.ts`,
+  `introspection-bridge.ts`); Claude-in-Chrome can drive a _real_ browser. That's
+  the "kick the tires" mechanism.
+- **Predicates are the serializable contract form** — verified, ReDoS-safe,
+  compile-to-native, travel as data (the `$predicate` keyword already embeds them
+  in JSON Schema, now evaluated by `tosijs-schema` via `tjs-lang/schema`).
+- **The VM already models this as capabilities.** It injects `fetch`/`store`/
+  `llm`; "DOM-as-capability, predicate-validated at the boundary" is the same
+  pattern. A headless setting swaps the stub; the predicate catches divergence.
+- **"Types are examples" already** — deriving a contract from _observed_ real
+  values is the same philosophy as `inferTypeFromValue`, sourced from a live probe
+  instead of a literal.
+
+## The honest constraints
+
+- **Most of the DOM's contract is _behavioral_** (layout, events, mutation),
+  which a pure predicate can't capture — only shape + pure invariants. So:
+  - **Scope to the used surface.** Trace which ambient APIs the code actually
+    touches (in the real iframe) and derive a contract for _that slice_, not all
+    of `lib.dom.d.ts`.
+  - **Behavioral conformance is a separate, impure harness** — run the same probe
+    battery against the real env and a candidate stub, diff the outputs. The
+    predicate is the pure shape-gate; the harness is the behavior-gate.
+- **Snapshots drift.** Browsers evolve; a captured contract is a dated snapshot.
+  Fine — it's re-derivable, and versioning it is a feature (conformance over
+  time).
+- **Non-determinism / side effects** must stay outside predicates (the `effects`
+  tag already enforces this): a predicate validates the _data_ crossing the
+  boundary, never performs the effect.
+
+## Shape of the tooling (sketch)
+
+1. **Probe** — in a real environment (browser via Claude-in-Chrome, or the
+   introspection iframe), walk an ambient object / a program's used surface and
+   record: property names + `typeof`, method names + `.length` (arity), and a few
+   sampled input→output pairs for pure-ish accessors.
+2. **Derive** — turn the probe record into a predicate cluster (shape checks +
+   `typeof` guards + membership sets), run it through `verifyPredicate` (so the
+   emitted contract is itself certified safe), and `suggest()`-mine it for the
+   enumerable leaves.
+3. **Emit** — a `$predicate` schema (naive validators see structure, aware ones
+   run the contract) + optionally a `.d.ts`-ish view for editors.
+4. **Conform** — a harness that validates a stand-in (happy-dom, a hand stub, a
+   VM capability) against the contract, failing loud where it diverges. This is
+   what would have unblocked the Phase 5 real-`tosijs`-theme measurement (blocked
+   because `theme.ts` needs `HTMLElement` at import).
+
+## First spike — CSS + DOM (the convergence point)
+
+`element.style` (`CSSStyleDeclaration`) is the ideal first target: it's an
+ambient, stateful host object, and we _already have a full CSS value grammar as
+predicates_ (`tjs-lang/css`). So the loop is concrete and small:
+
+- **`event.target` demo** — show the `hasValueTarget` predicate compiles, is
+  verified pure, is total, and validates a real input event while rejecting a
+  click on a `<div>`. The predicate TypeScript won't let you write cleanly is a
+  perfectly ordinary verified predicate. (This is the "asinine" antidote, and
+  needs no browser — synthetic event-shaped objects suffice for the unit; a real
+  browser confirms on live events.)
+- **`CSSStyleDeclaration` probe** — introspect real `element.style` in a browser,
+  derive a shape contract, and diff a happy-dom `style` against it: where does the
+  stub lie? Leaf _values_ ride the existing CSS predicates (`isColorValue`,
+  `isDimension`, …), so this exercises probe → contract → conformance end-to-end
+  while reusing what phases 1–5 built.
+
+## Ask the environment directly — `CSS.supports` (tosijs-ui port finding)
+
+The tosijs 2.0 port arrived at the same idea from the other side (see
+`../tosijs/TJS-PORT-DX.md`): the strongest form of "probe reality" for CSS is to
+**ask the browser's own validator** — `CSS.supports(prop, value)` is exact, always
+current with the engine's real support (vendor prefixes, new features, the full
+`calc()`/`var()` grammar), and zero-maintenance. It closes the exact gap the
+hand-authored grammar has: `isCssProperty('align-kontent')` returns `true`
+(identifier-shaped), but `CSS.supports('align-kontent', …)` in a real browser
+returns `false`. Property names for autocomplete come from the same place (a
+throwaway element's `.style` keys / `CSSStyleDeclaration.prototype`).
+
+This sharpens the contract-vs-fallback split by **when** validation runs:
+
+- **Runtime, in a browser** → `CSS.supports` is ground truth (exact, free). A
+  `CSS.supports`-based check is predicate-_safe to run_ but references the ambient
+  `CSS` object, so it can't be statically _verified_ (it's effectful/ambient).
+- **Transpile-time / SSR / Node** → no `CSS`, so the hand-authored grammar
+  predicates (`isColor`/`isLength`/`isStyleValueFor`) are the portable fallback.
+
+So the ideal CSS-value check prefers `CSS.supports` when `typeof CSS !== 'undefined'`
+and falls back to the grammar predicate otherwise — which is exactly the
+probe-reality / portable-fallback pairing this whole note is about, one leaf down.
+**Caveat (verified, and it's the same "the stand-in lies" finding): happy-dom
+stubs `CSS.supports` to return `true` for everything** (even `width: banana`) — so
+tests can't rely on it; ground truth needs a real browser or a real CSS engine.
+
+## Findings from the first spike (2026-07-03)
+
+Built in `experiments/ambient/` (`probe.ts` + two demo tests, 7 green):
+
+- **The `event.target` predicate is ordinary.** `hasValueTarget(e)` (reads
+  `e.target.value`, the thing TS rejects) verifies pure/safe, compiles native, and
+  is total — no throw on a missing target. The cast TS demands buys nothing a
+  predicate doesn't. (`event-target.demo.test.ts`.)
+- **Host objects hide their surface on the prototype.** Probed a real
+  `CSSStyleDeclaration` via happy-dom: `Object.keys(style)` is nearly empty, yet
+  `typeof style.color === 'string'` and `typeof style.setProperty === 'function'`.
+  So a naive own-enumerable probe derives an empty contract — **the probe must
+  walk the prototype chain** (`getOwnPropertyNames` per proto) or check a scoped
+  key list. `probeShape` now does both.
+- **Scope to the used surface — the full proto chain is huge.** An `HTMLElement`'s
+  chain is hundreds of props; a whole-shape contract would be enormous and
+  over-specified. A `keys: [...]` scope (the surface a program actually touches,
+  traced from the real env) is the right input. Demonstrated: a 4-key contract for
+  `style` verifies safe, accepts a real happy-dom `style` and a conforming hand
+  stub, rejects a plain object missing the methods.
+- **Reading accessors during a probe can have side effects** (`offsetWidth` forces
+  layout). A scoped key list bounds this; a stricter probe would read property
+  _descriptors_ rather than the values. Getters that throw are skipped.
+- **CSS convergence holds.** Leaf values off the real object ride the existing
+  `tjs-lang/css` predicates (`isColorValue(style.color)`), so shape-gate (contract)
+  + value-grammar (css) compose — the recursive style structure from CSS phase 4
+  is the same shape a DOM-derived contract would target.
+
+Net: the probe→derive→verify→conform loop works end-to-end on a real host object;
+the open work is sourcing the used-surface scope (trace) and the behavioral half.
+
+### Real-browser findings (via haltija `/eval`, live Chrome — 2026-07-03)
+
+Confirmed against a real browser (not happy-dom), which sharpened three points:
+
+- **Builtins don't honor `new`.** `new HTMLDivElement()` → `TypeError: Failed to
+  construct 'HTMLDivElement': Illegal constructor`. You **don't need `new`** — the
+  shape is on the constructor's `.prototype` chain
+  (`HTMLDivElement → HTMLElement → Element → Node → EventTarget`), readable
+  statically, no instance, no side effects. Cleaner than instantiating.
+- **The manager vends the type.** `document.createElement('div').constructor ===
+  HTMLDivElement` (and `'a' → HTMLAnchorElement`, `'input' → HTMLInputElement`).
+  So a factory's output gives you _both_ a live example (real default values — the
+  "types are examples" leaf) _and_ the type identity (`.constructor` → name +
+  `.constructor.prototype` → the surface). Two complementary probe sources that
+  cross-check.
+- **Structural contracts are realm-portable; `instanceof` is not — proved.** An
+  `<iframe>`'s input: `instanceof HTMLInputElement` (top realm) = **false**, but
+  the structural predicate (`typeof x.value === 'string' && x.tagName === 'INPUT'`)
+  = **true**. This is the whole argument in one line: nominal DOM types are
+  realm-bound (the stand-in problem _is_ a realm problem), a derived structural
+  predicate crosses realms. (happy-dom couldn't show this — it shares one
+  `HTMLInputElement` across `Window`s; the real browser does.)
+- **Bonus — the stand-in already diverges from reality.** Real Chrome's `style`
+  has **678 own keys** (CSS properties as own props); happy-dom's had ~1 (on the
+  proto). Same object, wildly different probe result — exactly the conformance gap
+  the harness exists to catch, and proof that you must probe _reality_, not a
+  stand-in, to derive the contract.
+
+### Generalizes beyond the DOM — Node/Bun internals
+
+The probe is environment-agnostic: `process`, `Buffer`, `node:fs`, `Bun.*`,
+`globalThis` are ambient objects with the same shape. Derive a used-surface
+contract from the _real_ runtime and certify a stand-in — e.g. "does my `process`
+usage survive in the browser polyfill?" or "does Bun's `process` satisfy the
+contract my code derived from Node's?". It's the realm/stand-in problem one level
+up: cross-_runtime_ portability instead of cross-_frame_. Same tool.
+
+## Open questions
+
+- Where's the line between "derive automatically" and "author, then verify
+  against reality"? The probe likely _proposes_ a contract a human trims.
+- Method behavior: can we derive useful pure invariants for methods
+  (idempotence, `getComputedStyle(x)` shape) or only signatures?
+- Editor story: a derived `$predicate` contract as the source of both validation
+  _and_ autocomplete (the introspection-autocomplete north star) for host objects
+  that ship no good `.d.ts`.