Cheetah / Cheetah documentation

Parser registry and definitions

A parser definition is trusted, versioned behavior rather than an anonymous object attached to every command. Cheetah identifies a definition by the exact tuple (engine, parser_id, version), validates it when it enters the server registry, delivers it as cache material, and records the same identity with the parser result.

Changing extraction behavior means creating a new version. It must not silently replace the body already associated with an existing identity.

Registry contract

ParserDefinitionRecord contains:

Registering a new identity stores a defensive copy. Re-registering the same body and schema version may update status and metadata. A different body or schema version under the same identity raises ParserDefinitionConflictError. Deleting through the registry archives the record rather than making that identity available for reuse.

The supplied InMemoryParserRegistry is protected by an asynchronous lock but remains a single-process development implementation. The local preset creates one with the Imprint validator. Redis and production presets accept an application-supplied registry; they do not invent a distributed registry. The built-in registry is not accepted by shared-tenancy composition because its identities are not tenant-scoped.

Command request and cache material

A parser request names an output and exact definition identity:

{
  "engine": "imprint",
  "parser_id": "catalog.product",
  "version": "2026-08-11.1",
  "output_key": "product",
  "required": true
}

The command can also carry capture.parser_definitions. Those entries repeat the identity and add a definition object or an explicitly supported signed-reference marker. They are cache material prepared by the trusted application path, not a general per-command code channel.

AppNode supports two delivery modes:

• inline attaches active registered definitions before ordinary dispatch;
• cache_aware first relies on the client's parser cache. For an RPC send, a narrowly classified missing-required-parser preflight result can cause send_command_and_wait() to issue one new command with definitions attached.

The retry is a new command attempt after a preflight failure, not a replay of an action that already ran. Parser preflight occurs before lease acquisition and handler execution, precisely so the missing definition cannot duplicate application work.

Required parser records must exist and be active when the App node prepares them. Optional parser requests may continue through preflight without a cached definition and later produce a structured parser failure. The exact outcome remains visible under _capture.

Imprint v2 validation

The supplied validator accepts engine: "imprint" and schema version 2.0. It checks the record against the vendored JSON Schema Draft 2020-12 file and also requires the definition's parser_id and schema_version to match the registry record.

A compact definition looks like this:

{
  "schema_version": "2.0",
  "parser_id": "catalog.product",
  "page_matcher": {
    "url_patterns": ["https://shop.example/products/*"],
    "required_selectors": ["main [data-product]"]
  },
  "regions": [
    {
      "name": "product",
      "selector": "main [data-product]",
      "fields": [
        {
          "name": "name",
          "selector": "h1",
          "extract": { "type": "text" },
          "transform": { "type": "trim" },
          "required": true
        }
      ]
    }
  ],
  "output_schema": {
    "type": "object",
    "properties": { "name": { "type": "string" } },
    "required": ["name"]
  }
}

The root requires schema_version, parser_id, page_matcher, at least one region, and an object output schema. Regions can contain fields, collections, or child regions. Supported extractions include text, visible text, attributes, HTML, counts, and existence checks; transforms cover normalization, case, number parsing, regular expressions, templates, and prefix or suffix handling.

The vendored schema is the machine-readable authority for locator strategies, collection filters, nested output fields, and allowed optional keys. Unknown schema fields are rejected. Do not infer additions from a separate Imprint runtime version until the vendored Cheetah schema and its cross-package tests have been updated.

Every recursively nested key beginning with the reserved __cheetah_ prefix is rejected. This protects the distinction between application data and framework-owned payload markers.

Browser execution boundary

The browser runtime composes a parser-definition cache in chrome.storage.local, an offscreen Imprint runner, and a capture provider. The service worker performs preflight against the cache before the action. The offscreen document executes the definition over a serialized DOM snapshot after an applied handler.

The extension must still package the page content script and offscreen assets and request only the origins it is allowed to inspect. A registered definition cannot grant Chrome host permission, inject into a protected page, or broaden client-local policy.

Prepare browser parser capture

Post-command capture