Skip to content

refactor!: converge on canonical-only v3 naming - #246

Open
developer-1px wants to merge 5 commits into
mainfrom
docs/245-canonical-concept-naming-ssot
Open

refactor!: converge on canonical-only v3 naming#246
developer-1px wants to merge 5 commits into
mainfrom
docs/245-canonical-concept-naming-ssot

Conversation

@developer-1px

@developer-1px developer-1px commented Jul 30, 2026

Copy link
Copy Markdown
Owner

Goal Anchor

Outcome

Make json-document a durable, unambiguous naming foundation for future editable, canvas, presentation, and sheet systems.

Done when

  • one canonical concept dictionary and prefix/suffix grammar governs every active package
  • public APIs, internal identifiers, files, tests, standards, site copy, and metadata use only canonical vocabulary
  • deprecated naming aliases and compatibility fallbacks are absent
  • drift checks mechanically reject their return

Do not

  • do not change runtime algorithms or state transitions
  • do not change protocol meaning, serialized wire fields, or package boundaries
  • do not publish packages or merge without separate authorization

Approved contract deltas

  1. Repository-wide application expanded the original documentation-only anchor.
  2. The user then explicitly authorized a breaking cleanup because the published package has no other consumers and will become the shared foundation for future editor systems.
  3. Because removing published v2 names is breaking, the active contract moves to v3 rather than mislabeling the new surface as stable v2.

The immutable original anchor and both append-only deltas remain recorded in Issue #245 and the repository issue SSOT.

Canonical-only public surface

Core 3.0.0

  • 21 root exports
  • six JSONDocument members: value, at, query, validatePatch, commit, subscribe
  • removed canPatch, JSONCapabilityResult, and options.accepts

Collaboration 0.2.0-rc.1

  • canonical CollaborationReplica, ReplicaStatus, runtime.replica, and status()
  • canonical CollaborationValidation, History*, Text*, and didChangeDocument
  • removed all duplicate CollaborationHistory* / CollaborationText* names and option/result fallbacks

Contenteditable 0.2.0-rc.1

  • canonical ContentEditable*, TextDOMAdapter, DOMObservation
  • removed duplicate collaboration-prefixed exports and projectionChanged

Standards and enforcement

  • active profile and manifest moved to v3/JD3
  • Projection-named conformance paths, harnesses, vectors, and bindings became JSON Document artifacts
  • package manifests and peer ranges follow SemVer for the breaking surface
  • naming drift checks reject all removed identifiers in package source
  • archive/v1 remains unchanged and isolated

Verification

  • full npm run verify passed
  • npm run standard:check: 213 passed, 2 skipped
  • core: 220 passed, 2 skipped; typecheck, build, layers, and package smoke passed
  • collaboration: 116 passed; typecheck and build passed
  • contenteditable: 17 passed; typecheck and build passed
  • site: 12 passed; typecheck, Pages build, metadata evaluation, and HTTP smoke passed
  • browser: 3 passed
  • docs generation/evaluation, archive isolation, diff check, and pre-push build passed

Compatibility-only test counts disappeared because the aliases themselves were intentionally removed.

Contract audit

Runtime algorithms and state transitions are unchanged. Versioned wire labels and codes such as acceptance, acceptance_required, acceptance_reentrancy, deps, and ops remain unchanged. No npm package was published.

Closes #245

@developer-1px developer-1px changed the title docs: establish canonical concept and naming standard refactor: apply canonical naming repository-wide Jul 30, 2026
@developer-1px developer-1px changed the title refactor: apply canonical naming repository-wide refactor!: converge on canonical-only v3 naming Jul 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Establish the canonical concept dictionary and naming grammar

1 participant