forge-lcdl

Handbook

Artifact `PageMechanicsSpec` v1

JSON object exchanged between source-ingest Playwright runtime and LCDL mechanics tasks. It describes inferred page kind, confidence, a question context blob, ordered actions the runtime may execute (declarative kinds…

Artifact PageMechanicsSpec v1

Summary

JSON object exchanged between source-ingest Playwright runtime and LCDL mechanics tasks. It describes inferred page kind, confidence, a question context blob, ordered actions the runtime may execute (declarative kinds only—no arbitrary scripts), and metadata for grading, loops, safety, and notes.

LCDL does not run Playwright; the runtime consumes this spec after validation.

Root object

Field Type Required Notes
schema_version string yes Must be exactly page_mechanics_v1.
page_kind string yes One of the allowed page_kind values (see below). Use unknown when unsure.
confidence number yes Model or heuristic confidence in [0.0, 1.0].
question object yes Opaque context for the question flow (e.g. stems, option labels, DOM hints). May be {}.
actions array yes Ordered list of action objects (see Action object).
grading object yes How correctness is observed (e.g. revealed answer, score selector). May be {}.
loop object yes Pagination / repeat hints. May be {}.
safety object yes Bounds (max steps, stop conditions). May be {}.
notes string yes Human-readable caveats; use "" if none.

Allowed page_kind values

  • static_mcq_page
  • interactive_quiz
  • paginated_static_quiz
  • api_backed_quiz
  • pdf_or_document
  • login_or_blocked
  • unknown

Any other string is invalid for v1.

Action object

Each element of actions is an object:

Field Type Required Notes
kind string yes One of the allowed action kinds (see below).
… varies no Additional fields (e.g. selector, value, timeout_ms) are defined by the runtime; this contract does not enumerate them.

Allowed action kind values

  • click
  • click_if_present
  • click_option_by_index
  • select_option_by_value
  • fill
  • press
  • wait_for_selector
  • wait_for_text_change
  • wait_for_url_change
  • wait_for_network_idle
  • read_text
  • read_attribute
  • read_class

Forbidden action kinds

These must never appear—arbitrary JavaScript execution is out of scope:

  • eval
  • execute_js
  • script

(Case-insensitive match for rejection in validators.)

Validation split

  • forge-lcdl (validate_page_mechanics_shape, validate_allowed_actions): lightweight structural and enum checks for tasks and tooling.
  • Source-ingest runtime: selector existence, timeouts, deterministic replay, and full Playwright semantics.

Changelog

  • v1 — Initial mechanics discovery contract.