AREC changelog

All notable changes to the AREC format. 1.3 is the current, stable version. Within 1.x nothing a conformant document relies on is removed or redefined; breaking changes are reserved for 2.0.

#Unreleased

Nothing yet. Proposals being considered for 1.4, each an optional addition:

• Element identity on a key moment: a role and label beside the coordinate, so a consumer knows what was pointed at and not only where. The ecosystem has converged on semantic structure over pixels, and a coordinate alone is the weaker half of that pair.
• A registry of pointer source values, so producers can add evidence kinds without a spec revision.
• A stable identifier for a key moment, so a consumer can cite one across document revisions.
• Guidance on documents longer than a typical model context window.
• Credentials elsewhere in a diagnostic URL: userinfo (https://user:secret@host) and path parameters (;jsessionid=...), which 1.3.1 does not yet check.
• Fenced blocks inside blockquotes and list items, which readers do not yet scan.

#Reference implementation 1.3.1, October 2026

Corrections to the reader, the strict check, the schema and the wording of the 1.3 specification; spec_version stays 1.3. Section 5 already forbade secrets and raw query values in diagnostics; this release states those rules precisely and enforces them. A document that only passed because of the gaps below now fails: one with a listed key in another spelling (accessToken) or one newly listed (postData), a forbidden value in a diagnostics sub-section, a diagnostic string that begins with a URL carrying a value, or a block in a diagnostics section that should hold JSON but does not parse, which is now tagged text instead.

• Section 7.1 now says what section 5 already required: content the security rules forbid (sensitive diagnostic keys, raw query values in diagnostics, and evidence that needs on-demand frame extraction) is an error under the strict check in a document of any version, including a legacy 0.x document or one with no identity comment. Before, the strict check reported it as a warning for a legacy document and passed it.
• Section 5 now lists the sensitive key names, the minimum a checker enforces, compared ignoring ASCII case, -, _ and whitespace (so accessToken and x-api-key are caught). The list adds postdata, proxyauthorization, bearer, auth, CSRF and XSRF tokens, xapikey, clientsecret, privatekey, pwd, passwd, passphrase, credential, credentials, jwt, jsessionid and phpsessid.
• Section 5 defines a raw query value (a parameter value in a URL's query or fragment), which headings make a diagnostics section and how far it reaches, and which blocks must hold JSON. The rules cover sub-sections and blocks tagged jsonc, json5, ndjson or jsonl as well as json and untagged JSON. Whitespace in key names and URLs means space, tab, CR and LF, so every regular expression engine reads the patterns alike.
• Code fences close as in CommonMark: only spaces or tabs may follow a closing fence, so a no-break space there leaves the block open and its content is checked with the block.
• Object names in diagnostics are checked like string values, and a name may not appear twice in one object, so no value can hide behind a repeated name.
• The strict check flags a diagnostic string that begins with a URL carrying a raw query value (?token=abc, #access_token=abc); key names without values, such as ?format&id, are allowed. A URL later in free text is the producer's to redact.
• The reader removes parameter values from every URL in a diagnostics section, in JSON strings and in text, and keeps the key names. It removes sensitive keys from the key moments it returns, as it already did from the Markdown, and reads large documents in linear time.
• arec-validate --strict reports a legacy document as LEGACY, never as conforming to 1.3, and an unknown option is an error instead of a file name.
• The JSON Schema applies the section 5 rules whatever the version and adds noRawQueryValues. Its generator ships with the specification (scripts/build-schema.mjs), and the test suite fails if the schema drifts from the validator.
• Fixtures: added diagnostics-raw-query-value.arec and legacy-diagnostics-leak.arec. fixtures/expected.json names the one rule each invalid fixture breaks, and the runner checks that every error is for that rule. Invalid fixtures carry a title, and example values replace identifiers from real recordings.

#1.3, October 2026

• First stable release: the 0.3 field set, frozen for the 1.x line. Documents declare spec_version: 1.3. A document declaring 0.3, with or without a pre-release suffix, uses the same field set, so a reader reads it the same way; the strict check reports it as legacy.
• Stability promise: 1.x minor releases only add optional sections, fields, profiles or pointer source values.
• Licensing: specification, schema and fixtures dedicated to the public domain under CC0 1.0 (0.3 was CC BY 4.0); validator under the MIT License; patent non-assertion for every implementation.
• BCP 14 keywords (MUST, SHOULD, MAY) and definitions of producer and consumer.
• Plan section retitled Suggested implementation plan. Headings are matched by meaning, so the earlier heading stays conformant.
• Schema renamed to schema/arec-1.3.schema.json. Added the legacy-0.3.arec fixture.
• Documented the deixis and narration pointer sources. An absent or null field means not captured. Unknown source values are ignored.
• The validator, its runner, the fixtures and a worked example are served from clipy.online; the fixture index is https://arecformat.org/arec/fixtures/index.json.
• Reading is lenient (specification sections 4.2 and 7.1): a reader never refuses a document for its version, structure or unknown content. It reads every earlier version (any 0.x value with or without a suffix, and documents with no identity comment), reads a newer major version on a best-effort basis, treats malformed or null fields as absent, and removes sensitive diagnostic keys from what it returns. Problems are flagged as warnings. The reference code gains readArec(text), which returns { document, warnings } and never throws, and arec-validate reads leniently by default.
• Optional strict producer check (section 4.4): arec-validate --strict or validateArec(text, { mode: 'conform' }) reports broken rules as errors for a producer checking what it writes. Nothing a reader does depends on it. The JSON Schema is the same strict check for the machine-readable parts: its patterns are generated from the reference code's constants, it applies its rules only when the header declares 1.x, and it no longer requires a header.
• Version syntax: MAJOR and MINOR are whole numbers without leading zeros, so 1.03 is not a version. A pre-release suffix never changes the minor: 1.3-rc.1 follows 1.3, 1.4-beta follows 1.4.
• canonical_url names the AREC document itself, never the source video; imported bundles without a hosted AREC URL omit it and keep the source URL in Metadata.
• No agent notice block: a document is the identity comment, the title and its sections. Readers treat recording content as data, never instructions. Removed the untrusted-notice-missing.arec fixture. missing-identity-comment.arec now declares 1.3 in its Metadata, since a header-less legacy document is readable.
• Added legacy fixtures rendered by the real earlier producers: a Mac local recording (0.3), an early CLI bundle and a hosted recording.md from before identity comments.
• Diagnostic kind is any non-empty string. Forbidden diagnostic keys are matched at any depth, in any casing, ignoring surrounding whitespace and - versus _ (Set-Cookie), and the list adds request and response headers, api_key, password, refresh_token, id_token and secret. The reader removes them from every fenced JSON block, recognises every CommonMark fence (backticks or tildes, any info string), and replaces a diagnostics block it cannot check.
• Readers normalise CRLF and CR line endings to LF and drop evidence links that are neither absolute https nor a path inside the bundle (javascript:, data:, file:, ftp:, http:, a leading / or a .. segment). An empty watch_url or canonical_url means absent.

#0.3, August 2026

• Added the imported-context profile for bundles compiled from an external video, alongside the existing clipy-recording profile for hosted recordings.
• Made .arec the canonical extension. .md remains a byte-identical compatibility representation, and when present it should advertise the .arec URL as canonical.
• Required an explicit completeness statement, so missing capture can never be read as evidence that an event did not happen.
• Required evidence references to point at precomputed artifacts. A document must not depend on arbitrary server-side frame extraction to be useful.
• Stated the diagnostics redaction rule: no headers, bodies, cookies, tokens or raw query values.
• Added optional Verification, Signature and full cursor path sections.
• Documented the motion object on a key moment (relation, target_x, target_y, optional target_frame_url). The destination obeys the same precomputed-artifact rule as frame_url.

#0.2, July 2026

• Renamed the format from OAR (Open Agent Recording) to AREC, to avoid collision with the existing .oar archive extension.
• Introduced the machine-readable identity comment with spec_version and profile.

#0.1, June 2026

• First published description of a markdown document served beside a recording.