@termwright/protocol 0.2.0 → 0.3.0

package/dist/action-model-BP9Znu6L.d.ts

@@ -0,0 +1,219 @@
+import { b as SemanticSnapshot, n as ObservationStamp, O as Observation, R as Rect, j as EvidenceProvenance } from './contract-CH9gmj2Y.js';
+import './capability-graph.js';
+
+/** Policy applied when runtime values cross an artifact/publication boundary. */
+declare const ARTIFACT_VALUE_POLICIES: readonly ["none", "redacted", "raw"];
+type ArtifactValuePolicy = (typeof ARTIFACT_VALUE_POLICIES)[number];
+/** Secure default. Recording raw input must always be an explicit choice. */
+declare const DEFAULT_ARTIFACT_VALUE_POLICY: ArtifactValuePolicy;
+type ValueSensitivity = 'public' | 'sensitive';
+/** Explicit wrapper for values which must not enter artifacts by default. */
+interface SensitiveValue {
+    readonly sensitivity: 'sensitive';
+    readonly value: string;
+}
+interface PublicValue {
+    readonly sensitivity: 'public';
+    readonly value: string;
+}
+/** Plain strings remain executable but are conservatively sensitive at artifact boundaries. */
+type ExecutableValue = string | PublicValue | SensitiveValue;
+type RecordedValue = {
+    readonly status: 'known';
+    readonly value: string;
+    readonly sensitivity: ValueSensitivity;
+} | {
+    readonly status: 'withheld';
+    readonly reason: 'artifact-policy';
+    readonly sensitivity: ValueSensitivity | 'unknown';
+};
+declare function sensitive(value: string): SensitiveValue;
+declare function publicValue(value: string): PublicValue;
+declare function executableText(value: ExecutableValue): string;
+declare function valueSensitivity(value: ExecutableValue): ValueSensitivity;
+declare function recordValue(value: ExecutableValue, policy: ArtifactValuePolicy): RecordedValue;
+declare function projectSemanticSnapshotForArtifact(snapshot: SemanticSnapshot, policy?: ArtifactValuePolicy): SemanticSnapshot;
+
+type LocatorDomain = 'semantic' | 'screen';
+type SemanticLocatorRef = `semantic:${string}@${number}`;
+type ScreenLocatorRef = `screen:${number},${number},${number},${number}@${number}`;
+type LocatorRef = SemanticLocatorRef | ScreenLocatorRef;
+type ConditionTextMatcher = {
+    readonly kind: 'exact' | 'substring';
+    readonly text: string;
+} | {
+    readonly kind: 'regex';
+    readonly source: string;
+    readonly flags: string;
+};
+type Condition = {
+    readonly kind: 'attached';
+    readonly target: string;
+} | {
+    readonly kind: 'detached';
+    readonly target: string;
+} | {
+    readonly kind: 'displayed';
+    readonly target: string;
+} | {
+    readonly kind: 'hidden';
+    readonly target: string;
+} | {
+    readonly kind: 'visible';
+    readonly target: string;
+} | {
+    readonly kind: 'in-viewport';
+    readonly target: string;
+    readonly minRatio: number;
+} | {
+    readonly kind: 'offscreen';
+    readonly target: string;
+} | {
+    readonly kind: 'receives-pointer';
+    readonly target: string;
+} | {
+    readonly kind: 'pointer-region';
+    readonly target: string;
+} | {
+    readonly kind: 'pointer-input';
+    readonly target: string;
+} | {
+    readonly kind: 'mouse-input-enabled';
+    readonly target: string;
+} | {
+    readonly kind: 'enabled';
+    readonly target: string;
+} | {
+    readonly kind: 'disabled';
+    readonly target: string;
+} | {
+    readonly kind: 'focused';
+    readonly target: string;
+} | {
+    readonly kind: 'checked';
+    readonly target: string;
+    readonly value: boolean;
+} | {
+    readonly kind: 'selected';
+    readonly target: string;
+    readonly value: boolean;
+} | {
+    readonly kind: 'expanded';
+    readonly target: string;
+    readonly value: boolean;
+} | {
+    readonly kind: 'collapsed';
+    readonly target: string;
+} | {
+    readonly kind: 'value';
+    readonly target: string;
+    readonly matcher: ConditionTextMatcher;
+} | {
+    readonly kind: 'not';
+    readonly condition: Condition;
+} | {
+    readonly kind: 'all' | 'any';
+    readonly conditions: readonly Condition[];
+};
+type ScreenLeafCondition = Extract<Condition, {
+    readonly kind: 'attached' | 'detached' | 'displayed' | 'hidden' | 'visible' | 'in-viewport' | 'offscreen' | 'receives-pointer' | 'pointer-region' | 'pointer-input' | 'mouse-input-enabled';
+}>;
+type ScreenCondition = ScreenLeafCondition | {
+    readonly kind: 'not';
+    readonly condition: ScreenCondition;
+} | {
+    readonly kind: 'all' | 'any';
+    readonly conditions: readonly ScreenCondition[];
+};
+interface ConditionResult {
+    readonly condition: Condition;
+    readonly checkpoint: ObservationStamp;
+    readonly observation: Observation<boolean>;
+    readonly verdict: 'satisfied' | 'unsatisfied' | 'inconclusive';
+}
+/** A disjoint physical region represented as canonical, non-overlapping row spans. */
+interface PhysicalRegion {
+    readonly checkpoint: ObservationStamp;
+    readonly coordinateSpace: 'viewport-cells';
+    readonly intendedRect: Rect;
+    readonly spans: readonly {
+        readonly row: number;
+        readonly from: number;
+        readonly to: number;
+    }[];
+    readonly evidence: EvidenceProvenance;
+}
+type ActionKind = 'click' | 'double-click' | 'hover' | 'drag' | 'focus' | 'activate' | 'press' | 'type' | 'paste' | 'fill' | 'check' | 'uncheck' | 'wheel' | 'shell-command' | 'resize';
+interface ActionIntent {
+    readonly kind: ActionKind;
+    readonly selector?: string;
+    readonly targetRef?: LocatorRef;
+}
+type ExecutableDeviceOperation = {
+    readonly device: 'keyboard';
+    readonly kind: 'press' | 'type' | 'paste';
+    readonly value: ExecutableValue;
+} | {
+    readonly device: 'mouse';
+    readonly kind: 'move' | 'down' | 'up' | 'wheel';
+    readonly row: number;
+    readonly column: number;
+    readonly button?: 'left' | 'middle' | 'right';
+    readonly modifiers?: readonly ('shift' | 'alt' | 'control')[];
+    readonly deltaX?: number;
+    readonly deltaY?: number;
+};
+type RecordedDeviceOperation = {
+    readonly device: 'keyboard';
+    readonly kind: 'press' | 'type' | 'paste';
+    readonly value: RecordedValue;
+} | Exclude<ExecutableDeviceOperation, {
+    readonly device: 'keyboard';
+}>;
+/** Runtime-only plan. It must be projected before crossing an artifact boundary. */
+interface ExecutableActionPlan {
+    readonly actionId: string;
+    readonly contractId: string;
+    readonly intent: ActionIntent;
+    readonly checkpoint: ObservationStamp;
+    readonly requirements: readonly ConditionResult[];
+    readonly strategy: string;
+    readonly physicalRegion?: PhysicalRegion;
+    readonly operations: readonly ExecutableDeviceOperation[];
+}
+interface ActionPlan {
+    readonly actionId: string;
+    readonly contractId: string;
+    readonly intent: ActionIntent;
+    readonly checkpoint: ObservationStamp;
+    readonly requirements: readonly ConditionResult[];
+    readonly strategy: string;
+    readonly physicalRegion?: PhysicalRegion;
+    readonly operations: readonly RecordedDeviceOperation[];
+    readonly valuePolicy: ArtifactValuePolicy;
+}
+interface ActionabilityExplanation {
+    readonly actionable: boolean;
+    readonly intent: ActionIntent;
+    readonly checkpoint: ObservationStamp;
+    readonly requirements: readonly ConditionResult[];
+    readonly strategy?: string;
+    readonly reason?: {
+        readonly code: string;
+        readonly message: string;
+        readonly targetRef?: LocatorRef;
+    };
+}
+interface ActionReceipt {
+    readonly intent: ActionIntent;
+    readonly plan: ActionPlan;
+    readonly before: ObservationStamp;
+    readonly after: ObservationStamp;
+    readonly executed: readonly RecordedDeviceOperation[];
+    readonly outcome: 'completed' | 'partial' | 'failed';
+}
+declare function recordDeviceOperation(operation: ExecutableDeviceOperation, policy: ArtifactValuePolicy): RecordedDeviceOperation;
+declare function recordActionPlan(plan: ExecutableActionPlan, policy: ArtifactValuePolicy): ActionPlan;
+declare function projectActionReceiptForArtifact(receipt: ActionReceipt, policy: ArtifactValuePolicy): ActionReceipt;
+
+export { ARTIFACT_VALUE_POLICIES as A, type Condition as C, DEFAULT_ARTIFACT_VALUE_POLICY as D, type ExecutableActionPlan as E, type LocatorDomain as L, type PhysicalRegion as P, type RecordedDeviceOperation as R, type ScreenCondition as S, type ValueSensitivity as V, type ActionIntent as a, type ActionKind as b, type ActionPlan as c, type ActionReceipt as d, type ActionabilityExplanation as e, type ArtifactValuePolicy as f, type ConditionResult as g, type ConditionTextMatcher as h, type ExecutableDeviceOperation as i, type ExecutableValue as j, type LocatorRef as k, type PublicValue as l, type RecordedValue as m, type ScreenLeafCondition as n, type ScreenLocatorRef as o, type SemanticLocatorRef as p, type SensitiveValue as q, executableText as r, projectActionReceiptForArtifact as s, projectSemanticSnapshotForArtifact as t, publicValue as u, recordActionPlan as v, recordDeviceOperation as w, recordValue as x, sensitive as y, valueSensitivity as z };

package/dist/action-model.d.ts

@@ -0,0 +1,3 @@
+import './contract-CH9gmj2Y.js';
+export { a as ActionIntent, b as ActionKind, c as ActionPlan, d as ActionReceipt, e as ActionabilityExplanation, C as Condition, g as ConditionResult, h as ConditionTextMatcher, E as ExecutableActionPlan, i as ExecutableDeviceOperation, L as LocatorDomain, k as LocatorRef, P as PhysicalRegion, R as RecordedDeviceOperation, S as ScreenCondition, n as ScreenLeafCondition, o as ScreenLocatorRef, p as SemanticLocatorRef, s as projectActionReceiptForArtifact, v as recordActionPlan, w as recordDeviceOperation } from './action-model-BP9Znu6L.js';
+export { CONDITION_KINDS, ConditionKind } from './capability-graph.js';

package/dist/action-model.js

@@ -0,0 +1,15 @@
+import {
+  projectActionReceiptForArtifact,
+  recordActionPlan,
+  recordDeviceOperation
+} from "./chunk-PUXRCPGY.js";
+import {
+  CONDITION_KINDS
+} from "./chunk-VBLS6E6U.js";
+export {
+  CONDITION_KINDS,
+  projectActionReceiptForArtifact,
+  recordActionPlan,
+  recordDeviceOperation
+};
+//# sourceMappingURL=action-model.js.map

package/dist/action-model.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/capability-graph.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Executable capability graph shared by certification, negotiation tooling,
+ * documentation and every public action surface.
+ *
+ * A producer declaration is not itself a public guarantee. Edges make the
+ * complete path explicit: producer fact -> frozen session evidence -> runtime
+ * prerequisite -> planning strategy/public consumer. Diagnostic facts never
+ * unlock a public API.
+ */
+declare const CAPABILITY_GRAPH_VERSION: 5;
+declare const CAPABILITY_NODE_CATEGORIES: readonly ["evidence", "input", "planning", "synchronization", "diagnostic"];
+type CapabilityNodeCategory = (typeof CAPABILITY_NODE_CATEGORIES)[number];
+declare const CAPABILITY_NODE_LAYERS: readonly ["producer", "session", "runtime", "strategy", "public"];
+type CapabilityNodeLayer = (typeof CAPABILITY_NODE_LAYERS)[number];
+declare const CAPABILITY_EDGE_KINDS: readonly ["produces", "requires", "requires-any", "runtime-requires", "diagnoses"];
+type CapabilityEdgeKind = (typeof CAPABILITY_EDGE_KINDS)[number];
+declare const ADAPTER_CAPABILITIES: readonly ["tree", "intended-geometry", "clipped-geometry", "states", "focus-state", "actions", "action-recipes", "text-ranges", "render-revisions", "logs", "pointer-hit-grid"];
+type AdapterCapability = (typeof ADAPTER_CAPABILITIES)[number];
+declare const PROBE_CAPABILITIES: readonly ["stable-identity", "intended-rect", "visible-rect", "operations", "annotations", "frame-begin", "paint-order"];
+type ProbeCapability = (typeof PROBE_CAPABILITIES)[number];
+declare const EVIDENCE_PROVIDER_CAPABILITIES: readonly ["pointer-regions", "hit-test", "focus-state", "action-recipes", "scroll-state", "painted-regions", "terminal-input-modes"];
+type EvidenceProviderCapability = (typeof EVIDENCE_PROVIDER_CAPABILITIES)[number];
+declare const EVIDENCE_PROVIDER_TYPES: readonly ["pointer-evidence", "focus-evidence", "action-strategy", "scroll-evidence", "paint-evidence", "input-mode-evidence"];
+type EvidenceProviderType = (typeof EVIDENCE_PROVIDER_TYPES)[number];
+declare const SESSION_CAPABILITIES: readonly ["semantic-tree", "stable-identity", "intended-geometry", "clipped-geometry", "painted-region", "pointer-geometry", "pointer-hit-testing", "focus", "scroll", "render-order", "action-strategies", "keyboard-input", "pointer-input", "focus-input", "paired-revisions"];
+type SessionCapabilityId = (typeof SESSION_CAPABILITIES)[number];
+declare const RUNTIME_PREREQUISITES: readonly ["writable-pty", "terminal-input-modes-authoritative", "mouse-reporting-enabled", "mouse-motion-enabled", "focus-reporting-enabled", "committed-observation"];
+type RuntimePrerequisiteId = (typeof RUNTIME_PREREQUISITES)[number];
+declare const PUBLIC_CAPABILITY_CONSUMERS: readonly ["locator.semantic-query", "locator.semantic-scroll", "locator.painted-region", "condition.attached", "condition.displayed", "condition.visible", "condition.in-viewport", "condition.focused", "condition.value", "action.click", "action.hover", "action.drag", "action.focus", "action.activate", "action.type", "action.fill", "action.check", "action.uncheck", "device.keyboard", "device.mouse", "device.window-focus", "checkpoint", "runner.inspector", "trace.action", "recorder.semantic-action", "mcp.semantic-action", "runner.diagnostics", "trace.diagnostics"];
+type PublicCapabilityConsumer = (typeof PUBLIC_CAPABILITY_CONSUMERS)[number];
+declare const CAPABILITY_CONFORMANCE_CLAIMS: readonly ["claim.semantic-tree-authoritative", "claim.stable-identity-authoritative", "claim.intended-geometry-authoritative", "claim.clipped-geometry-authoritative", "claim.painted-region-authoritative", "claim.pointer-region-authoritative", "claim.pointer-hit-test-authoritative", "claim.focus-authoritative", "claim.scroll-authoritative", "claim.render-order-authoritative", "claim.action-strategy-authoritative", "claim.keyboard-real-pty", "claim.pointer-real-pty", "claim.focus-report-real-pty", "claim.paired-revisions", "claim.logs-diagnostic"];
+type CapabilityConformanceClaimId = (typeof CAPABILITY_CONFORMANCE_CLAIMS)[number];
+declare const CONDITION_KINDS: readonly ["attached", "detached", "displayed", "hidden", "visible", "in-viewport", "offscreen", "receives-pointer", "pointer-region", "pointer-input", "mouse-input-enabled", "enabled", "disabled", "focused", "checked", "selected", "expanded", "collapsed", "value", "not", "all", "any"];
+type ConditionKind = (typeof CONDITION_KINDS)[number];
+type CapabilityNodeId = `adapter.${AdapterCapability}` | `probe.${ProbeCapability}` | `provider.${EvidenceProviderCapability}` | `terminal.${'writable-pty' | 'input-modes-observable'}` | `session.${SessionCapabilityId}` | `runtime.${RuntimePrerequisiteId}` | `strategy.${'pointer-target' | 'keyboard-activate' | 'pointer-activate' | 'focus-by-pointer' | 'type-focused'}` | `public.${PublicCapabilityConsumer}` | `diagnostic.${'semantic-tree' | 'geometry' | 'render-order' | 'logs'}`;
+interface CapabilityRemediation {
+    readonly code: 'select-certified-adapter' | 'register-application-provider' | 'enable-terminal-runtime' | 'wait-for-committed-observation' | 'no-authoritative-producer';
+    readonly message: string;
+    readonly providerType?: EvidenceProviderType;
+    readonly runtimePrerequisite?: RuntimePrerequisiteId;
+}
+interface CapabilityGraphNode {
+    readonly id: CapabilityNodeId;
+    readonly category: CapabilityNodeCategory;
+    readonly layer: CapabilityNodeLayer;
+    readonly description: string;
+    readonly conformanceClaims?: readonly CapabilityConformanceClaimId[];
+    readonly conditions?: readonly ConditionKind[];
+    readonly publicConsumer?: PublicCapabilityConsumer;
+    readonly remediation: CapabilityRemediation;
+}
+interface CapabilityGraphEdge {
+    readonly from: CapabilityNodeId;
+    readonly to: CapabilityNodeId;
+    readonly kind: CapabilityEdgeKind;
+}
+declare const CAPABILITY_GRAPH: Readonly<{
+    version: 5;
+    nodes: CapabilityGraphNode[];
+    edges: readonly CapabilityGraphEdge[];
+}>;
+interface CapabilityGraphValidationResult {
+    readonly ok: boolean;
+    readonly errors: readonly string[];
+}
+/** Mechanical integrity gate used by protocol and registry tests. */
+declare function validateCapabilityGraph(): CapabilityGraphValidationResult;
+declare function capabilityNode(id: CapabilityNodeId): CapabilityGraphNode;
+/** Generated, deterministic remediation for a missing graph node. */
+declare function capabilityRemediation(id: CapabilityNodeId): CapabilityRemediation;
+interface CapabilityResolution {
+    readonly available: boolean;
+    readonly target: CapabilityNodeId;
+    readonly missing: readonly CapabilityNodeId[];
+    readonly remediation: readonly CapabilityRemediation[];
+}
+/**
+ * Resolves the frozen session facts produced by an exact set of negotiated
+ * producer nodes. Only explicit `produces` edges may create a session
+ * capability; similarly named adapter facts never imply extra guarantees.
+ */
+declare function sessionCapabilitiesFromProducers(producers: ReadonlySet<CapabilityNodeId>): ReadonlyMap<SessionCapabilityId, readonly CapabilityNodeId[]>;
+/**
+ * Resolve a strategy or public consumer against one already-negotiated
+ * session/runtime node set. Session nodes are leaves: producer declarations do
+ * not opportunistically unlock them after negotiation.
+ */
+declare function resolveCapability(target: CapabilityNodeId, available: ReadonlySet<CapabilityNodeId>): CapabilityResolution;
+
+export { ADAPTER_CAPABILITIES, type AdapterCapability, CAPABILITY_CONFORMANCE_CLAIMS, CAPABILITY_EDGE_KINDS, CAPABILITY_GRAPH, CAPABILITY_GRAPH_VERSION, CAPABILITY_NODE_CATEGORIES, CAPABILITY_NODE_LAYERS, CONDITION_KINDS, type CapabilityConformanceClaimId, type CapabilityEdgeKind, type CapabilityGraphEdge, type CapabilityGraphNode, type CapabilityGraphValidationResult, type CapabilityNodeCategory, type CapabilityNodeId, type CapabilityNodeLayer, type CapabilityRemediation, type CapabilityResolution, type ConditionKind, EVIDENCE_PROVIDER_CAPABILITIES, EVIDENCE_PROVIDER_TYPES, type EvidenceProviderCapability, type EvidenceProviderType, PROBE_CAPABILITIES, PUBLIC_CAPABILITY_CONSUMERS, type ProbeCapability, type PublicCapabilityConsumer, RUNTIME_PREREQUISITES, type RuntimePrerequisiteId, SESSION_CAPABILITIES, type SessionCapabilityId, capabilityNode, capabilityRemediation, resolveCapability, sessionCapabilitiesFromProducers, validateCapabilityGraph };

package/dist/capability-graph.js

@@ -0,0 +1,43 @@
+import {
+  ADAPTER_CAPABILITIES,
+  CAPABILITY_CONFORMANCE_CLAIMS,
+  CAPABILITY_EDGE_KINDS,
+  CAPABILITY_GRAPH,
+  CAPABILITY_GRAPH_VERSION,
+  CAPABILITY_NODE_CATEGORIES,
+  CAPABILITY_NODE_LAYERS,
+  CONDITION_KINDS,
+  EVIDENCE_PROVIDER_CAPABILITIES,
+  EVIDENCE_PROVIDER_TYPES,
+  PROBE_CAPABILITIES,
+  PUBLIC_CAPABILITY_CONSUMERS,
+  RUNTIME_PREREQUISITES,
+  SESSION_CAPABILITIES,
+  capabilityNode,
+  capabilityRemediation,
+  resolveCapability,
+  sessionCapabilitiesFromProducers,
+  validateCapabilityGraph
+} from "./chunk-VBLS6E6U.js";
+export {
+  ADAPTER_CAPABILITIES,
+  CAPABILITY_CONFORMANCE_CLAIMS,
+  CAPABILITY_EDGE_KINDS,
+  CAPABILITY_GRAPH,
+  CAPABILITY_GRAPH_VERSION,
+  CAPABILITY_NODE_CATEGORIES,
+  CAPABILITY_NODE_LAYERS,
+  CONDITION_KINDS,
+  EVIDENCE_PROVIDER_CAPABILITIES,
+  EVIDENCE_PROVIDER_TYPES,
+  PROBE_CAPABILITIES,
+  PUBLIC_CAPABILITY_CONSUMERS,
+  RUNTIME_PREREQUISITES,
+  SESSION_CAPABILITIES,
+  capabilityNode,
+  capabilityRemediation,
+  resolveCapability,
+  sessionCapabilitiesFromProducers,
+  validateCapabilityGraph
+};
+//# sourceMappingURL=capability-graph.js.map

package/dist/capability-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/chunk-B4VUTTUE.js

@@ -0,0 +1,59 @@
+import {
+  SESSION_CAPABILITIES
+} from "./chunk-VBLS6E6U.js";
+
+// src/probe/ir.ts
+var PROBE_UNOBSERVABLE_FIELDS = [
+  "focused",
+  "disabled",
+  "checked",
+  "expanded",
+  "readonly",
+  "selected",
+  "busy",
+  "multiline",
+  "required",
+  "multiselectable",
+  "displayed",
+  "value",
+  "selectedIndex",
+  "textSelection",
+  "scroll",
+  "scrollExtent",
+  "intendedRect",
+  "visibleRect",
+  "paintOrder",
+  "text",
+  "parent"
+];
+var PROBE_INJECTION_TIERS = ["T0", "T1", "T2", "T3"];
+var PROBE_SEMANTIC_CLASSES = ["A", "B"];
+var PROBE_DEGRADED_CAPABILITIES = Object.freeze([
+  ...SESSION_CAPABILITIES,
+  "inactive-screen-tree",
+  "custom-container-enumeration"
+]);
+var PROVENANCE_SOURCES = [
+  "annotation",
+  "recognizer",
+  "framework",
+  "application",
+  "correlation",
+  "heuristic"
+];
+
+// src/contract.ts
+function evidence(source, method, strength, providerId) {
+  if (providerId.trim().length === 0) throw new TypeError("evidence providerId must not be empty");
+  return Object.freeze({ source, method, strength, providerId });
+}
+
+export {
+  PROBE_UNOBSERVABLE_FIELDS,
+  PROBE_INJECTION_TIERS,
+  PROBE_SEMANTIC_CLASSES,
+  PROBE_DEGRADED_CAPABILITIES,
+  PROVENANCE_SOURCES,
+  evidence
+};
+//# sourceMappingURL=chunk-B4VUTTUE.js.map

package/dist/chunk-B4VUTTUE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/probe/ir.ts","../src/contract.ts"],"sourcesContent":["/**\n * Probe IR — what an instrumented process **observed**, not what it means.\n *\n * A probe reports facts; a recognizer turns them into the semantic tree. The\n * split exists because the six frameworks disagree about what is even knowable,\n * and collapsing that disagreement early is how a tree ends up asserting things\n * no framework ever said.\n *\n * Three rules shape every type here, each forced by the Phase 0 audits:\n *\n * 1. **Never fabricate identity.** Immediate-mode frameworks have none, and a\n *    synthesised ordinal presented as a handle is worse than no handle: a test\n *    written against it fails later and looks flaky rather than wrong. Identity\n *    is therefore a typed capability with `frame-local` as a first-class value.\n * 2. **Intent is not ownership.** The rectangle a widget was drawn *into* is not\n *    the cells it ended up owning; later writes win and no framework records\n *    who painted what. The two are separate fields, and only one framework\n *    computes the second.\n * 3. **Absent and unobservable are different facts.** A state a framework does\n *    not expose is not a state that is off. The IR says which is which, rather\n *    than letting `undefined` mean both.\n *\n * Naming note: the words `region` and `area` are avoided throughout. Each\n * carries at least three conflicting meanings across the audited frameworks,\n * and an IR that reuses them inherits every one of those ambiguities.\n */\n\n/**\n * How an object's identity behaves across frames.\n *\n * `frame-local` is a legitimate answer, not a degraded one: in immediate mode\n * the widget is consumed by the render and nothing upstream survives to be\n * named again. A consumer must not correlate `frame-local` values between\n * frames.\n */\nexport type ProbeIdentityKind = 'stable' | 'frame-local';\n\n/** An object's identity, tagged with what it is worth. */\nexport interface ProbeIdentity {\n  readonly kind: ProbeIdentityKind;\n  /** Unique within its frame; unique across the session only when `stable`. */\n  readonly value: string;\n}\n\n/**\n * A rectangle in terminal cells.\n *\n * Deliberately not called a region or an area: `row`/`column` are absolute\n * cell coordinates, and negative origins are legal because a widget may be\n * partly scrolled off.\n */\nexport interface ProbeRect {\n  readonly row: number;\n  readonly column: number;\n  readonly width: number;\n  readonly height: number;\n}\n\n/**\n * Where an object was drawn.\n *\n * `intendedRect` is where it *asked* to draw. It is a statement of intent, not\n * a claim on cells: frameworks do not clip it, do not validate it against the\n * viewport, and a later write silently wins. For overlapping UIs — popups,\n * modals, shadows — it is not where the object ended up.\n *\n * `visibleRect` is the intersection with the clip imposed by ancestors, which\n * is the closest any framework gets to \"what the user can see\". Only one of\n * the six computes it; everywhere else it is absent, and inferring it from\n * `intendedRect` would be inventing a fact.\n */\nexport interface ProbeGeometry {\n  readonly intendedRect?: ProbeRect;\n  readonly visibleRect?: ProbeRect;\n}\n\n/** Scroll position, in cells, of a scrollable object's viewport. */\nexport interface ProbeScroll {\n  readonly row: number;\n  readonly column: number;\n}\n\n/** Total scrollable extent, in cells. Absent where a framework cannot report it. */\nexport interface ProbeExtent {\n  readonly rows: number;\n  readonly columns: number;\n}\n\n/**\n * State a probe read directly from the framework.\n *\n * Every field is optional, and absence means \"not reported by this probe\".\n * A field the framework is *known* not to expose belongs in\n * {@link ProbeObject.unobservable} instead, so a consumer can tell \"off\" from\n * \"unknowable\".\n *\n * The three selection facts have separate names on purpose. An accessibility\n * `selected` flag, a highlighted collection index and a selected text range\n * are not interchangeable, even though frameworks often call all three\n * \"selection\".\n */\nexport interface ProbeObservedState {\n  readonly focused?: boolean;\n  readonly disabled?: boolean;\n  readonly checked?: boolean | 'mixed';\n  readonly expanded?: boolean;\n  readonly readonly?: boolean;\n  readonly selected?: boolean;\n  readonly busy?: boolean;\n  readonly multiline?: boolean;\n  readonly required?: boolean;\n  readonly multiselectable?: boolean;\n  /**\n   * Whether the framework's own display flag is on. Distinct from being\n   * scrolled out of view, which shows up as an empty `visibleRect`.\n   */\n  readonly displayed?: boolean;\n  /** Contents of a value-bearing widget. `''` means empty, not absent. */\n  readonly value?: string;\n  /** Explicit confidentiality classification. Omitted values default sensitive. */\n  readonly valueSensitivity?: 'public' | 'sensitive';\n  /** Highlighted item in a collection, by index. Not a text selection. */\n  readonly selectedIndex?: number;\n  /** Selected text range within this object. Not an item selection. */\n  readonly textSelection?: { readonly start: number; readonly end: number };\n  readonly scroll?: ProbeScroll;\n  readonly scrollExtent?: ProbeExtent;\n}\n\n/** Field names a probe can declare unobservable. */\nexport const PROBE_UNOBSERVABLE_FIELDS = [\n  'focused',\n  'disabled',\n  'checked',\n  'expanded',\n  'readonly',\n  'selected',\n  'busy',\n  'multiline',\n  'required',\n  'multiselectable',\n  'displayed',\n  'value',\n  'selectedIndex',\n  'textSelection',\n  'scroll',\n  'scrollExtent',\n  'intendedRect',\n  'visibleRect',\n  'paintOrder',\n  'text',\n  'parent',\n] as const;\n\nexport type ProbeUnobservableField = (typeof PROBE_UNOBSERVABLE_FIELDS)[number];\n\n/**\n * Author-supplied annotations carried verbatim.\n *\n * The probe does not interpret these — a recognizer does, at the top of the\n * merge precedence. `role` is deliberately a free string here: it is whatever\n * the author wrote, and validating it against the closed role set is the\n * recognizer's job, which can then report a bad annotation instead of silently\n * dropping it.\n */\nexport interface ProbeAccessibilityHints {\n  /** Framework-native accessibility role, in the framework's vocabulary. */\n  readonly role?: string;\n  readonly name?: string;\n  readonly description?: string;\n}\n\nexport interface ProbeAnnotations {\n  readonly role?: string;\n  readonly name?: string;\n  readonly testId?: string;\n  readonly description?: string;\n  /** Application-domain JSON state, kept outside the portable state flags. */\n  readonly extended?: import('../tree.js').SemanticExtendedState;\n  /** Descriptive action intent; never callbacks or a second input channel. */\n  readonly actions?: readonly import('../roles.js').SemanticAction[];\n  /** Production key bindings represented as data, never framework callbacks. */\n  readonly inputRecipes?: readonly import('../roles.js').PhysicalInputRecipe[];\n  /** Probe identity values of author-declared labelling relationships. */\n  readonly labelledBy?: readonly string[];\n  /** Probe identity values of author-declared description relationships. */\n  readonly describedBy?: readonly string[];\n}\n\n/**\n * One object a probe observed in a frame.\n *\n * `frameworkType` is required. It is the framework's own name for the thing —\n * a class name, a constructor name, a widget type — and it is what keeps an\n * unrecognised widget alive as a `generic` node instead of being dropped. Its\n * quality varies enormously (Textual gives a full class ancestry; Ink gives one\n * of four host-element names), so a recognizer must treat it as a hint, not a\n * classification.\n */\nexport interface ProbeObject {\n  readonly identity: ProbeIdentity;\n  readonly frameworkType: string;\n  /** Parent's identity value; absent for a root. */\n  readonly parent?: string;\n  readonly geometry?: ProbeGeometry;\n  readonly state?: ProbeObservedState;\n  /** Text the object itself carries, not its descendants'. */\n  readonly text?: string;\n  /** Accessibility metadata retained by the framework itself, not author SDK data. */\n  readonly accessibility?: ProbeAccessibilityHints;\n  readonly annotations?: ProbeAnnotations;\n  /**\n   * Where this object sits in paint order: higher was painted later, and\n   * therefore on top.\n   *\n   * Available in three of the six frameworks (a compositor hit-test, a z-order\n   * child list, a paint-order key) and absent in the rest. It is the only fact\n   * that makes \"is my target actually the thing at this cell\" answerable\n   * without inventing cell ownership, which no framework records.\n   */\n  readonly paintOrder?: number;\n  /**\n   * Facts this framework cannot report for this object. Distinct from a field\n   * simply being absent, which means the probe did not report it this time.\n   */\n  readonly unobservable?: readonly ProbeUnobservableField[];\n}\n\n/**\n * A render or layout call the probe intercepted.\n *\n * Only some frameworks expose a call stream, and in immediate mode it is the\n * *only* structure that exists — there is no tree to walk, just an ordered list\n * of \"this type was drawn into this rectangle\". `ordinal` is the position in\n * that stream and is meaningful only within its frame.\n */\nexport interface ProbeOperation {\n  readonly kind: 'render' | 'layout';\n  readonly ordinal: number;\n  /** Identity of the object this call concerned, when the probe can attribute it. */\n  readonly target?: ProbeIdentity;\n  readonly frameworkType?: string;\n  readonly intendedRect?: ProbeRect;\n}\n\n/**\n * One observed frame.\n *\n * `objects` may be empty and `operations` may carry everything: that is what an\n * immediate-mode frame looks like, and a flat op list is a legal degenerate\n * tree rather than an error.\n */\nexport interface ProbeFrame {\n  /** Monotonic within the session. Every framework has exactly one of these. */\n  readonly frame: number;\n  readonly objects: readonly ProbeObject[];\n  readonly operations?: readonly ProbeOperation[];\n}\n\n/** Optional abilities a probe declares at handshake time. */\nexport { PROBE_CAPABILITIES } from '../capability-graph.js';\nexport type { ProbeCapability } from '../capability-graph.js';\nimport {\n  SESSION_CAPABILITIES,\n  type ProbeCapability,\n  type SessionCapabilityId,\n} from '../capability-graph.js';\n\n/** Injection tiers used by the semantic-probe attachment doctrine. */\nexport const PROBE_INJECTION_TIERS = ['T0', 'T1', 'T2', 'T3'] as const;\nexport type ProbeInjectionTier = (typeof PROBE_INJECTION_TIERS)[number];\n\n/** Semantic class A has geometry; class B deliberately publishes a tree without it. */\nexport const PROBE_SEMANTIC_CLASSES = ['A', 'B'] as const;\nexport type ProbeSemanticClass = (typeof PROBE_SEMANTIC_CLASSES)[number];\n\n/**\n * Named reductions a probe can report even when the broader session\n * capability remains useful. These are deliberately more precise than the\n * capability graph: omitting inactive screens must not disable the live\n * semantic tree, and an opaque custom container must not disable known\n * framework children.\n */\nexport const PROBE_DEGRADED_CAPABILITIES = Object.freeze([\n  ...SESSION_CAPABILITIES,\n  'inactive-screen-tree',\n  'custom-container-enumeration',\n] as const);\nexport type ProbeDegradedCapabilityId =\n  SessionCapabilityId | 'inactive-screen-tree' | 'custom-container-enumeration';\n\n/** Runtime record of the strongest attachment mechanism that actually engaged. */\nexport interface ProbeInstrumentation {\n  readonly highestTier: ProbeInjectionTier;\n  readonly semanticClass: ProbeSemanticClass;\n  readonly degradedCapabilities: readonly ProbeDegradedCapabilityId[];\n}\n\n/**\n * What a probe says about itself when it attaches.\n *\n * @remarks\n * `frame-begin` is optional for a reason that is easy to get wrong. No audited\n * framework offers a hook guaranteed to fire before every frame: one lets a\n * pre-draw hook veto the frame entirely (so the post-draw hook never runs), one\n * exposes only a post-frame hook, and one decouples submission from the flush\n * with a ticker. A consumer must therefore never read \"no frame-begin\" as \"no\n * frame in progress\" — doing so turns four of the six frameworks into a hang\n * rather than an error.\n */\nexport interface ProbeInfo {\n  /** Framework name, e.g. `ink`, `textual`, `ratatui`. */\n  readonly framework: string;\n  readonly frameworkVersion?: string;\n  /** Version of the probe itself, so a mismatch is diagnosable. */\n  readonly probeVersion: string;\n  /** The best identity this probe can offer for any object. */\n  readonly identityKind: ProbeIdentityKind;\n  readonly capabilities: readonly ProbeCapability[];\n  /**\n   * How this concrete run attached and what it could not observe.\n   * Optional on the wire so existing protocol-v2/custom adapters remain valid.\n   */\n  readonly instrumentation?: ProbeInstrumentation;\n}\n\n/**\n * Where a semantic fact came from.\n *\n * Ranked: an annotation is what the author said, a recognizer is what our rules\n * concluded, `framework` is what the framework itself reported, `correlation`\n * is what matching across sources implied, and `heuristic` is a guess that\n * happened to be useful. The merge precedence follows this order, except that\n * physical facts — bounds, focus, visibility, cells — are never casually\n * overridden by an annotation: an author may name a thing, but may not declare\n * where it is on screen.\n */\nexport const PROVENANCE_SOURCES = [\n  'annotation',\n  'recognizer',\n  'framework',\n  'application',\n  'correlation',\n  'heuristic',\n] as const;\n\nexport type ProvenanceSource = (typeof PROVENANCE_SOURCES)[number];\n","export {\n  ADAPTER_CAPABILITIES,\n  EVIDENCE_PROVIDER_CAPABILITIES,\n  SESSION_CAPABILITIES,\n} from './capability-graph.js';\nexport type {\n  AdapterCapability,\n  EvidenceProviderCapability,\n  SessionCapabilityId,\n} from './capability-graph.js';\nexport {\n  PROBE_DEGRADED_CAPABILITIES,\n  PROBE_INJECTION_TIERS,\n  PROBE_SEMANTIC_CLASSES,\n} from './probe/ir.js';\nimport type { EvidenceProviderCapability, SessionCapabilityId } from './capability-graph.js';\nimport type { ProbeInstrumentation } from './probe/ir.js';\n\n/**\n * Stable application provider identity announced in the adapter hello.\n *\n * Providers are collected before hello is sent. The declaration is therefore\n * part of the same immutable negotiation as framework and terminal evidence;\n * there is no late-registration message and no mutable side channel.\n */\nexport interface EvidenceProviderRegistration {\n  readonly id: string;\n  readonly version: string;\n  readonly capabilities: readonly EvidenceProviderCapability[];\n  /** How the application obtains its authoritative production-router facts. */\n  readonly method: 'native' | 'declared';\n}\n\n/** Where a fact originated, how it was obtained, and what consumers may infer. */\nexport interface EvidenceProvenance {\n  readonly source: 'framework' | 'application' | 'terminal' | 'recognizer' | 'driver';\n  readonly method:\n    'native' | 'instrumented' | 'declared' | 'correlated' | 'measured' | 'derived' | 'heuristic';\n  readonly strength: 'authoritative' | 'diagnostic';\n  /** Stable identity of the producer, never a display label. */\n  readonly providerId: string;\n}\n\nexport function evidence(\n  source: EvidenceProvenance['source'],\n  method: EvidenceProvenance['method'],\n  strength: EvidenceProvenance['strength'],\n  providerId: string,\n): EvidenceProvenance {\n  if (providerId.trim().length === 0) throw new TypeError('evidence providerId must not be empty');\n  return Object.freeze({ source, method, strength, providerId });\n}\n\nexport type SessionCapabilityAvailability =\n  | { readonly status: 'supported'; readonly evidence: EvidenceProvenance }\n  | {\n      readonly status: 'unsupported';\n      readonly reason:\n        'not-negotiated' | 'framework-unobservable' | 'terminal-unobservable' | 'provider-required';\n    };\n\nexport type ContractProvider =\n  | {\n      readonly id: string;\n      readonly kind: 'framework' | 'terminal';\n      readonly version: string;\n    }\n  | {\n      readonly id: string;\n      readonly kind: 'application';\n      readonly version: string;\n      readonly method: 'native' | 'declared';\n      readonly capabilities: readonly EvidenceProviderCapability[];\n    };\n\n/**\n * Immutable public contract negotiated once for one session epoch.\n *\n * Runtime state (disabled nodes, clipping, terminal modes currently off) is\n * intentionally absent. Those are actionability observations, not capability.\n */\nexport interface EffectiveSessionContract {\n  readonly contractId: string;\n  readonly sessionId: string;\n  readonly epoch: number;\n  readonly protocol: 'termwright/2';\n  readonly framework: {\n    readonly name: string;\n    readonly version: string;\n    readonly adapterVersion: string;\n    readonly certificationId: string;\n    /** Runtime attachment facts declared by a framework probe, when available. */\n    readonly instrumentation?: ProbeInstrumentation;\n  } | null;\n  readonly providers: readonly ContractProvider[];\n  readonly capabilities: Readonly<Record<SessionCapabilityId, SessionCapabilityAvailability>>;\n  readonly terminal: {\n    readonly profile: string;\n    readonly platform: string;\n    readonly mouseModesObservable: boolean;\n  };\n}\n"],"mappings":";;;;;AAkIO,IAAM,4BAA4B;AAAA,EACvC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAqHO,IAAM,wBAAwB,CAAC,MAAM,MAAM,MAAM,IAAI;AAIrD,IAAM,yBAAyB,CAAC,KAAK,GAAG;AAUxC,IAAM,8BAA8B,OAAO,OAAO;AAAA,EACvD,GAAG;AAAA,EACH;AAAA,EACA;AACF,CAAU;AAkDH,IAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;;;AC7SO,SAAS,SACd,QACA,QACA,UACA,YACoB;AACpB,MAAI,WAAW,KAAK,EAAE,WAAW,EAAG,OAAM,IAAI,UAAU,uCAAuC;AAC/F,SAAO,OAAO,OAAO,EAAE,QAAQ,QAAQ,UAAU,WAAW,CAAC;AAC/D;","names":[]}