From 4d6d82929d5af122bfc7d46695ccde730ab1fbdf Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Thu, 29 Oct 2026 15:08:45 +0000 Subject: [PATCH 1/2] Prepare Syncables 0.26.0 and proxy 0.4.1 release candidates Consolidate unreleased notes around the final PostgreSQL/CLI implementation and document the reviewed release, production catalog preservation, Heroku rollout and isolated scratch-note trial. Keep publication and deployment gated on the required Opus review; merging the npm version bump will publish automatically. Claude-Session: https://github.com/ontola/atomic-plugins/blob/codex/syncd-keep-release-0-26/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md Codex-Session: https://github.com/ontola/atomic-plugins/blob/codex/syncd-keep-release-0-26/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md --- docs/agents/releases/2026-10-29-syncd-keep.md | 134 +++++++++++++++ integration-proxy/CHANGELOG.md | 15 +- integration-proxy/Cargo.lock | 2 +- integration-proxy/Cargo.toml | 2 +- syncables/README.md | 157 ++++++++++++++++-- syncables/changes/567.added.md | 6 - syncables/changes/567.behaviour.md | 3 - syncables/changes/auth-placement.fixed.md | 8 - syncables/changes/braid-interface.added.md | 6 - .../changes/created-identity-values.fixed.md | 10 -- .../changes/device-approval-link.fixed.md | 6 - syncables/changes/empty-cursor.fixed.md | 5 - .../changes/google-keep-oad.behaviour.md | 5 - syncables/changes/header-name-token.fixed.md | 4 - syncables/changes/live-daemon-trials.added.md | 6 - syncables/changes/mock-idempotency.added.md | 6 - syncables/changes/mock-page-params.fixed.md | 6 - .../changes/node-env-credentials.fixed.md | 7 - .../normal-collection-checkouts.behaviour.md | 5 - .../changes/observation-consistency.other.md | 4 - .../postgres-snapshot-history.behaviour.md | 7 - syncables/changes/snapshot-intent.added.md | 6 - syncables/changes/standalone-daemon.added.md | 7 - .../syncables-stack-explainer.other.md | 4 - .../changes/syncd-explainer-pitch.other.md | 3 - syncables/changes/syncd-interfaces.other.md | 5 - .../changes/syncd-provider-writes.added.md | 7 - .../changes/versioned-atomic-data.other.md | 4 - .../2026-10-29-syncd-release-preparation.md | 48 ++++++ syncables/docs/daemon-writes.md | 2 +- syncables/docs/daemon.md | 2 +- syncables/package-lock.json | 4 +- syncables/package.json | 2 +- 33 files changed, 349 insertions(+), 149 deletions(-) create mode 100644 docs/agents/releases/2026-10-29-syncd-keep.md delete mode 100644 syncables/changes/567.added.md delete mode 100644 syncables/changes/567.behaviour.md delete mode 100644 syncables/changes/auth-placement.fixed.md delete mode 100644 syncables/changes/braid-interface.added.md delete mode 100644 syncables/changes/created-identity-values.fixed.md delete mode 100644 syncables/changes/device-approval-link.fixed.md delete mode 100644 syncables/changes/empty-cursor.fixed.md delete mode 100644 syncables/changes/google-keep-oad.behaviour.md delete mode 100644 syncables/changes/header-name-token.fixed.md delete mode 100644 syncables/changes/live-daemon-trials.added.md delete mode 100644 syncables/changes/mock-idempotency.added.md delete mode 100644 syncables/changes/mock-page-params.fixed.md delete mode 100644 syncables/changes/node-env-credentials.fixed.md delete mode 100644 syncables/changes/normal-collection-checkouts.behaviour.md delete mode 100644 syncables/changes/observation-consistency.other.md delete mode 100644 syncables/changes/postgres-snapshot-history.behaviour.md delete mode 100644 syncables/changes/snapshot-intent.added.md delete mode 100644 syncables/changes/standalone-daemon.added.md delete mode 100644 syncables/changes/syncables-stack-explainer.other.md delete mode 100644 syncables/changes/syncd-explainer-pitch.other.md delete mode 100644 syncables/changes/syncd-interfaces.other.md delete mode 100644 syncables/changes/syncd-provider-writes.added.md delete mode 100644 syncables/changes/versioned-atomic-data.other.md create mode 100644 syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md diff --git a/docs/agents/releases/2026-10-29-syncd-keep.md b/docs/agents/releases/2026-10-29-syncd-keep.md new file mode 100644 index 000000000..173d691a5 --- /dev/null +++ b/docs/agents/releases/2026-10-29-syncd-keep.md @@ -0,0 +1,134 @@ +# SyncD / Keep release candidate and rollout + +Prepared 2026-10-29 from `c968e34417ea37d916a3954121253518e322c339` +(merged two-way implementation PR [#713](https://github.com/ontola/atomic-plugins/pull/713)). +This document is a rollout handoff, not evidence of publication, deployment or a +live Google write. Follow [Q-105 and the release recipe](../proxy-release.md): +merged, Opus-reviewed, green `main`; Heroku rollout through the coordinator's +worker. The cloud worker has GitHub access but no Opus or Heroku credentials. + +## Review and release + +Candidates: **syncables 0.26.0** and **atomic-integration-proxy 0.4.1**. +Both previous registry versions were checked as 0.25.0 and 0.4.0 respectively. +The npm release includes all changes since published commit +`5506b2ce3c1d57269ff325fe20b31edaded0efe9`, not only Keep. Review its migration +notes, especially the PostgreSQL history migration and optional inbox body. +The proxy release includes the existing unreleased key-transfer, tier-pacing +and webhook changes; check the rolling-deploy/downgrade notes in its changelog. + +1. Obtain an Opus review of the implementation/release diffs and resolve findings. + Review the destructive replacement path, create uncertainty, durable receipt + boundary, credential isolation, schema projection, disabled defaults and + refresh-scope behavior. Existing green CI is test evidence, not that review. +2. Merge the release PR only after review and all exact-head checks pass. + **Merging its package.json bump triggers npm publication automatically.** + Verify `Syncables publish to npm` succeeds and registry metadata identifies + version 0.26.0 and the reviewed source. Do not manually republish that version. +3. On the reviewed release merge commit, create and push + `integration-proxy-v0.4.1` as the recipe specifies. Verify its OIDC publication + workflow and the registry version/checksum before changing the wrapper. +4. In `localthought/integration-proxy`, update the exact dependency from + `=0.4.0` to `=0.4.1`, then `cargo update -p atomic-integration-proxy --precise + 0.4.1`. Keep the actual registry-generated checksum and source in Cargo.lock; + do not substitute a path/git dependency or invent an unpublished checksum. + Run that repository's fmt/Clippy/release-build checks and open its wrapper PR. +5. The coordinator worker merges/deploys the reviewed wrapper, verifies the + Heroku release's commit/version, `/healthz`, logs and device discovery. + Discovery must offer `proxy:write`. Existing tokens retain their read grants; + new write authority requires fresh owner approval. Report crate/npm/Heroku + versions on #227. No owner/provider secret is copied to the cloud worker. + +## Preserve the production catalog + +The new source default has ten entries: its prior nine plus Keep. The live +service has historically used explicit catalogs containing additional platforms. +**Do not replace that selection with the ten-entry default or unset +CATALOG_PATH without comparing the current live selection.** + +Before rollout, the Heroku worker records only the non-secret current catalog +URL and `/catalog`'s public platform names/profile selections, and the current +release id for rollback. It must preserve every non-Keep production entry, +including OAD pins, overlay order and selection, unchanged. If production uses +a different catalog, create a new immutable catalog derived from that actual +selection and replace/add only Keep with this reviewed entry: + +- source candidate: `overlays/catalog/2026-10-29-google-keep-writes.json`; +- OAD pin: `5ccf0e09eef66d45b43e97dfc364233b2707689c`; +- auth + pagination overlays for that pin; +- CRUD overlay `crud-causality-v2-5ccf0e09eef66d45b43e97dfc364233b2707689c-overlay.yaml`; +- selection: `authenticationProfile: googleKeep`. + +Require an exact comparison showing that all other production entries are +unchanged, composition/allowlist validation, merged green publication and +`Overlays published` before selecting that catalog. The new source candidate's +Pages bytes were verified after #713; that does not prove it matches the live +service's current selection. A catalog update alone does not enable writes. +Preserve the current owner hub, OAuth credentials, registered public clients +and trusted-proxy settings. Never dump Heroku configuration or credentials. + +## Isolated live scratch-note trial + +After deployment and package verification, the laptop worker/user runs the +trial with their existing local approval bridge and actual approved Keep +connection. Use a dedicated empty **local PostgreSQL database**, a private +configuration/data directory, and a copy of the exact composed Keep document. +The config's owner, issuer, client id and connection come from the existing +local setup, not invented credentials or values copied into a GitHub comment. +No production notes are selected for editing/deletion. + +1. Set the dedicated database URL in `SYNCABLES_DATABASE_URL`; keep it out of + logs and source. Configure one Keep collection and add + `"writes": {"enabled": true, "allowReplacement": true}`. + Verify `syncables edits --collection ALIAS --config FILE` is empty. + Aliases alone do not isolate queues: scopes can be shared, hence the separate + database. `send` drains that collection's queued edits. +2. Use `send --interactive` for each write batch and `sync --interactive` for + each pull, approving only this connection in the owner hub. These foreground + grants stay in memory and leave the existing shared Keychain session alone; + each process requires its own approval. A persistent `login --write` can + replace the stored connection selection used by other daemon processes and + is deliberately not part of this isolated trial. The owner key remains on + the laptop and OAuth credentials at the proxy. Approve no unrelated connection + or administrative access. +3. Write a new JSON input file with a unique trial marker in its title and + invented checklist items, including a parent and child. Queue `create` with + `--edit-id UUID`; run `send --interactive`. Record the edit UUID, confirmed returned + `created_id`, revision and status, without tokens or other notes' contents. +4. Run `sync --interactive` and retain the returned revision. Verify only the scratch note's + content through local `browse`; the API read can archive the whole account + even if display filtering selects its marker. Keep that archive private. +5. Change the scratch title and uncheck the child, then queue + `edit CREATED_ID --at REVISION --input FILE --owned` with the same collection + and config. `--owned` attests ownership of the note this trial just created. + Send once with `--interactive`, inspect the receipt, then pull with + `--interactive` and verify the new id/content. + Confirm the original scratch id is absent. Never use a pre-existing note id. +6. Queue `delete NEW_SCRATCH_ID --at NEW_REVISION`, send and pull with + `--interactive`, and verify + the scratch note is absent. This permanently deletes only the disposable + note created by this trial. Preserve the local receipt/history for diagnosis. +7. If create is uncertain, **stop**: do not create another note, reset the + database or discard its receipt. Identify the created scratch note and use + `adopt-edit` only after verification. If a partial replacement conflicts, + retain both and resolve explicitly with `keep-both`; never delete by title. + See [provider write recovery](../../../syncables/docs/daemon-writes.md). + +Record trial evidence as operation/status/counts and redacted local result ids; +no credential values, live account dump or private note text. A successful +synthetic trial does not substitute for this Google/laptop verification. + +## Rollback and completion + +Disable collection writes and stop explicit sends first. Keep queued edits, +uncertain states, replacement receipts and accepted history intact. Restoring a +prior service/catalog release does not undo Google creates/deletes. A proxy +binary predating key-transfer support can re-admit retired agents; do not treat +an arbitrary old-version downgrade as a safe rollback. Use the recorded previous +reviewed release only after evaluating those changelog constraints. + +Complete when registry publications, the actual Heroku release and preserved +production catalog are verified, and the isolated Google create/replace/delete +trial has recorded results. The remaining blockers are the required Opus review, +Heroku-worker access and local owner approval/Keep connection, not another +product authorization decision. diff --git a/integration-proxy/CHANGELOG.md b/integration-proxy/CHANGELOG.md index 4d0a3065d..3f7ecdca1 100644 --- a/integration-proxy/CHANGELOG.md +++ b/integration-proxy/CHANGELOG.md @@ -3,7 +3,20 @@ Releases of the `atomic-integration-proxy` crate. Earlier releases are described in the README ("Deploying 0.2", and the "0.2.1 and later" notes). -## Unreleased +## 0.4.1 (2026-10-29) + +- Device sessions support an independently approved `proxy:write` scope for + POST, PUT, PATCH and DELETE on explicitly selected connections. Existing + sessions and default logins remain read-only; write scope does not imply + read or connection-management authority. Catalog restrictions, provider + credentials, ownership, access policy and pacing still apply. Owner + approval names permanent deletion, and token refresh cannot widen scope. +- The source-default catalog adds Google Keep to its previous nine entries, + with the refreshed full OAD and immutable auth, pagination and CRUD overlays. + Resource-name path encoding and explicit checkbox defaults support SyncD's + replacement sender. Keep has no update endpoint. An explicit `CATALOG_PATH` + remains authoritative; deployment must preserve every existing production + catalog selection when updating Keep. - Webhook inbox (`WEBHOOKS_ENABLED`, off by default): `GET /subscriptions/{id}/events` takes `maxBytes` (Webhook Subscriptions diff --git a/integration-proxy/Cargo.lock b/integration-proxy/Cargo.lock index 48d957e05..7ed7558d9 100644 --- a/integration-proxy/Cargo.lock +++ b/integration-proxy/Cargo.lock @@ -59,7 +59,7 @@ dependencies = [ [[package]] name = "atomic-integration-proxy" -version = "0.4.0" +version = "0.4.1" dependencies = [ "axum", "axum-extra", diff --git a/integration-proxy/Cargo.toml b/integration-proxy/Cargo.toml index 7f18e2d86..72b7807b0 100644 --- a/integration-proxy/Cargo.toml +++ b/integration-proxy/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "atomic-integration-proxy" -version = "0.4.0" +version = "0.4.1" edition = "2021" description = "OAuth/catalog integration proxy (pinned OpenAPI catalog, connections owned by Atomic agents, Atomic v2 request signatures, delegations and frame capabilities) used by Atomic Server and LocalThought" license = "MIT" diff --git a/syncables/README.md b/syncables/README.md index 901588d50..5bd89a7f3 100644 --- a/syncables/README.md +++ b/syncables/README.md @@ -2216,17 +2216,152 @@ Not verified against a real provider: no overlay declares `x-produces` yet. ## Changelog -- **Unreleased**: the webhook inbox consumer speaks Webhook Subscriptions - 0.2.0-draft's `maxBytes` (ontola/atomic-plugins#369, step 4b plan Unit - B). `InboxClient.events()` takes `maxBytes` and refuses one that is not - an integer of at least 1 (`RangeError`), and `InboxConsumerOptions` - passes `maxBytes` to every fetch. An event whose body alone is over it - reaches the journal with `payload.omitted: true` and no `body`, and is - acknowledged like any other; `scopedReads` names no reads for it. - **Breaking for TypeScript:** `InboxEvent.payload.body` is now optional - (`body?: string`), so code that reads it must handle its absence; a - receiver sends no omitted event unless the consumer asked for - `maxBytes`. +- **0.26.0**: Experimental SyncD with PostgreSQL history, offline browsing, Git import/export, read-only Braid and explicit provider writes; check migration and API changes before upgrading. + - **Behaviour change:** The supported Node range is now 22.11 or newer, with CI on Node 22, 24 and 26; + the inherited Node 22-only upper limit is removed. Volta still defaults to + Node 22 for development. + - **Behaviour change:** The Google Keep daemon example uses the full pinned Keep v1 OAD and the + proxy catalog's auth, pagination and CRUD overlays. Reads remain the default; + provider writes require separate approval, collection opt-in and explicit + sending. Replacing an existing private example changes its document hash + and starts a new collection scope; previous snapshot history is retained + under the old scope rather than migrated automatically. + - **Behaviour change:** Syncs maintain ordinary snapshot folders per collection under + `workspaceDirectory` (default `./workspace`). Local edits block automatic + updates instead of being overwritten, and never trigger provider writes. + Existing snapshots can be exposed offline with `syncables checkout`; source + classes and schemas are added while preserving original history and payloads. + - **Behaviour change:** Local daemon snapshots, schemas, messages and revision heads now live in + PostgreSQL, sharing content-addressed JSON nodes with the response archive. + Existing Git installations must run `syncables migrate git --config FILE` + before continuing. Original archives and worktrees remain untouched; ordinary + snapshot folders use `workspaceDirectory` (default `./workspace`). Use + `syncables export git --subtree platform/account/collection --output NEW_DIR` + for checked-out Git history, including branches, tags and commit metadata. + - **Behaviour change:** the webhook inbox consumer speaks Webhook Subscriptions + 0.2.0-draft's `maxBytes` (ontola/atomic-plugins#369, step 4b plan Unit + B). `InboxClient.events()` takes `maxBytes` and refuses one that is not + an integer of at least 1 (`RangeError`), and `InboxConsumerOptions` + passes `maxBytes` to every fetch. An event whose body alone is over it + reaches the journal with `payload.omitted: true` and no `body`, and is + acknowledged like any other; `scopedReads` names no reads for it. + **Breaking for TypeScript:** `InboxEvent.payload.body` is now optional + (`body?: string`), so code that reads it must handle its absence; a + receiver sends no omitted event unless the consumer asked for + `maxBytes`. + - **Added:** The optional `syncables` CLI tests device login and provider access through + Local Thought, saves replication destination definitions, and records reads + in a separate local PostgreSQL archive. The `syncables/postgres` entry + provides owner-scoped compressed payloads, caching and offline recorded-run + replay. Runtime replication and background service installation remain + unimplemented. Existing Node and browser library imports are unchanged. + - **Added:** SyncD can serve selected PostgreSQL snapshots with the new local-only braid + command: authenticated versioned GETs, read-only Braid subscriptions, bounded + replay after reconnect and explicit full-snapshot reset. JSON-AD records and + bundled schemas travel as text to preserve numeric lexemes. The listener is + independent of provider login, Git export and the Atomic adapter; writes and + patches are not supported. See docs/braid.md for commands and limits. + - **Added:** The standalone daemon guide names the exact config and OpenAPI files to + copy, recommends a private data directory outside the source checkout, and + shows real GitHub configuration and connection discovery. The full Google + Keep profile and trial instructions cover provider setup prerequisites, + pagination, account-wide response archival, local title filtering and revision + history. Explicit provider writes and recovery have a separate guide. No + provider credentials or live note data are included. + - **Added:** The mock server deduplicates creates on a declared `Idempotency-Key` + header parameter: a POST sent again with a key it has seen gets the + record made the first time, and the same key with another body gets a + `422` (bodies compare as JSON with sorted keys, or as text when they are + not JSON). A test runs the client's retry of a create whose response was + lost against it over HTTP, and finds one record at the server. + - **Added:** Standalone sync and daemon commands accept `--message` to record intent in + local PostgreSQL snapshot revisions alongside generated run provenance. + History returns messages, timestamps and parents, supports a pinned `--at` + revision, and accepts `--subject` for resource or schema history while + preserving the revision-ID list. Explicit storage-layer messages retain + intent-only revisions even when their trees are unchanged; Git exports + preserve these messages and ancestry. + - **Added:** Add experimental standalone sync, foreground daemon, local browse/history + and commit/tag resource lookup commands. Archive lossless nested JSON objects + by content hash in local PostgreSQL and version the JSON-AD data copy with its + bundled schemas in PostgreSQL snapshots, with optional Git import/export. + Support configured GET collections, a query-token incremental subset, + durable deduplicated webhook hints, periodic polling and macOS Keychain + device credentials. See `docs/daemon.md` for setup and limits; remote + replication and background service installation remain planned. + - **Added:** SyncD adds explicit, opt-in provider creates, replacements and deletes through + an independently approved device write grant. Local edits and receipts persist + in PostgreSQL; interrupted creates remain uncertain without automatic reposting, + and replacement identities are committed before originals are retired. Google + Keep uses a revised composed profile with resource-name path bindings. See + Provider writes and recovery for configuration, conflict handling, metadata + loss, ownership attestation and the remaining non-atomic deletion race. + - **Fixed:** `apiKeyAuth` takes `cookie` as well as `header` and `query`, the third + place an OpenAPI `apiKey` security scheme can put a key: it adds the + cookie to the request's `cookie` header, keeping the others, and refuses + a cookie name that is not an RFC 6265 token and a key that is not + cookie-octets (a `;` would inject a cookie). It and + `bearerAuth` now replace a header of the same name in any case; before, + a request with `Authorization` or `X-Api-Key` already set was sent with + both that header and the lower-case one the adapter added. + - **Fixed:** A create's identity read from its response (CRUD Causality §4.3.2) must + be a value `resolveReference` would also accept: a nonempty string that + is not `.` or `..`, is not padded with whitespace, and holds no NUL or + lone surrogate, or a safe integer. A numeric string past 2^53 is kept, + as a string. Before, a `Location` of `/pets/..` (or `%2E%2E`) bound the + record to `..`, whose path normalises to another resource; a lone + surrogate made every later update or delete of the record throw + `URIError`; and a body `id` that was an object or a boolean bound it to + `[object Object]` or `true`. Such a create is now unbound, as one + without a usable identity already was. + - **Fixed:** Device login now prints the server's complete verification link with the + matching user code prefilled, and explains continuing to owner approval. + Previously it printed the bare instruction page, which has no code-entry + field. Complete links are checked against the verification endpoint and user + code; servers without a complete link retain the manual-entry flow. The mock + approval page also supports a prefilled code. + - **Fixed:** A read by the last item's cursor (Pagination Schemes `fromLastItem`) + ends with a `PageReadError`, not complete, when that item's cursor value + is an empty string. Before, the client sent `?starting_after=`, and a + provider that answered it with an empty page made the read end as + complete after the items before it. + - **Fixed:** `apiKeyAuth(name)` and `apiKeyAuth(name, 'header')` refuse a header name + that is not an RFC 7230 token (a space, a colon, CR or LF, a non-ASCII + letter) when the adapter is made, as `cookie` placement already refused + such a cookie name. A query parameter name is not restricted. + - **Fixed:** The mock server answers a paginated list's page size, offset, page + number or page token with a `400` when it is not a whole number in range + (a page size of at least 1, a page at least the scheme's `start`). + Before, `limit=0` answered `hasMore` with the same next offset forever, + and a value that is not a number (`limit=abc`, `cursor=abc`) an empty + page that ended a read as if it were complete. + - **Fixed:** The Node entry's `createApiClient` reads `SYNCABLES_*` credentials from + the environment only when an `authenticate` adapter is given; without + one they are ignored, silently. Before, a + `SYNCABLES_API_KEY` or `SYNCABLES_ACCESS_TOKEN` set for something else + made a client without an adapter (a transport that authenticates itself) + refuse to start with "Credentials require an authenticate adapter". + Explicit credentials without an adapter are still refused. + - **Other:** Clarify pagination coverage as an observation of a possibly stale API view, + with mixed snapshots across pages. Explain the limits of repeated identical + reads and the separate append-only, stable-selection and closed-prefix + guarantees needed for stronger cursor-based synchronization. + - **Other:** Add an illustrated whole-stack explainer covering OpenAPI extensions, GitHub + and Keep profiles, authentication, shared JSON storage, versioned snapshots + and contract-derived page coverage. Add a design investigation of ambiguous, + delayed cross-collection matches using bank-transfer examples. + - **Other:** Lead the illustrated stack explainer with SyncD's elevator pitch: a generic + client driven by declarative OpenAPI extensions, running as a daemon that + keeps local versioned data available through Git exports and Braid subscriptions. + - **Other:** Document SyncD as Michiel's shorthand for the standalone Syncables Daemon, + without renaming the syncables package or command. Describe Git and Braid + as implemented experimental interfaces over shared PostgreSQL data/history, + and AtomicSync as a planned adapter. Git import/export and read-only Braid + subscriptions do not imply native Atomic peer replication or writable Braid. + - **Other:** Document Versioned Atomic Data resources, schemas, immutable revisions and + commit/tag lookup over local PostgreSQL history, with optional Git + import/export. Distinguish these versions from native Atomic signed commits + and describe publication and missing-schema behavior. - **0.25.0**: behaviour changes to know before upgrading come first: explicit `x-pagination` entries must have the spec's shape; Throttling `blocked`; auto-detection by response headers and fields; `applyOverlay` diff --git a/syncables/changes/567.added.md b/syncables/changes/567.added.md deleted file mode 100644 index 320f7eaa4..000000000 --- a/syncables/changes/567.added.md +++ /dev/null @@ -1,6 +0,0 @@ -The optional `syncables` CLI tests device login and read-only API access -through Local Thought, saves replication destination definitions, and records -reads in a separate local PostgreSQL archive. The `syncables/postgres` entry -provides owner-scoped compressed payloads, caching and offline recorded-run -replay. Runtime replication, durable outgoing changes and daemon installation -remain unimplemented. Existing Node and browser library imports are unchanged. diff --git a/syncables/changes/567.behaviour.md b/syncables/changes/567.behaviour.md deleted file mode 100644 index d16925093..000000000 --- a/syncables/changes/567.behaviour.md +++ /dev/null @@ -1,3 +0,0 @@ -The supported Node range is now 22.11 or newer, with CI on Node 22, 24 and 26; -the inherited Node 22-only upper limit is removed. Volta still defaults to -Node 22 for development. diff --git a/syncables/changes/auth-placement.fixed.md b/syncables/changes/auth-placement.fixed.md deleted file mode 100644 index 584eac872..000000000 --- a/syncables/changes/auth-placement.fixed.md +++ /dev/null @@ -1,8 +0,0 @@ -`apiKeyAuth` takes `cookie` as well as `header` and `query`, the third -place an OpenAPI `apiKey` security scheme can put a key: it adds the -cookie to the request's `cookie` header, keeping the others, and refuses -a cookie name that is not an RFC 6265 token and a key that is not -cookie-octets (a `;` would inject a cookie). It and -`bearerAuth` now replace a header of the same name in any case; before, -a request with `Authorization` or `X-Api-Key` already set was sent with -both that header and the lower-case one the adapter added. diff --git a/syncables/changes/braid-interface.added.md b/syncables/changes/braid-interface.added.md deleted file mode 100644 index f1334d728..000000000 --- a/syncables/changes/braid-interface.added.md +++ /dev/null @@ -1,6 +0,0 @@ -SyncD can serve selected PostgreSQL snapshots with the new local-only braid -command: authenticated versioned GETs, read-only Braid subscriptions, bounded -replay after reconnect and explicit full-snapshot reset. JSON-AD records and -bundled schemas travel as text to preserve numeric lexemes. The listener is -independent of provider login, Git export and the Atomic adapter; writes and -patches are not supported. See docs/braid.md for commands and limits. diff --git a/syncables/changes/created-identity-values.fixed.md b/syncables/changes/created-identity-values.fixed.md deleted file mode 100644 index b1301183c..000000000 --- a/syncables/changes/created-identity-values.fixed.md +++ /dev/null @@ -1,10 +0,0 @@ -A create's identity read from its response (CRUD Causality §4.3.2) must -be a value `resolveReference` would also accept: a nonempty string that -is not `.` or `..`, is not padded with whitespace, and holds no NUL or -lone surrogate, or a safe integer. A numeric string past 2^53 is kept, -as a string. Before, a `Location` of `/pets/..` (or `%2E%2E`) bound the -record to `..`, whose path normalises to another resource; a lone -surrogate made every later update or delete of the record throw -`URIError`; and a body `id` that was an object or a boolean bound it to -`[object Object]` or `true`. Such a create is now unbound, as one -without a usable identity already was. diff --git a/syncables/changes/device-approval-link.fixed.md b/syncables/changes/device-approval-link.fixed.md deleted file mode 100644 index d1ca4b5c0..000000000 --- a/syncables/changes/device-approval-link.fixed.md +++ /dev/null @@ -1,6 +0,0 @@ -Device login now prints the server's complete verification link with the -matching user code prefilled, and explains continuing to owner approval. -Previously it printed the bare instruction page, which has no code-entry -field. Complete links are checked against the verification endpoint and user -code; servers without a complete link retain the manual-entry flow. The mock -approval page also supports a prefilled code. diff --git a/syncables/changes/empty-cursor.fixed.md b/syncables/changes/empty-cursor.fixed.md deleted file mode 100644 index 9cb264efc..000000000 --- a/syncables/changes/empty-cursor.fixed.md +++ /dev/null @@ -1,5 +0,0 @@ -A read by the last item's cursor (Pagination Schemes `fromLastItem`) -ends with a `PageReadError`, not complete, when that item's cursor value -is an empty string. Before, the client sent `?starting_after=`, and a -provider that answered it with an empty page made the read end as -complete after the items before it. diff --git a/syncables/changes/google-keep-oad.behaviour.md b/syncables/changes/google-keep-oad.behaviour.md deleted file mode 100644 index a96af6e9d..000000000 --- a/syncables/changes/google-keep-oad.behaviour.md +++ /dev/null @@ -1,5 +0,0 @@ -The Google Keep daemon example now uses the full pinned Keep v1 OAD and the -proxy catalog's auth, pagination and CRUD overlays. It remains read-only at -runtime. Replacing an existing private example changes its document hash -and starts a new collection scope; previous snapshot history is retained -under the old scope rather than migrated automatically. diff --git a/syncables/changes/header-name-token.fixed.md b/syncables/changes/header-name-token.fixed.md deleted file mode 100644 index b94dfe936..000000000 --- a/syncables/changes/header-name-token.fixed.md +++ /dev/null @@ -1,4 +0,0 @@ -`apiKeyAuth(name)` and `apiKeyAuth(name, 'header')` refuse a header name -that is not an RFC 7230 token (a space, a colon, CR or LF, a non-ASCII -letter) when the adapter is made, as `cookie` placement already refused -such a cookie name. A query parameter name is not restricted. diff --git a/syncables/changes/live-daemon-trials.added.md b/syncables/changes/live-daemon-trials.added.md deleted file mode 100644 index 94271a400..000000000 --- a/syncables/changes/live-daemon-trials.added.md +++ /dev/null @@ -1,6 +0,0 @@ -The standalone daemon guide now names the exact config and OpenAPI files to -copy, recommends a private data directory outside the source checkout, and -shows real GitHub configuration and connection discovery. A GET-only Google -Keep note profile and trial instructions cover provider setup prerequisites, -pagination, account-wide response archival, local title filtering and revision -history. No provider credentials or live note data are included. diff --git a/syncables/changes/mock-idempotency.added.md b/syncables/changes/mock-idempotency.added.md deleted file mode 100644 index 61e5b8418..000000000 --- a/syncables/changes/mock-idempotency.added.md +++ /dev/null @@ -1,6 +0,0 @@ -The mock server deduplicates creates on a declared `Idempotency-Key` -header parameter: a POST sent again with a key it has seen gets the -record made the first time, and the same key with another body gets a -`422` (bodies compare as JSON with sorted keys, or as text when they are -not JSON). A test runs the client's retry of a create whose response was -lost against it over HTTP, and finds one record at the server. diff --git a/syncables/changes/mock-page-params.fixed.md b/syncables/changes/mock-page-params.fixed.md deleted file mode 100644 index 5d4c26486..000000000 --- a/syncables/changes/mock-page-params.fixed.md +++ /dev/null @@ -1,6 +0,0 @@ -The mock server answers a paginated list's page size, offset, page -number or page token with a `400` when it is not a whole number in range -(a page size of at least 1, a page at least the scheme's `start`). -Before, `limit=0` answered `hasMore` with the same next offset forever, -and a value that is not a number (`limit=abc`, `cursor=abc`) an empty -page that ended a read as if it were complete. diff --git a/syncables/changes/node-env-credentials.fixed.md b/syncables/changes/node-env-credentials.fixed.md deleted file mode 100644 index a0c57d7db..000000000 --- a/syncables/changes/node-env-credentials.fixed.md +++ /dev/null @@ -1,7 +0,0 @@ -The Node entry's `createApiClient` reads `SYNCABLES_*` credentials from -the environment only when an `authenticate` adapter is given; without -one they are ignored, silently. Before, a -`SYNCABLES_API_KEY` or `SYNCABLES_ACCESS_TOKEN` set for something else -made a client without an adapter (a transport that authenticates itself) -refuse to start with "Credentials require an authenticate adapter". -Explicit credentials without an adapter are still refused. diff --git a/syncables/changes/normal-collection-checkouts.behaviour.md b/syncables/changes/normal-collection-checkouts.behaviour.md deleted file mode 100644 index 5930e13e2..000000000 --- a/syncables/changes/normal-collection-checkouts.behaviour.md +++ /dev/null @@ -1,5 +0,0 @@ -Syncs now maintain a normal Git working folder per collection under `data` -beside the private Git archive (configurable with `checkoutDirectory`). Local -edits block automatic updates instead of being overwritten. Existing snapshots -can be exposed offline with `syncables checkout`; it adds API-specific classes -and schemas in a new commit while preserving original history and payloads. diff --git a/syncables/changes/observation-consistency.other.md b/syncables/changes/observation-consistency.other.md deleted file mode 100644 index 3f8756681..000000000 --- a/syncables/changes/observation-consistency.other.md +++ /dev/null @@ -1,4 +0,0 @@ -Clarify pagination coverage as an observation of a possibly stale API view, -with mixed snapshots across pages. Explain the limits of repeated identical -reads and the separate append-only, stable-selection and closed-prefix -guarantees needed for stronger cursor-based synchronization. diff --git a/syncables/changes/postgres-snapshot-history.behaviour.md b/syncables/changes/postgres-snapshot-history.behaviour.md deleted file mode 100644 index 022275c6e..000000000 --- a/syncables/changes/postgres-snapshot-history.behaviour.md +++ /dev/null @@ -1,7 +0,0 @@ -Local daemon snapshots, schemas, messages and revision heads now live in -PostgreSQL, sharing content-addressed JSON nodes with the response archive. -Existing Git installations must run `syncables migrate git --config FILE` -before continuing. Original archives and worktrees remain untouched; ordinary -snapshot folders use `workspaceDirectory` (default `./workspace`). Use -`syncables export git --subtree platform/account/collection --output NEW_DIR` -for checked-out Git history, including branches, tags and commit metadata. diff --git a/syncables/changes/snapshot-intent.added.md b/syncables/changes/snapshot-intent.added.md deleted file mode 100644 index 3a8764998..000000000 --- a/syncables/changes/snapshot-intent.added.md +++ /dev/null @@ -1,6 +0,0 @@ -Standalone sync and daemon commands accept `--message` to record intent in -local Git snapshot commits alongside generated run provenance. History now -returns messages, timestamps and parents, supports a pinned `--at` revision, -and accepts `--subject` for resource or schema history while preserving the -existing revision-ID list. Explicit storage-layer messages retain intent-only -commits even when their trees are unchanged. diff --git a/syncables/changes/standalone-daemon.added.md b/syncables/changes/standalone-daemon.added.md deleted file mode 100644 index 910811436..000000000 --- a/syncables/changes/standalone-daemon.added.md +++ /dev/null @@ -1,7 +0,0 @@ -Add experimental standalone sync, foreground daemon, local browse/history -and commit/tag resource lookup commands. Archive lossless nested JSON objects -by content hash in local PostgreSQL and version the JSON-AD data copy with its -bundled schemas in private Git snapshots. Support configured GET collections, -a query-token incremental subset, durable deduplicated webhook hints, periodic -polling and macOS Keychain device credentials. See `docs/daemon.md` for setup, -limits and pending laptop validation; remote replication remains planned. diff --git a/syncables/changes/syncables-stack-explainer.other.md b/syncables/changes/syncables-stack-explainer.other.md deleted file mode 100644 index 9adc524d7..000000000 --- a/syncables/changes/syncables-stack-explainer.other.md +++ /dev/null @@ -1,4 +0,0 @@ -Add an illustrated whole-stack explainer covering OpenAPI extensions, GitHub -and Keep profiles, authentication, shared JSON storage, versioned snapshots -and contract-derived page coverage. Add a design investigation of ambiguous, -delayed cross-collection matches using bank-transfer examples. diff --git a/syncables/changes/syncd-explainer-pitch.other.md b/syncables/changes/syncd-explainer-pitch.other.md deleted file mode 100644 index 7d4bf58cb..000000000 --- a/syncables/changes/syncd-explainer-pitch.other.md +++ /dev/null @@ -1,3 +0,0 @@ -Lead the illustrated stack explainer with SyncD's elevator pitch: a generic -client driven by declarative OpenAPI extensions, running as a daemon that -keeps local versioned data available through Git exports and Braid subscriptions. diff --git a/syncables/changes/syncd-interfaces.other.md b/syncables/changes/syncd-interfaces.other.md deleted file mode 100644 index 1c6b0a893..000000000 --- a/syncables/changes/syncd-interfaces.other.md +++ /dev/null @@ -1,5 +0,0 @@ -Document SyncD as Michiel's shorthand for the standalone Syncables Daemon, -without renaming the syncables package or command. Describe Git, Braid and -AtomicSync as interfaces over shared PostgreSQL data/history, distinguishing -implemented Git import/export from proposed protocol adapters, and outline -a read-only Braid snapshot/subscription milestone. diff --git a/syncables/changes/syncd-provider-writes.added.md b/syncables/changes/syncd-provider-writes.added.md deleted file mode 100644 index 0a0467ed0..000000000 --- a/syncables/changes/syncd-provider-writes.added.md +++ /dev/null @@ -1,7 +0,0 @@ -SyncD adds explicit, opt-in provider creates, replacements and deletes through -an independently approved device write grant. Local edits and receipts persist -in PostgreSQL; interrupted creates remain uncertain without automatic reposting, -and replacement identities are committed before originals are retired. Google -Keep uses a revised composed profile with resource-name path bindings. See -Provider writes and recovery for configuration, conflict handling, metadata -loss, ownership attestation and the remaining non-atomic deletion race. diff --git a/syncables/changes/versioned-atomic-data.other.md b/syncables/changes/versioned-atomic-data.other.md deleted file mode 100644 index 872090c4d..000000000 --- a/syncables/changes/versioned-atomic-data.other.md +++ /dev/null @@ -1,4 +0,0 @@ -Document the Versioned Atomic Data Git experiment: resources and imported -schemas share snapshots, historical references select a commit or tag, and -local reads pin one commit by default. Distinguish these versions from native -Atomic signed commits and describe publication and missing-schema behavior. diff --git a/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md b/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md new file mode 100644 index 000000000..1a1772f3a --- /dev/null +++ b/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md @@ -0,0 +1,48 @@ +# SyncD / Keep release preparation + +Session: no public chat URL supplied; this repository record is available at +https://github.com/ontola/atomic-plugins/blob/codex/syncd-keep-release-0-26/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md + +Assistant: OpenAI Codex, GPT-6. This is AI-assisted release preparation, not an +Opus review or an assertion of independent human approval. + +## Human request + +After the assistant reported merged two-way SyncD support (#713), with deployment +and a live scratch-note trial still needed, the maintainer said: +“ok please continue”. + +## Assistant work and explanation + +Read the standing release recipe and current environment readiness, checked +registry versions and the Heroku wrapper's exact dependency, and verified the +merged implementation's CI/publication state. Prepared syncables 0.26.0 and +atomic-integration-proxy 0.4.1 release metadata and consolidated the unreleased +notes around the final PostgreSQL/CLI implementation. Existing versioned +artifacts and provider behavior were not changed. + +The release rules require Opus-reviewed, merged, green main, with Heroku work +through the coordinator worker. This cloud worker has no Opus or Heroku access. +Requested that review/rollout through the existing #227 board and prepared a +concrete rollout handoff. No release tag, package publication, auto-publishing +release merge, Heroku change or live Google mutation was performed. + +The handoff explicitly preserves the actual production catalog before updating +Keep: the new ten-entry source default must not silently replace a production +selection containing additional providers. It covers registry-backed wrapper +locking, fresh write approval, a dedicated local trial database to avoid sending +unrelated queued edits, operating only on the returned id of a newly created +scratch note, uncertain-create recovery, and rollback limitations. + +Local candidate validation passed: 1,858 tests in 105 files against a dedicated +PostgreSQL test database, full TypeScript build, lint, formatting, changelog +validation, and the installed 0.26.0 tarball's nested-checklist create/pull/ +replace/pull/delete smoke. Proxy fmt, Clippy with warnings denied and packaging/ +verification of the actual 0.4.1 crate passed with the locked dependency graph. +The release handoff's relative links resolve and the diff is whitespace-clean. +Exact-head hosted CI/review outcomes are recorded in the release PR. The existing +implementation had already passed Node 22/24/26 and the full proxy suite before +this release-only preparation. + +Only invented fixture data is used locally. Credential values and private note +contents are omitted. diff --git a/syncables/docs/daemon-writes.md b/syncables/docs/daemon-writes.md index 121b8a32b..8acfd31ab 100644 --- a/syncables/docs/daemon-writes.md +++ b/syncables/docs/daemon-writes.md @@ -8,7 +8,7 @@ preconditions, compound creates or non-generated added-field derivation. Google webhooks, working folders and Braid remain readers of accepted provider snapshots; changing or deleting a checkout file never sends a provider write. -This source implementation is experimental and unreleased. Tests use invented +This implementation is experimental. Tests use invented providers. Live Google writes, proxy deployment and package publication have not been verified by these tests. diff --git a/syncables/docs/daemon.md b/syncables/docs/daemon.md index ae4882e52..e0f2943e6 100644 --- a/syncables/docs/daemon.md +++ b/syncables/docs/daemon.md @@ -24,7 +24,7 @@ and AtomicSync peer are separate work. See the [three-interface design](daemon-design.md#syncd-interfaces-git-braid-and-atomicsync) for their roles and the implemented read-only Braid milestone. -This implementation is unreleased. It reuses #567's CLI/archive work without +This implementation is experimental. It reuses #567's CLI/archive work without changing that draft branch. Device authorization uses the deployed [integration-proxy contract](../../integration-proxy/DEVICE_AUTH.md). Owner signing stays in the existing laptop bridge; the daemon receives device tokens. diff --git a/syncables/package-lock.json b/syncables/package-lock.json index 35f252d36..121a070b2 100644 --- a/syncables/package-lock.json +++ b/syncables/package-lock.json @@ -1,12 +1,12 @@ { "name": "syncables", - "version": "0.25.0", + "version": "0.26.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "syncables", - "version": "0.25.0", + "version": "0.26.0", "license": "Apache-2.0", "dependencies": { "@bokuweb/zstd-wasm": "0.0.27", diff --git a/syncables/package.json b/syncables/package.json index 5478696f4..90067af59 100644 --- a/syncables/package.json +++ b/syncables/package.json @@ -1,6 +1,6 @@ { "name": "syncables", - "version": "0.25.0", + "version": "0.26.0", "repository": { "type": "git", "url": "git+https://github.com/ontola/atomic-plugins.git", From 83cb4ba95e77ddb15d7c7da088cddba5a8118c7b Mon Sep 17 00:00:00 2001 From: Michiel de Jong Date: Fri, 30 Oct 2026 08:40:54 +0000 Subject: [PATCH 2/2] Use capability-based review guidance in the release handoff Record the maintainer's model-neutral documentation request and current cloud-worker CLI check. Keep the required model review and deployment access requirements explicit. Claude-Session: https://github.com/ontola/atomic-plugins/blob/codex/syncd-keep-release-0-26/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md Codex-Session: https://github.com/ontola/atomic-plugins/blob/codex/syncd-keep-release-0-26/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md --- docs/agents/releases/2026-10-29-syncd-keep.md | 12 +++++++----- .../2026-10-29-syncd-release-preparation.md | 19 +++++++++++++++++++ 2 files changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/agents/releases/2026-10-29-syncd-keep.md b/docs/agents/releases/2026-10-29-syncd-keep.md index 173d691a5..a40ee6aba 100644 --- a/docs/agents/releases/2026-10-29-syncd-keep.md +++ b/docs/agents/releases/2026-10-29-syncd-keep.md @@ -4,8 +4,9 @@ Prepared 2026-10-29 from `c968e34417ea37d916a3954121253518e322c339` (merged two-way implementation PR [#713](https://github.com/ontola/atomic-plugins/pull/713)). This document is a rollout handoff, not evidence of publication, deployment or a live Google write. Follow [Q-105 and the release recipe](../proxy-release.md): -merged, Opus-reviewed, green `main`; Heroku rollout through the coordinator's -worker. The cloud worker has GitHub access but no Opus or Heroku credentials. +merged, green `main` reviewed by a state of the art model; Heroku rollout through +the coordinator's worker. The preparing cloud worker had GitHub access but no +Heroku credentials. ## Review and release @@ -17,7 +18,8 @@ notes, especially the PostgreSQL history migration and optional inbox body. The proxy release includes the existing unreleased key-transfer, tier-pacing and webhook changes; check the rolling-deploy/downgrade notes in its changelog. -1. Obtain an Opus review of the implementation/release diffs and resolve findings. +1. Have a state of the art model review the implementation/release diffs and + resolve findings. Review the destructive replacement path, create uncertainty, durable receipt boundary, credential isolation, schema projection, disabled defaults and refresh-scope behavior. Existing green CI is test evidence, not that review. @@ -129,6 +131,6 @@ reviewed release only after evaluating those changelog constraints. Complete when registry publications, the actual Heroku release and preserved production catalog are verified, and the isolated Google create/replace/delete -trial has recorded results. The remaining blockers are the required Opus review, -Heroku-worker access and local owner approval/Keep connection, not another +trial has recorded results. The remaining steps are review by a state of the art +model, Heroku-worker access and local owner approval/Keep connection, not another product authorization decision. diff --git a/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md b/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md index 1a1772f3a..a97c8a8cb 100644 --- a/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md +++ b/syncables/docs/ai-logs/sessions/2026-10-29-syncd-release-preparation.md @@ -46,3 +46,22 @@ this release-only preparation. Only invented fixture data is used locally. Credential values and private note contents are omitted. + +## 2026-10-30: capability-based model guidance and worker location + +The maintainer requested replacing specific Claude/ChatGPT model requirements +in docs/agents with capability descriptions such as “a state of the art model” +and “an efficient model”. Replaced the named review requirement in the working +model, proxy release recipe and pending SyncD release handoff. The review itself +remains required. No smaller-model requirements were present. Product names, +commands and actual host/path identifiers remain operational references. + +The maintainer also asked whether this worker runs on the laptop and can use +Heroku CLI. Verified the current environment is a managed cloud worker running +Linux at /workspace; Heroku CLI is absent. Reported the distinction from the +local desktop app without inspecting credential values. The review-policy +updates are separated from the automatic-publishing release candidate. + +Verification: no specific model names remain in docs/agents; whitespace and +relative Markdown links were checked. This change adds no runtime behavior, +release tag, package publication or deployment.