Add Reference Runtime Spec

Scope

This change graduates ready reference-runtime behavior into a canonical reference-implementation-runtime OpenSpec capability. It covers behavior that is already shipped in runtime/controller/scheduler code and regression tests.

It does not change runtime code, root PDPP protocol semantics, connector implementations, query extraction, dashboard behavior, or fixture scrubbing.

Evidence Inventory

Ready Reference-Runtime Behavior

Behavior	Classification	Evidence
The reference runtime derives START.scope from the manifest when no scope is supplied, validates supplied scopes, rejects wildcards/unresolved views/issuance-time necessity, normalizes requested fields with required, primary-key, and consent-time fields, and advertises network, filesystem, and optionally interactive bindings.	Reference-specific implementation of root Collection Profile handoff rules.	reference-implementation/runtime/index.js:51, reference-implementation/runtime/index.js:441; reference-implementation/test/collection-profile.test.js:324, reference-implementation/test/collection-profile.test.js:956, reference-implementation/test/collection-profile.test.js:1891, reference-implementation/test/collection-profile.test.js:1926, reference-implementation/test/collection-profile.test.js:1971; openspec/changes/add-polyfill-connector-system/tasks.md:87.
Connector stdout is consumed as newline-delimited UTF-8 split only on ASCII LF, and optional PDPP_TRACE_DIR captures raw connector lines for debugging.	Reference-specific runtime robustness and diagnostics.	reference-implementation/runtime/index.js:832; openspec/changes/add-polyfill-connector-system/design-notes/gmail-jsonl-truncation-bug.md; packages/polyfill-connectors/src/connector-runtime.ts:317.
RECORD, STATE, PROGRESS, SKIP_RESULT, INTERACTION, and DONE messages are validated against the active scope and run state; protocol violations fail the run and surface structured run failure metadata.	Reference-specific enforcement of root wire semantics.	reference-implementation/runtime/index.js:525, reference-implementation/runtime/index.js:559, reference-implementation/runtime/index.js:633, reference-implementation/runtime/index.js:648, reference-implementation/runtime/index.js:684, reference-implementation/runtime/index.js:1275, reference-implementation/runtime/index.js:1314, reference-implementation/runtime/index.js:1343, reference-implementation/runtime/index.js:1454, reference-implementation/runtime/index.js:1488, reference-implementation/test/collection-profile.test.js:2319, reference-implementation/test/collection-profile.test.js:2725, reference-implementation/test/collection-profile.test.js:3903, reference-implementation/test/scheduler.test.js:933.
Checkpointed streaming flushes records before state staging, commits staged state only after successful terminal validation when persistState is enabled, reports checkpoint_summary, and reports partial/not-committed checkpoints as known gaps.	Reference-specific runtime persistence and observability.	reference-implementation/runtime/index.js:1013, reference-implementation/runtime/index.js:1072, reference-implementation/runtime/index.js:1314, reference-implementation/runtime/index.js:1668, reference-implementation/test/scheduler.test.js:89, reference-implementation/test/scheduler.test.js:281, reference-implementation/test/scheduler.test.js:482, reference-implementation/test/scheduler.test.js:803.
Interaction handling parks the live child process, records run.interaction_required and run.interaction_completed, writes only status/kind/stream metadata to the durable timeline, rejects connector output while awaiting the response, and fails invalid handler responses.	Reference-specific in-process pause/resume primitive; not full restart-from-checkpoint.	reference-implementation/runtime/index.js:1343, reference-implementation/test/collection-profile.test.js:2109, reference-implementation/test/collection-profile.test.js:2725, reference-implementation/test/collection-profile.test.js:2853, reference-implementation/test/collection-profile.test.js:3211, reference-implementation/test/collection-profile.test.js:3472, reference-implementation/test/collection-profile.test.js:3613; openspec/changes/add-polyfill-connector-system/design.md:22.
The owner control plane brokers interaction responses by run_id and current interaction_id, rejects stale/no-pending/unknown interactions, and does not persist submitted secrets into run timeline events.	Reference-specific operator surface over the runtime.	reference-implementation/runtime/controller.ts:245, reference-implementation/runtime/controller.ts:868, reference-implementation/runtime/controller.ts:904, reference-implementation/test/run-interaction-control.test.js:224, reference-implementation/test/run-interaction-control.test.js:254, reference-implementation/test/run-interaction-control.test.js:278, reference-implementation/test/run-interaction-control.test.js:310, reference-implementation/test/run-interaction-control.test.js:323, reference-implementation/test/run-interaction-control.test.js:424.
Scheduler records run history/stats, forwards run identifiers, checkpoint summaries, connector terminal errors, and known gaps, prevents overlapping runs per connector, retries retryable failures with bounded exponential backoff, does not retry deterministic failures, treats single_use grants as non-persistent and consumed only after success, and emits one disabled skip after deterministic grant lifecycle failures.	Reference-specific orchestration policy.	reference-implementation/runtime/scheduler.ts:176, reference-implementation/runtime/scheduler.ts:247, reference-implementation/runtime/scheduler.ts:272, reference-implementation/runtime/scheduler.ts:457, reference-implementation/runtime/scheduler.ts:499, reference-implementation/runtime/scheduler.ts:591; reference-implementation/test/scheduler.test.js:1027, reference-implementation/test/scheduler.test.js:1143, reference-implementation/test/scheduler.test.js:1242, reference-implementation/test/scheduler.test.js:1511, reference-implementation/test/scheduler.test.js:1642, reference-implementation/test/scheduler.test.js:1771, reference-implementation/test/scheduler.test.js:1896, reference-implementation/test/scheduler.test.js:1978, reference-implementation/test/scheduler.test.js:2053, reference-implementation/test/scheduler.test.js:2309.
The controller resolves default connector paths using manifest fingerprints when reference fixture and polyfill manifests share a connector_id, prefers runnable polyfill implementations for matching polyfill manifests, persists controller-managed active runs, reconciles abandoned active runs on startup, and exposes schedule lifecycle endpoints.	Reference-specific local controller behavior.	reference-implementation/runtime/controller.ts:270, reference-implementation/runtime/controller.ts:399, reference-implementation/runtime/controller.ts:567, reference-implementation/runtime/controller.ts:654, reference-implementation/runtime/controller.ts:778; reference-implementation/test/connector-path-resolution.test.js:64, reference-implementation/test/connector-path-resolution.test.js:96, reference-implementation/test/control-actions.test.js:264, reference-implementation/test/control-actions.test.js:451, reference-implementation/test/control-actions.test.js:496, reference-implementation/test/control-actions.test.js:613.
Polyfill connector helpers provide shared connector-side runtime plumbing: auth resolution via env credentials and INTERACTION kind=credentials, browser context acquisition, session probing/repair, flushAndExit, record filtering, shape-check SKIP_RESULT, tombstone emission, fixture capture, and Playwright tracing.	Connector-authoring/runtime helper behavior; reference-specific unless later promoted to root profile guidance.	packages/polyfill-connectors/src/connector-runtime.ts:20, packages/polyfill-connectors/src/connector-runtime.ts:300, packages/polyfill-connectors/src/connector-runtime.ts:317, packages/polyfill-connectors/src/connector-runtime.ts:342, packages/polyfill-connectors/src/connector-runtime.ts:473, packages/polyfill-connectors/src/connector-runtime.ts:509, packages/polyfill-connectors/src/connector-runtime.ts:608, packages/polyfill-connectors/src/connector-runtime.ts:643, packages/polyfill-connectors/src/connector-runtime.ts:682, packages/polyfill-connectors/src/auth.ts:121, packages/polyfill-connectors/src/auth.ts:157; openspec/changes/add-polyfill-connector-system/specs/polyfill-runtime/spec.md.
Browser-backed connectors acquire per-connector isolated patchright profiles under ~/.pdpp/profiles/<name>/ and emit optional ntfy notifications from connector tooling.	Reference-specific operator/runtime integration.	packages/polyfill-connectors/src/browser-launch.ts, packages/polyfill-connectors/src/connector-runtime.ts:608, packages/polyfill-connectors/src/interaction-handler.ts:13, packages/polyfill-connectors/src/ntfy.ts:2, docs/local-testing-e2e.md:72; openspec/changes/retire-browser-daemon.

Not Ready To Graduate

• INTERACTION kind=missing_credentials is named in APCS task history, but shipped runtime validation currently accepts credentials, otp, and manual_action. The ready behavior is credential prompting via kind: "credentials".
• Full restart-from-checkpoint after a parked interaction process dies is explicitly deferred; the shipped primitive is an in-process park while the child remains alive.
• A persisted inbox module and reference-server inbox routes remain incomplete in APCS.
• Nightly ntfy status summaries remain unsettled/manual.
• Root PDPP Collection Profile semantics for tombstones, SKIP_RESULT, credential prompting, browser binding vocabulary, external tools, blob hydration, identity graph, and partial-run honesty remain candidates rather than settled root requirements.

Classification

Reference-specific commitments in this change:

• Local Node child-process runtime behavior, stdout parsing, trace files, runtime-authored spine events, checkpoint commit status, scheduler retry/skip policy, controller active-run reconciliation, connector-path fingerprinting, schedule lifecycle, per-connector isolated browser profile directories, ntfy integration, and connector helper APIs.

Root PDPP Collection Profile candidates, left non-normative here:

• Portable semantics for SKIP_RESULT, tombstones, credential prompting, browser and filesystem binding vocabulary, external-tool declaration, partial-run honesty, restartable interaction resume, and profile-level notification/inbox behavior.

Decisions

• The canonical spec delta will define only behavior already shipped and tested in the reference implementation.
• Runtime requirements will say when behavior is reference-specific instead of asserting that all PDPP runtimes must behave the same way.
• APCS-only connector-authoring helper behavior will be mentioned only where it affects reference runtime contracts.
• Inbox persistence, notification summaries, and root Collection Profile promotions stay explicit open questions.

Acceptance Checks

• openspec validate add-reference-runtime-spec --strict
• openspec validate --all --strict