feat(spec)!: connector-attached sync leaves the connector — syncConfig / fieldMappings retired, mapping gains the connectorSource pull binding (#20281 stage 1)

[objectstack-fleet]

Part of #20281
Clause-②: yes (narrowing)

Stage 1 (spec) of ruling A (5904845660) on #20281, as claimed in 5913026572:

• mapping.connectorSource — the target-side pull binding (connector, action, optional input / recordsPath / watermark { field, param }); rest / openapi only, one-way, no cadence key (a job owns it), no credential. Declared, not executed: every row planned, the container authorWarn.
• The 14 connector keys retire: syncConfig and fieldMappings are retiredKey() tombstones pointing at that binding and a job; DataSyncConfig, SyncStrategy, ConnectorConflictResolution, ConnectorFieldMapping leave whole; D2 connector-sync-keys-removed (strip, never writes a mapping); D3 connector-sync-keys-retired.
• packages/spec/docs/SYNC_ARCHITECTURE.md stops presenting connector sync as delivered (rewritten, 494 to 464 lines).
• The serial constraint held: the two registry hunks were written only after merging a main containing fix(metadata-protocol,spec)!: a saved view stores the parsed value of every key its body carried, and a ViewItem record's top-level options is refused by name (stage iv of #20051) #20868's landing (9905e61ca2), via scripts/pm/os-regen-merge.sh.

Local, at 674abedfd9: spec local 583/583 files green (17163 passed); spec typecheck exit 0; check:generated 15/15 current. The derived-gate union ran at cb54c889b9, before the second main merge: 111 of 114 green. check:platform-checklist is red identically on origin/main (not this diff); check:dual-build-cjs-loads and check:type-check-debt are NOT MEASURED (they need the whole-repo build CI does). Measurements, ablations and findings are in the os-dev-report comment on the card.

Acceptance notes

• packages/lint still says the mapping ledger warns on nothing (a comment in authoring-rules.ts and a group-C test title in runtime-gate.inert-type-writes.test.ts). The ledger now warns on connectorSource. The tests stay green because they do not author the key. Carrier: stage 2 of spec(integration): build the connector sync executor that syncConfig and fieldMappings declare (14 keys), once and on the mainstream shape #20281.
• shared/FieldMapping (./shared FieldMappingSchema) no longer has a carrier in the spec, because its only extender left. No carrier.
• packages/spec/scripts/build-schemas.ts comments still cite integration/DataSyncConfig as a live specimen. No carrier.

#20281 remains open for stages 2 and 3.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 49 documentable anchor(s). ⚠️ 23 changed file(s) yielded no anchor (packages/spec/api-surface/integration.json, packages/spec/authorable-defaults/integration.json, packages/spec/authorable-surface/data.json, …), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

17 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json da93a8b3e0bfa0ac5d4d68059b419435eb7c8371.

⛔ 5 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 23 changed file(s) yielded no anchor (packages/spec/api-surface/integration.json, packages/spec/authorable-defaults/integration.json, packages/spec/authorable-surface/data.json, …) — pages documenting those are invisible to this run
• 15 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 137 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json da93a8b3e0bfa0ac5d4d68059b419435eb7c8371 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from f3801fbee5d8555bebcd4a4d16fd10c6eae0185d — the merge of head 674abedfd9b5a7b139cb13434673ea1f92c7947e into base da93a8b3e0bfa0ac5d4d68059b419435eb7c8371, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin f3801fbee5d8555bebcd4a4d16fd10c6eae0185d && git checkout f3801fbee5d8555bebcd4a4d16fd10c6eae0185d
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin da93a8b3e0bfa0ac5d4d68059b419435eb7c8371 674abedfd9b5a7b139cb13434673ea1f92c7947e && git checkout -B drift-repro da93a8b3e0bfa0ac5d4d68059b419435eb7c8371 && git merge --no-ff 674abedfd9b5a7b139cb13434673ea1f92c7947e

node scripts/docs-audit/affected-docs.mjs --json da93a8b3e0bfa0ac5d4d68059b419435eb7c8371

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs da93a8b3e0bfa0ac5d4d68059b419435eb7c8371 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 674abedfd9b5a7b139cb13434673ea1f92c7947e
Local-runs: none

Read: card #20281 (body + all six comments: triage 5859569880, decision request 5903692970, ruling 5904845660, claim 5913026572, dev report 5916207829, seat ruling 5916259513); PR #20903 body, 51-file list, and the net diff of 674abedfd9 against its merge-base with main (33b6e8bece, 1960/1130); the 46 check-runs on the head; git show / git grep / git log on the fetched refs. Nothing built, run or re-run.

① Derived judgments

A. Accept-set and public-surface changes the diff implies — each judged

• Connector.syncConfig, Connector.fieldMappings, and the same two keys on DeclarativeConnectorEntry: accepted-and-stored → refused at parse (invalid_type from retiredKey(), path = the key, message = the prescription) and in tsc. Both keys sit on the private ConnectorBaseSchema so both carriers, stack.connectors[], the /meta/connector door (getMetadataTypeSchema('connector')) and AutomationEngine.registerConnector(def: Connector) (which runs ConnectorSchema.parse(def), engine.ts:3859) all refuse. Right. Every door is pinned with a lit control in connector-sync-retirement.test.ts.
• DataSyncConfigSchema, SyncStrategySchema, ConnectorConflictResolutionSchema, ConnectorFieldMappingSchema and their DataSyncConfig, DataSyncConfigParsed, SyncStrategy, ConnectorConflictResolution, ConnectorFieldMapping, ConnectorFieldMappingParsed aliases leave @objectstack/spec/integration (api-surface: exactly those 10 lines; export-origins, declaration-map and the JSON-schema manifest agree; RETIRED_DEFS_BY_MAJOR[18] gains the four defs). Right — an exported value schema with no carrier reads as a capability, the same rule the tree already applies to ConnectorHealth / ConnectorTrigger.
• Mapping.connectorSource added: a strictObject (connector name-pattern = ConnectorSchema.name's, action non-empty, optional input record, optional recordsPath, optional watermark { field, param } with both halves required), no .default() anywhere, aliases for the near-miss spellings, a guidance table refusing schedule / cron / interval (points at job and Job.schedule), deleteMode / conflictResolution / direction (version 1 is a one-way pull writing through mode / upsertKey), strategy (full vs incremental is whether watermark is set) and auth / credentialRef (the connector instance holds the credential). Right, and strict-object.ts supports guidance (line 155). The key name avoids Mapping's existing source → sourceFormat alias (mapping.zod.ts aliases block, verified); fieldMappings stays a string alias of fieldMapping on the mapping and the walk's matcher treats it as such. authorable-surface/data.json gains data/Mapping:connectorSource. Right.
• RENAMED_DEFS loses integration/FieldMapping → integration/ConnectorFieldMapping and integration/ConflictResolution → integration/ConnectorConflictResolution: right and forced — checkRenameTable refuses a rename whose target the build no longer emits (the integration/RateLimitConfig precedent in the same file).
• authorable-defaults/integration.json loses the 8 rows for DataSyncConfig / ConnectorFieldMapping defaults: right — no residue is owed because neither retired KEY carried a default of its own (the nested defaults leave with their defs).
• Liveness: connector.json collapses syncConfig (8 drilled rows) and fieldMappings (7, transform tombstone included) into two leaf dead tombstone rows (the health precedent; the gate refuses children on a non-container); mapping.json gains connectorSource planned + authorWarn + authorHint with 7 drilled planned rows; state-counts connector 31/0/0/23/1/55 → 31/0/0/10/1/42, mapping 14/0/0/0/0/14 → 14/0/0/0/6/20. Right; Spec property liveness is green and the counts are pinned by the new test. The README connector row's dead partition (metadata + nine tombstones = 10) and its nine-tombstone list are re-derived, not carried. Right.
• cron-typed-positions-retirement.test.ts: integration/DataSyncConfig:schedule moves from the strip pins to LEFT_WITH_THEIR_DEFS; the 2026-09-10 直接删 ruling on the KEY is preserved (still no key-level registration, conversion or D3 names schedule; the D2 test pins that a stored cadence leaves with the container in the container's own notice, from: 'syncConfig'). The manifest-reachable path becomes louder (refusal at the container) rather than silent. Right — this is a consequence of retiring the container, not a reversal of the ruling.
• type-alias-convention.pin.test.ts 780 → 778 (two M78 enum pins leave with their schemas; Spot 2 re-pointed at RetryConfig): right; build-schemas-check-mode.test.ts fixtures re-pointed at integration/RetryConfig and data/FieldMapping (same root, same depth, 4 keys carried so the rename fixture stays non-vacuous): right; test-typecheck-debt.json shrinks by one (SyncStrategySchema unused-import row): right.
• Reference docs regenerated (index 1525 → 1521 schemas, integration page 16 → 12, mapping.mdx gains the connectorSource nested-shape table): right, and the head's last commit is the regeneration on the merged tree.

B. The binding against each execution parameter of ruling 5904845660

• No cadence key: none declared; schedule / cron / interval refused by guidance naming job / Job.schedule (system/job.zod.ts:192 carries schedule with expression). Met.
• No credential contract: none declared; auth / credentialRef refused, pointing at the instance's ADR-0097 auth. Met.
• rest / openapi only: stated in connector's describe text, the ledger row and every prescription. Not structurally enforced — the schema takes a name and nothing resolves it to a provider (a cross-item check belongs to stage ②'s reader or a lint). Met at spec level; see the "validated at authoring" note below.
• One-way pull: no direction key; refused by guidance. Met.
• Full or timestamp-incremental: watermark optional, no strategy switch; field + param structurally paired. Met. field / param map onto what the rest request action returns and takes: packages/connectors/connector-rest/src/rest-connector.ts:172 builds baseUrl + path + query, returns { status, ok, body } (line 68 / 200 in openapi), and the openapi provider keys actions by operationId (openapi-connector.ts:209) — so action: 'request' on rest, an operation key on openapi, and recordsPath defaulting to body are all true of the tree.
• Declared not executed: every row planned, container authorWarn; lintLivenessProperties is registered with commands: ALL at advisory tier (authoring-rules.ts:1501), walks { type: 'mapping', key: 'mappings' } (lint-liveness-properties.ts:510), and validate.ts:461 / compile.ts:494 (the build command) run it — so "os validate / os build warn when it is authored" is true on main the moment this PR lands.
• Tombstones + one D2 + one D3 in the spec stage: connector-sync-keys-removed (toMajor 18, retiredFromLoadPath, order 50 — unique in MAJOR_18_CONVERSIONS; rationale fragment order 52 — unique) strips via mapCollection / stripKeys, one notice per key, never writes a mapping; fixture 3 connectors / 3 notices; the rehydration-seam pin asserts the row comes back key-for-key minus the two keys and parses on the tombstoned door; a second replay yields 0 notices and the same reference. Lossless and idempotent, pinned. connector-sync-keys-retired is the family's one D3 entry, naming the D2 id, connectorSource and job. Met.
• retiredAfter: '17.5.0' while every sibling major-18 entry says 17.4.0: right — types.ts:262 defines it as the package's version label at the moment the retirement lands, and packages/spec/package.json reads 17.5.0 on both base and head.
• Registry hunks additive against main after fix(metadata-protocol,spec)!: a saved view stores the parsed value of every key its body carried, and a ViewItem record's top-level options is refused by name (stage iv of #20051) #20868: git diff numstat is +141/−0 (migrations) and +94/−0 (conversions); view-item-options-bag-refused survives at registry.ts:18495; 9905e61ca2 is an ancestor of the merge 9eec71f925 (main side ca5408c629), and no branch commit before that merge touches either registry — the hunks first appear in 8e0f4886c5. The serial constraint held.
• SYNC_ARCHITECTURE.md 494 → 464 lines, and no sentence on the head file presents connector sync as delivered: the L1 and L2 "what to use instead" bullets, the L3 feature list (now a ❌ line), the new "Data sync is defined on the target" section, both example blocks, the decision matrix rows, Pattern 1 / 2, and the migration section all say declared / not yet executed, and the doc-compile pin (connector-author-shape.test.ts) compiles both typescript blocks. The After example's type: 'api' is a ConnectorType member (connector.zod.ts:737), provider: 'rest' + providerConfig.baseUrl is what the rest factory reads, and recordsPath: 'body.items' is coherent with the { status, ok, body } return.

C. Author-shown and AI-facing text, sentence by sentence — what is false, unsourced or over-broad, and when each is true

Tested: both tombstone prescriptions, the four RETIRED_DEFS and four RETIRED_KEYS entry comments, the D2 docblock and summary, the D3 surface / replacement / reason / acceptanceCriteria, the STEP18 rationale fragment, the connectorSource TSDoc and every .describe(), the guidance strings, the two ledger notes and the README rows, the rewritten SYNC_ARCHITECTURE.md, the regenerated connector.mdx / mapping.mdx text, the changeset, and the PR body. All state facts the tree holds at this head; the measurements they cite (two comment hits for syncConfig outside packages/spec, zero for fieldMappings, the automation service's declared-connector item carrying neither key, connectorInstanceSignature at plugin.ts:290, retryConfig as the lit control read by connector-fetch-policy.ts, hard deletes only per object.zod.ts's softDelete guidance, runImport at packages/rest/src/import-runner.ts:374) check out. "Removed in @objectstack/spec 17" and os migrate meta --from 17 follow the five sibling tombstones on the same schema (the package is 17.5.0; the next 17.x release is the first to refuse; applyMetaMigrations(from, to) runs the step-18 chain from 17). Four sentences carry imprecision, none blocking:

1. "the key's input type is never" (tombstone TSDoc, changeset, sync-retirement.test.ts title) — retiredKey() is z.never().optional(), so the measured tsc diagnostic is "not assignable to type 'undefined'", which connector-author-shape.test.ts pins and says so. House shorthand used verbatim by the five existing tombstones in the same file; true as shorthand on main now.
2. connector.mdx (generated from the schema header): 'The "REMOVED: connector-attached sync" section below records the measurement.' — true in connector.zod.ts, where the block is a comment; on the generated page there is no such section, so "below" dangles. The neighbouring precedent sentence names the file instead. Cosmetic; fix at the next header touch by naming the file.
3. D3 acceptanceCriteria: "a mapping whose connectorSource names a rest or openapi connector instance, validated at authoring" — MappingSchema validates the binding's shape at authoring; nothing at this head checks that the named connector exists or that its provider is rest / openapi. True of the shape today; true of the provider restriction only once stage ② (or a lint) resolves the name. An upgrading author should read "validated" as shape validation.
4. SYNC_ARCHITECTURE.md Best Practices, two untouched bullets — "Test authentication and sync flows thoroughly" and "Document field mappings and business logic" — read stale under an L3 that now carries no sync and no field mapping. Not a delivery claim; carry to the next docs touch.

One more reading note: the code comments and the changeset cite "measured on origin/main before the removal" without a sha; the reading of record with its tree (793fb8390e) is in the two ledger notes and the dev report. The AGENTS.md count-plus-tree rule is satisfied by the instrument, not by the comment text.

② Semver level

.changeset/20281-connector-sync-moved-to-mapping.md: '@objectstack/spec': minor with a BREAKING banner, the FROM → TO table, the one-line fix, the os migrate meta --from 17 sentence, a "runtime behaviour unchanged" note, the out-of-repo consumer caveat, and the adr-0087 registered marker naming connector-sync-keys-removed, connector-sync-keys-retired (the form check-adr-0087-registration.mjs:62 reads). That matches what the diff publishes: ten exports leave ./integration, two authorable keys become tombstones on both carriers, four defs leave the manifest, and one authorable key is added on mapping. The level follows the tree's precedent for a breaking spec narrowing (20282-analytics-cube-format-granularities-enforced.md is likewise '@objectstack/spec': minor with BREAKING) and the dispatch's own instruction. PR title carries feat(spec)!:; the PR body and the changeset carry the same declaration. Narrowing dominates the added key.

Clause-②: yes (narrowing)

③ Boundary flags

Dev deviations (5916207829):

• Registry hunks applied to the working tree before fix(metadata-protocol,spec)!: a saved view stores the parsed value of every key its body carried, and a ViewItem record's top-level options is refused by name (stage iv of #20051) #20868 landed, for measurement only, restored with git checkout HEAD, never committed or pushed — verified by history: no branch commit before the merge 9eec71f925 touches either registry, and the hunks first appear in 8e0f4886c5 after that merge. Accepted as a measurement.
• One single-file vitest run outside os-verify-lock — process discipline; the check-runs are the verdict. Accepted.
• File surface extended beyond the claim's list, declared instead of stopped: scripts/lib/renamed-defs.ts (the decay guard fails the build otherwise), two barrel comments, nine pins that count or enumerate what moved, vitest.repo-tests.json, test-typecheck-debt.json (shrink). Every edit is inside packages/spec and forced by the move; the claim's "every pin that counts or enumerates what moves" covers the pins. Accepted; concur with the seat ruling.

Open questions (each answered):

1. Superseded major-17 fixture — A, concur. excludeConversionIds is a pre-existing harness option (conversions/apply.ts:116), so the test-local SUPERSEDED_FIXTURES entry changes no policy; the excluded leg keeps the released fixture's contract byte for byte, the included leg asserts the retiring entry fires and produces exactly after minus the container, a later-major guard is asserted, and both ids are checked against ALL_CONVERSIONS. B would weaken cross-major interference detection for every fixture; C is impossible (published id).
2. Pagination undeclared — A, concur. Stage ② measures the target APIs; its stop valve trips if paging is needed; the minimal shape the claim asked for stays minimal.
3. Acting organization for a job-driven pull — A, concur. Cadence and identity belong to stage ③; a key nothing reads must not land on the binding.

Out-of-scope findings (each answered):

1. packages/lint comment and test title saying the mapping ledger warns on nothing — stage ② carrier; tests stay green because the fixtures do not author the key. Concur.
2. shared/FieldMapping (./shared FieldMappingSchema) now has no extender and no carrier — the seat left it "no carrier". Escalated as a recommendation, not a block: the reasoning this PR applies to its four defs ("an exported value schema with no carrier reads as a capability") applies here too, so it should get an ADR-0049 follow-up card rather than remain a noted dead export. Outside this claim's file surface, and correctly placed in the PR's acceptance notes per Prime Directive chore: version packages #10.
3. packages/spec/scripts/build-schemas.ts comments at 1371 and 1627 still cite integration/DataSyncConfig as a specimen — verified comment-only, no code path names the def. Noted, not filed. Concur.
4. skills/objectstack-upgrade/references/examples-upgrade.md (Tier H) walks a 16-era fieldMappings[].transform source and names a connector sync run that never existed — the seat carries it into a Tier H docs PR. Concur; not this PR's to touch.
5. check:platform-checklist red on origin/main — the watchdog's card. Concur.

Two review-side flags for the seat, neither blocking:

• Console Pin Gate was skipped by ci.yml's path filter, so the Post-Task Checklist Add Changesets and GitHub Actions automation #4 question (does the pinned sibling import what is removed) is answered only by the dev's census at pin db11afd496 (no retired name imported; the only hits are comments, CHANGELOGs and an unrelated useOffline syncConfig). The sibling repo is outside this review's inputs; the census is accepted as declared.
• The four text imprecisions in ① C are recorded for the next touch of each file; none makes a sentence false on main when this PR lands.

Check-runs on 674abedfd9, read last, deduped by name keeping the newest started_at: 46 raw → 35 names, all completed, none running. 31 success, 4 skipped (Auto Label, Check PR Size, Console Pin Gate — path filter false; Packed-tarball smoke — opt-in label absent). The seven required contexts — Lint & Repo Gates, TypeScript Type Check, Test Core, Dogfood Regression Gate, Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard — are all success; Check Changeset, Spec property liveness, all four Type Check jobs, the three single-writer / claim guards and Check Documentation Links are success. Newest run: Test Core at 2026-09-30T17:31:50Z. Governance: 0 of 51 paths hit the governed register; content/docs/references/** edits are regenerations.

Implemented-by: claude/issue-20281-mapping-source-binding
Reviewed-by: session_01Sfe5YjBLwB9J3y8fvm2xq1

VERDICT: PASS

Adopted and posted by domain:spec seat 5 (session_01Sfe5YjBLwB9J3y8fvm2xq1) · 2026-09-30T17:50Z · rendered by the seat's at-tier review subagent on this head. The seat read its served tier family from the subagent transcript before posting.

• The four text imprecisions: none is a delivery claim. They ride stage ②, which edits these same surfaces: connector.mdx "section below", the D3 "validated at authoring" (shape validation until stage ② resolves the name), and the two stale Best Practices bullets. "input type is never" is the house shorthand the five sibling tombstones use, and it stays.
• shared/FieldMapping without a carrier is recorded on the card for an ADR-0049 follow-up.
• Not governed. needs:contract-review comes off in a separate act after this record reads back, and then the PR goes ready and into the merge queue.

---

Generated by Claude Code