From 3bf3f35bb5dd5519e3081f766009d217d577bb27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E1=84=8B=E1=85=B2=E1=84=8B=E1=85=AD=E1=86=BC=E1=84=90?= =?UTF-8?q?=E1=85=A2?= Date: Fri, 19 Jun 2026 12:09:39 +0900 Subject: [PATCH] =?UTF-8?q?docs:=201.0=20RFC=20=EA=B2=B0=EC=A0=95=20?= =?UTF-8?q?=EC=A0=95=EC=8B=9D=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + docs/README.md | 1 + docs/standard/conformance-profile.md | 138 ++++++++++++++++++ docs/standard/contract-pressure-register.md | 34 +++-- docs/standard/core-standard.md | 15 +- .../standard/extension-delegation-standard.md | 58 ++++++++ docs/standard/foundation-gate.md | 1 + labs/extensions/autosave/README.md | 9 ++ labs/extensions/calculated-fields/README.md | 9 ++ labs/extensions/paste-special/README.md | 10 ++ llms.txt | 5 +- scripts/evaluate-standardization.mjs | 14 ++ 12 files changed, 279 insertions(+), 16 deletions(-) create mode 100644 docs/standard/conformance-profile.md diff --git a/README.md b/README.md index f3ea3205..44fe74a4 100644 --- a/README.md +++ b/README.md @@ -25,6 +25,7 @@ schema -> document -> pointer/query -> can* -> change -> result | 문서 구조 | [docs/README.md](docs/README.md) | | 변경 기록 | [docs/changelog.md](docs/changelog.md) | | core 의미론 명세 | [docs/standard/json-document-spec.md](docs/standard/json-document-spec.md) | +| 1.0 conformance profile | [docs/standard/conformance-profile.md](docs/standard/conformance-profile.md) | | result/error 계약 | [docs/standard/result-contract.md](docs/standard/result-contract.md) | | selection 계약 | [docs/standard/selection-contract.md](docs/standard/selection-contract.md) | | schema introspection 계약 | [docs/standard/schema-introspection-contract.md](docs/standard/schema-introspection-contract.md) | diff --git a/docs/README.md b/docs/README.md index 3fad0c1c..1b875933 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ docs | `-- recipes.md # 제품별 feature coverage 지도 `-- standard |-- core-standard.md # 표준 후보 계약 + |-- conformance-profile.md # 1.0 compatibility profile |-- contract-pressure-register.md |-- extension-delegation-standard.md |-- foundation-gate.md # foundation 판정 기준 diff --git a/docs/standard/conformance-profile.md b/docs/standard/conformance-profile.md new file mode 100644 index 00000000..c4ccf732 --- /dev/null +++ b/docs/standard/conformance-profile.md @@ -0,0 +1,138 @@ +# json-document 1.0 Conformance Profile + +상태: 1.0 정식화 기준. + +이 문서는 `@interactive-os/json-document` 1.0 호환성을 무엇으로 검증할지 +정의한다. 목표는 새 public API를 만드는 것이 아니라, 이미 고정된 public API +계약을 외부 구현체와 유지보수자가 같은 기준으로 읽게 만드는 것이다. + +1.0의 conformance profile은 문서화된 profile이다. 별도 npm package, CLI runner, +외부 구현체용 harness는 1.0 범위에 포함하지 않는다. 그런 artifact는 나중에 만들 +수 있지만, 1.0 core API 안정화의 선행 조건은 아니다. + +## 규범 + +`MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`는 규범 키워드다. + +`json-document compatible`을 주장하는 구현체는 public package entrypoint만으로 +이 profile의 의미론을 만족해야 한다. 구현체는 consumer에게 source path, +private module, test helper, dist 내부 파일 import를 요구하면 안 된다. + +## Profile Class + +| Profile | 대상 entrypoint | 의미 | +| --- | --- | --- | +| Core | `@interactive-os/json-document` | headless document foundation 표면 | +| React | `@interactive-os/json-document/react` | 같은 document 표면을 React hook으로 노출 | + +React profile은 선택적이다. Core profile을 통과하지 못한 구현체는 React profile을 +주장할 수 없다. + +## 1.0 Profile Artifact + +1.0 conformance는 다음 artifact 묶음으로 정의한다. + +| Artifact | 역할 | +| --- | --- | +| `docs/standard/core-standard.md` | public semantics의 규범 기준 | +| `docs/standard/result-contract.md` | result shape, stable error code, diagnostic 기준 | +| `docs/standard/selection-contract.md` | headless selection snapshot과 patch tracking 기준 | +| `docs/standard/schema-introspection-contract.md` | schema query, `schema-slot`, `document-result` 기준 | +| `packages/json-document/public-contract.json` | public export name lock | +| `packages/json-document/tests/public/signature-contract.test-d.ts` | overload와 call shape lock | +| `packages/json-document/tests/public/semantic-contract.test.ts` | strict 기본값, atomicity, clipboard spread, selection/history round-trip fixture | +| `packages/json-document/tests/public/result-contract.test.ts` | result code와 success result shape fixture | +| `packages/json-document/tests/public/standard-conformance.test.ts` | public entrypoint 기반 broad conformance scenario | +| `packages/json-document/tests/public/json-patch/*` | RFC 6902 JSON Patch 공개 동작 | +| `packages/json-document/tests/public/json-pointer/*` | RFC 6901 JSON Pointer 공개 동작 | +| `packages/json-document/tests/public/jsonpath/*` | JSONPath 검색 공개 동작 | + +이 artifact들은 서로 다른 층을 잠근다. + +```txt +conformance profile +|-- export lock: 이름이 사라지지 않는다 +|-- signature fixture: 호출 모양과 overload가 유지된다 +|-- semantic fixture: 1.0 이후 바뀌면 breaking인 예시를 고정한다 +|-- result fixture: code와 result shape로 분기할 수 있다 +|-- standard conformance: public entrypoint만으로 foundation 흐름을 검증한다 +`-- protocol fixtures: JSON Patch, Pointer, JSONPath 의미론을 검증한다 +``` + +## 포함되는 의미론 + +Core profile은 다음 의미론을 포함해야 한다. + +- JSON data boundary와 JSON-serializable public payload. +- JSON Pointer 주소와 JSONPath 검색의 구분. +- RFC 6902 JSON Patch 실행과 실패 atomicity. +- schema validation과 schema introspection. +- `strict: false` 기본값과 `strict: true` throwing boundary. +- `can*` capability purity와 reasoned result. +- document mutation result shape와 stable error code. +- headless selection snapshot, `selectionAfter`, patch tracking. +- document-owned clipboard buffer와 payload-only paste. +- undo/redo history round-trip. +- public root helper의 pure patch behavior. + +## 포함하지 않는 것 + +다음은 1.0 conformance profile의 일부가 아니다. + +- 별도 `@interactive-os/json-document-conformance` package. +- 외부 구현체용 CLI runner. +- private source path 또는 implementation-only helper. +- `dist/` 파일 구조. +- demo app, site, browser test, Playwright fixture. +- official extension, lab extension, product recipe의 동작. +- performance budget. +- DOM focus, rendering, keyboard, system clipboard permission, storage backend. + +Extension은 core profile 위에서 compose되어야 하지만, extension test를 통과했다고 +core compatible을 주장할 수는 없다. 반대로 core profile이 extension public API를 +자동으로 고정하지도 않는다. + +## 실행 기준 + +이 repo의 1.0 release gate는 다음 명령을 통해 profile과 관련 artifact를 검증한다. + +```sh +npm run standard:check +npm run docs:evaluate +npm test -w @interactive-os/json-document -- semantic-contract result-contract standard-conformance +npm run typecheck -w @interactive-os/json-document +``` + +`npm run standard:check`는 표준 문서, conformance scenario, semantic fixture, +signature fixture, public export lock이 서로 분리되지 않았는지 확인한다. + +## 변경 기준 + +다음 변경은 conformance profile 관점에서 breaking change다. + +- public export 제거 또는 rename. +- public overload와 call shape 변경. +- 기존 stable error code 제거, rename, 의미 변경. +- success result shape 의미 변경. +- failed mutation이 state, selection, clipboard, history, subscriber를 부분 변경하게 됨. +- `schema-slot`과 `document-result` violation path 기준 변경. +- `selectionAfter`보다 auto tracking을 우선하도록 변경. +- payload-only core clipboard/paste 의미론 변경. + +다음 변경은 별도 검토 후 minor일 수 있다. + +- 새 optional result diagnostic field. +- 새 error code 추가. +- 새 `SchemaKind` 추가. +- 새 conformance scenario 추가. + +## 보류된 artifact + +별도 conformance package나 runner는 보류한다. 보류 이유는 다음이다. + +- 1.0에서 public API surface를 더 늘리지 않는다. +- 현재 목표는 외부 구현체 지원 tooling보다 public contract freeze다. +- profile이 문서와 fixture로 충분히 안정된 뒤에야 runner API도 안정적으로 설계할 수 있다. + +추후 runner를 만든다면 이 문서의 profile을 source of truth로 삼아야 하며, +runner가 새로운 의미론 계약을 추가하면 안 된다. diff --git a/docs/standard/contract-pressure-register.md b/docs/standard/contract-pressure-register.md index 9f676981..5c2f2556 100644 --- a/docs/standard/contract-pressure-register.md +++ b/docs/standard/contract-pressure-register.md @@ -41,7 +41,7 @@ Core 승격은 마지막 단계다. 다음 중 하나라도 불명확하면 core | --- | --- | --- | --- | | guard composition | `protected-ranges`, `proposed-changes`, `search-replace`, paste/drop 계열이 guard와 core capability 실패를 조합 | 부분 반영: `@interactive-os/json-document-protected-ranges` | 같은 guard result shape가 3개 이상 package에서 자연스럽게 맞는지 확인 | | patch preview / dry-run | `patch-preview`, `document-diff`, `proposed-changes`, import/review workflow가 apply 전 next value를 요구 | 반영됨: `@interactive-os/json-document-patch-preview` | downstream dogfood에서 visual diff/review workflow가 host-owned로 남는지 확인 | -| structural change result | `grouping`, `wrap-selection`, `outline`, `bulk-edit`가 prospective operations와 execution result를 노출 | lab convention | `operations`, `selectionAfter`, `diagnostics` naming을 통일할 수 있는지 확인 | +| structural change result | `grouping`, `wrap-selection`, `outline`, `bulk-edit`가 prospective operations와 execution result를 노출 | **결정됨: extension convention** | Core API 변경 없음. 외부 extension에는 SHOULD, repo official/lab에는 MUST로 `operations`, `selectionAfter`, `diagnostics`를 소급 적용 | | anchored pointer lifecycle | `comments`, `bookmarks`, `live-cursors`, review anchor가 `trackPointer` 이후 lost/recovered 상태를 반복 | 부분 반영: `@interactive-os/json-document-comments` | generic anchor lifecycle이 bookmark/presence 밖에서도 같은지 확인 | | stable id to Pointer | Kanban, form builder, import/review, slide/layer selection, blind object editor review에서 반복 | 반영됨: `@interactive-os/json-document-id-resolver` | downstream dogfood에서 id policy가 host-owned로 남는지 확인 | | invalid form draft | form builder, settings, CMS property panel, spreadsheet cell editing에서 valid JSON commit 전 temporary input이 반복 | 반영됨: `@interactive-os/json-document-form-draft` | parser/widget/focus policy가 host-owned로 남는지 확인 | @@ -52,7 +52,7 @@ Core 승격은 마지막 단계다. 다음 중 하나라도 불명확하면 core | lab result boilerplate | 여러 lab이 `capabilityError`/`patchError`/`error`/`cloneJson` helper를 반복 | lab convention | helper 모양만으로 shared package/core를 만들지 않는다. 같은 실패 의미론이나 실행 단계가 반복될 때만 후보로 기록 | | command-sized feature granularity | `pad-text`, `trim-text`, `round`, `limit-items` 같은 단일 field/array command lab이 빠르게 증가 | reusable command feature | 편집도구 command로 이름 붙일 수 있으면 feature다. package 배포 단위와 feature 판정은 분리 | | semantic contract lock | export lock은 이름만 고정하고 signature/error literal 의미론은 문서와 테스트가 고정 | evaluator 후보 | signature snapshot 또는 semantic fixture를 추가할지 확인 | -| structural object commands | grouping, wrap/unwrap, layer order가 slide/diagram/object editor에서 반복 | official 후보 | 같은 `operations`/`selectionAfter` result shape로 승격 가능한지 확인 | +| structural object commands | grouping, wrap/unwrap, layer order가 slide/diagram/object editor에서 반복 | official/lab convention | `operations`/`selectionAfter`는 extension convention으로 고정. 개별 package 승격은 별도 증거 필요 | | sibling-range 정규화 | "선택된 sibling pointer → {공유 parent, 정렬 index, 연속성}" 를 `fill-series`·`move-selected`·`grouping`·`wrap-selection`·`layer-order` 5개 독립 확장이 재구현. `grouping`/`wrap-selection`의 resolver는 byte 단위 동일 | **반영됨: core `resolveSiblingRange` (#95)** | 순수 path helper로 core 승격(#95), 5개 소비자 모두 수렴(#96/#97/#98). `drag-drop`은 단일 source/target 개별 해석이라 range 대상이 아님(하위 primitive 사용, 제외). 남은 후보: 에러 코드 통일(현재 각 확장이 helper 코드를 자기 코드로 매핑) | ## Guard Composition @@ -108,8 +108,11 @@ plan pressure - `patch-preview`는 `@interactive-os/json-document-patch-preview` official extension으로 승격했다. - `PatchPlan`은 core 타입으로 만들지 않는다. -- lab에서는 `operations`, `preview`, `apply`, `diagnostics`, `selectionAfter`를 - 같은 의미로 쓰는지 확인한다. +- structural command 계열은 `operations`, `selectionAfter`, `diagnostics`를 + convention으로 쓴다. 외부 extension에는 SHOULD, 이 repo의 official/lab에는 + MUST다. +- `preview`와 `apply`는 feature가 preview/execution boundary를 노출할 때의 + method 이름 후보이지, 모든 structural result의 공통 field가 아니다. 최소 공유 어휘 후보: @@ -121,6 +124,13 @@ plan pressure | `diagnostics` | 실행을 막지는 않지만 adapter/import/paste에서 알려야 하는 정보 | | `selectionAfter` | 구조 편집 후 host가 focus/selection을 옮길 Pointer | +Repo 내부 audit 결과 `grouping`, `outline`, `bulk-edit`, `proposed-changes`, +`wrap-selection`, `move-selected`, `layer-order`, `fill-series`, `grid-range`, +`paste-cells`, `batch-update`, `clear-contents`, `fill-blanks`는 이미 +`operations`와 필요한 경우 `selectionAfter`로 수렴했다. `paste-special`, +`id-resolver`, `references`는 비차단 정보를 `diagnostics`로 노출한다. +따라서 이 항목은 core 승격 후보가 아니라 extension surface convention이다. + ## Anchor Lifecycle Core `trackPointer`는 patch 이후 Pointer를 추적한다. 그러나 comment, bookmark, @@ -310,14 +320,14 @@ delegation lens | Lab | Delegation | App-owned residue | Midcheck action | | --- | --- | --- | --- | -| `autosave` | partial | host save transport, scheduler, retry/offline/conflict policy가 큼 | coalescing/status는 위임됐지만 "autosave" 기대치에는 retry/backoff/offline profile 후보가 남음 | +| `autosave` | partial | host save transport, scheduler, retry/offline/conflict policy가 큼 | **lab 유지**. coalescing/status는 위임됐지만 "autosave" 기대치에는 retry/backoff/offline profile 후보가 남음 | | `batch-update` | strong | target selection, value/compute policy | 유지. batch atomicity, per-target patch, failure는 위임됨 | | `bookmarks` | strong | bookmark names, persistence, focus sync | 유지. pointer tracking/lost state는 위임됨 | | `checkpoints` | strong | persistence, retention, compare/restore UI | 유지. named snapshot/restore mechanics는 위임됨 | | `clear-contents` | mostly | ambiguous enum/object empty policy | 유지. schema-derived clear는 위임됐고 `emptyFor`는 product policy | | `convert-type` | strong | target type choice, locale-specific parsing beyond built-ins | 유지하되 command label은 `convert type` 후보 | | `sort-items` | mostly | comparator/sort key, rendered sort UI | 유지. array replacement, reverse, can/execute는 위임됨 | -| `calculated-fields` | partial | formula definitions, dependency graph, scheduling | deepen 후보. 현재는 sync boundary 위임이고 "computed fields" 전체는 아직 host가 많이 앎 | +| `calculated-fields` | partial | formula definitions, dependency graph, scheduling | **lab 유지**. 현재는 sync boundary 위임이고 "computed fields" 전체는 아직 host가 많이 앎 | | `convert-block-type` | mostly | kind descriptor, field preservation, default factory | 유지. conversion patch/failure는 위임됐고 schema-specific factory는 product policy | | `toggle-value` | strong | optional custom order via `values` | 유지. boolean/closed-set toggle-value mechanics는 위임됨 | | `dedupe` | mostly | duplicate key policy for objects | 유지. dedupe mechanics/atomicity는 위임됨 | @@ -335,7 +345,7 @@ delegation lens | `move-selected` | strong | source/target selection and focus | 유지. contiguous block move mechanics are delegated | | `increment-number` | strong | rendered spinner/unit/formatting | 유지. numeric step/clamp mechanics are delegated | | `pad-text` | strong | target choice, number formatting if needed | 유지. stored string padding mechanics are delegated | -| `paste-special` | partial | payload adaptation rules are the hard part and live in host adapter | deepen 후보. boundary/error preservation is delegated; common adapters may be needed for full feature delegation | +| `paste-special` | partial | payload adaptation rules are the hard part and live in host adapter | **lab 유지**. boundary/error preservation is delegated; common adapters may be needed for full feature delegation | | `live-cursors` | mostly | realtime transport, identity/color policy, timeout | 유지. remote anchor tracking over patches is delegated | | `references` | mostly | descriptor/readId/query policy, routing/remote lookup | 유지. indexing/backlink/set-reference mechanics are delegated | | `renumber-items` | strong | when reorder has happened, field name | 유지. order-field sync mechanics are delegated | @@ -349,9 +359,13 @@ delegation lens | `wrap-selection` | mostly | wrapper shape factory, product container policy | 유지. wrap/unwrap range mechanics are delegated | `partial`은 제거 판정이 아니다. 완전 위임이라는 제품 목표에서 다음에 깊게 만들 -후보라는 뜻이다. 현재 우선순위는 `calculated-fields`, `paste-special`, -`autosave`다. 세 package 모두 이름은 feature로 유효하지만, host callback이 -product policy 주입인지 feature 구현 위임 실패인지 더 확인해야 한다. +후보라는 뜻이다. + +1.0 결정: `calculated-fields`, `paste-special`, `autosave`는 아직 lab으로 +유지한다. Core API 변경은 없고, official 승격도 보류한다. 세 package 모두 이름은 +feature로 유효하지만, host callback이 product policy 주입인지 feature 구현 위임 +실패인지 더 확인해야 한다. 후속 작업은 승격 PR이 아니라 lab README와 recipe에서 +host-owned residue를 더 선명하게 만드는 audit이다. ## Semantic Contract Lock diff --git a/docs/standard/core-standard.md b/docs/standard/core-standard.md index 3d5ba254..02fb8f4e 100644 --- a/docs/standard/core-standard.md +++ b/docs/standard/core-standard.md @@ -11,9 +11,10 @@ headless JSON 편집 도구의 foundation 계약으로 쓰일 수 있는지를 `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, `MAY`는 규범 키워드다. -어떤 구현체가 json-document 호환이라고 주장하려면 이 문서와 적합성 -suite를 통과해야 한다. README와 사이트 문서는 사용법을 설명할 수 있지만, -의미론 계약의 기준은 이 문서다. +어떤 구현체가 json-document 호환이라고 주장하려면 이 문서와 +`docs/standard/conformance-profile.md`의 적합성 profile을 만족해야 한다. +README와 사이트 문서는 사용법을 설명할 수 있지만, 의미론 계약의 기준은 +standard 문서다. ## 2. 범위 @@ -233,6 +234,10 @@ adapter가 새 core concept을 요구한다면 public requirement, 기존 concep ## 14. 적합성 +1.0 적합성 기준은 `docs/standard/conformance-profile.md`가 정의한다. 이 +profile은 문서화된 profile이며, 1.0에서는 별도 npm package나 CLI runner를 +public artifact로 만들지 않는다. + 적합성 suite는 public package entrypoint에서만 import해야 한다. 적합성 suite는 정상 동작, 실패 동작, atomicity, JSON serializability, @@ -254,5 +259,5 @@ React `useJSONDocument` 초기값 overload처럼 사용자가 컴파일 시점 import해야 하며, implementation-private type이나 source path를 요구하면 안 된다. 일반 구현 테스트를 통과하는 것만으로는 표준 적합성을 주장할 수 없다. -json-document 호환 구현체는 implementation-private module 없이 적합성 suite를 -통과해야 한다. +json-document 호환 구현체는 implementation-private module 없이 conformance +profile을 만족해야 한다. diff --git a/docs/standard/extension-delegation-standard.md b/docs/standard/extension-delegation-standard.md index c5f2aae1..1f5e091f 100644 --- a/docs/standard/extension-delegation-standard.md +++ b/docs/standard/extension-delegation-standard.md @@ -277,6 +277,64 @@ extension은 React plugin이나 document plugin으로 등록되는 계층이 아 extension은 필요할 때 함수로 조립한다. 다만 official extension은 custom hook보다 더 엄격하게 concept boundary를 증명해야 한다. +### 4.6 Structural command result convention + +구조 편집 command는 JSON document의 모양, sibling order, group, outline, +range, grid-like region을 바꾼다. 이 계열은 core API를 새로 요구하지 않는다. +Core에는 이미 JSON Patch batch와 `commit(..., { selectionAfter })`가 있다. +따라서 extension은 같은 의미를 새 이름으로 다시 만들지 말고, 다음 어휘로 +수렴해야 한다. + +```ts +type StructuralCommandChange = { + operations: readonly JSONPatchOperation[]; + selectionAfter?: unknown; + diagnostics?: readonly unknown[]; +}; +``` + +| Field | 의미 | +| --- | --- | +| `operations` | 적용 예정 또는 적용한 JSON Patch batch | +| `selectionAfter` | command가 의미를 알고 있는 최종 headless selection | +| `diagnostics` | 실행을 막지는 않지만 host가 보여줄 수 있는 warning/info | + +Third-party extension은 이 convention을 `SHOULD`로 따른다. 이미 공개된 외부 +extension까지 강제로 깨뜨릴 수는 없기 때문이다. + +이 repo의 official extension과 lab extension은 이 convention을 `MUST`로 따른다. +1.0 전에 package 표면을 소급 적용할 수 있는 상태이므로, 같은 의미를 `patches`, +`nextSelection`, `warnings` 같은 별도 이름으로 새로 노출하면 안 된다. + +```txt +structural command +|-- plan/can 단계에서 operations를 노출한다 +|-- command가 다음 focus를 알면 selectionAfter를 노출한다 +|-- 실행을 막지 않는 정보는 diagnostics에 둔다 +`-- 실제 commit은 core doc.commit(..., { selectionAfter })를 사용한다 +``` + +`selectionAfter`는 DOM focus가 아니다. JSON Pointer, selection range input, +또는 `SelectionSnap`으로 복원할 수 있는 headless selection이다. Visual focus, +keyboard roving tabindex, scroll position은 host app 책임으로 남는다. + +`diagnostics`는 실패 result를 대체하지 않는다. 실행을 막는 문제는 stable `code`를 +가진 실패 result여야 한다. `diagnostics`는 import/paste/review처럼 host가 +사용자에게 보여줄 수 있는 비차단 정보를 보존하기 위한 field다. + +현재 repo audit 기준으로 다음 package들은 이미 convention에 맞는다. + +| 범주 | Package | +| --- | --- | +| official structural command | `grouping`, `outline`, `bulk-edit`, `proposed-changes` | +| lab structural command | `wrap-selection`, `move-selected`, `layer-order`, `fill-series`, `grid-range`, `paste-cells`, `batch-update`, `clear-contents`, `fill-blanks` | +| diagnostics convention | `paste-special`, `id-resolver`, `references` | + +`patch-preview`, `patch-log`, `persist-web`, `autosave`의 `applied`는 이 +structural command convention의 `operations`가 아니다. 이들은 이미 실행된 patch +record나 subscriber event를 기록하는 boundary이므로 result contract의 +`applied` 의미를 유지한다. + ## 5. MUST NOT gate 다음 중 하나에 해당하면 official extension으로 올리면 안 된다. diff --git a/docs/standard/foundation-gate.md b/docs/standard/foundation-gate.md index a2aefe2f..bc51e443 100644 --- a/docs/standard/foundation-gate.md +++ b/docs/standard/foundation-gate.md @@ -38,6 +38,7 @@ RFC급 foundation | 게이트 | 산출물 | 상태 | | --- | --- | --- | | 규범 표준 | `docs/standard/core-standard.md` | 초안 추가 | +| conformance profile | `docs/standard/conformance-profile.md` | 활성 | | result/error freeze | `docs/standard/result-contract.md` | 활성 | | selection freeze | `docs/standard/selection-contract.md` | 활성 | | schema introspection freeze | `docs/standard/schema-introspection-contract.md` | 활성 | diff --git a/labs/extensions/autosave/README.md b/labs/extensions/autosave/README.md index c077eddc..6009bb33 100644 --- a/labs/extensions/autosave/README.md +++ b/labs/extensions/autosave/README.md @@ -5,6 +5,15 @@ Lab autosave extension for `@interactive-os/json-document` documents. Use it to test whether autosave can stay outside core while using only the public document subscription and current value. +## 1.0 status + +1.0에서는 lab으로 유지한다. Core API 변경도 없고 official 승격도 보류한다. + +이 package가 맡는 책임은 valid document change를 구독하고 latest schema-valid +snapshot save를 coalesce하는 headless lifecycle이다. Retry, backoff, offline +queue, conflict resolution, durable transport, save UI는 제품 정책 차이가 크므로 +아직 official surface로 얼리지 않는다. + ```ts import { createAutoSave } from "@interactive-os/json-document-autosave"; diff --git a/labs/extensions/calculated-fields/README.md b/labs/extensions/calculated-fields/README.md index b8f0a096..a0fce3ef 100644 --- a/labs/extensions/calculated-fields/README.md +++ b/labs/extensions/calculated-fields/README.md @@ -5,6 +5,15 @@ Lab calculated field extension for `@interactive-os/json-document` documents. Use it to test whether formula-like derived values can stay outside core while still using public reads, schema checks, and patch execution. +## 1.0 status + +1.0에서는 lab으로 유지한다. Core API 변경도 없고 official 승격도 보류한다. + +이 package가 맡는 책임은 "현재 document를 읽어 host-defined computed value를 +schema-safe patch batch로 동기화한다"까지다. Formula language, dependency graph, +recalculation scheduler, circular dependency policy는 아직 product마다 다르게 +잡힐 가능성이 크므로 official surface로 얼리지 않는다. + ```ts import { createCalculatedFields } from "@interactive-os/json-document-calculated-fields"; diff --git a/labs/extensions/paste-special/README.md b/labs/extensions/paste-special/README.md index fcf7464f..066e8c01 100644 --- a/labs/extensions/paste-special/README.md +++ b/labs/extensions/paste-special/README.md @@ -5,6 +5,16 @@ Lab extension for paste special. Use it when a host receives a clipboard/import/drop payload that may need to be adapted before it can be inserted into the current document. +## 1.0 status + +1.0에서는 lab으로 유지한다. Core API 변경도 없고 official 승격도 보류한다. + +이 package가 맡는 책임은 external payload adaptation boundary, insert/replace +capability check, execution error preservation이다. 실제 payload parsing, +product-specific adapter rule, TSV/HTML/schema mapping, autocomplete UI는 아직 +host-owned로 남는다. 공통 adapter vocabulary가 더 수렴하기 전까지 official +surface로 얼리지 않는다. + ## Scope - let the host classify and adapt external payloads diff --git a/llms.txt b/llms.txt index 2738d206..e49651a1 100644 --- a/llms.txt +++ b/llms.txt @@ -37,7 +37,9 @@ import { createComments } from "@interactive-os/json-document-comments"; import { createWebClipboard } from "@interactive-os/json-document-clipboard-web"; ``` -Official extension은 현재 shipped `packages/*`만이다. `labs/extensions/*`는 후보이고 공식 package로 안내하지 않는다. +Official extension은 현재 shipped `packages/*`만이다. `labs/extensions/*`는 후보이고 공식 package로 안내하지 않는다. `calculated-fields`, `paste-special`, `autosave`는 1.0에서 lab 유지이며 official 승격을 보류한다. + +Structural command extension은 `operations`, `selectionAfter`, `diagnostics` 어휘로 수렴한다. 외부 extension에는 SHOULD convention이고, 이 repo의 official/lab에는 MUST convention이다. 이것은 core `JSONDocument` method 추가가 아니다. 다음 이름은 쓰지 않는다. @@ -68,6 +70,7 @@ schema -> document -> pointer/query -> can* -> change -> result - Result/error code: `docs/standard/result-contract.md` - Selection semantics: `docs/standard/selection-contract.md` - Schema introspection: `docs/standard/schema-introspection-contract.md` +- Conformance profile: `docs/standard/conformance-profile.md` - Signature/call shape: `packages/json-document/tests/public/signature-contract.test-d.ts` - Semantic fixture: `packages/json-document/tests/public/semantic-contract.test.ts` diff --git a/scripts/evaluate-standardization.mjs b/scripts/evaluate-standardization.mjs index 3e752bb2..2bb80414 100644 --- a/scripts/evaluate-standardization.mjs +++ b/scripts/evaluate-standardization.mjs @@ -17,6 +17,7 @@ function requirePattern(name, source, pattern) { } const standard = read("docs/standard/core-standard.md"); +const conformanceProfile = read("docs/standard/conformance-profile.md"); const foundationGate = read("docs/standard/foundation-gate.md"); const resultContract = read("docs/standard/result-contract.md"); const selectionContract = read("docs/standard/selection-contract.md"); @@ -47,6 +48,18 @@ for (const [label, pattern] of [ requirePattern("core standard", standard, pattern); } +for (const [label, pattern] of [ + ["documented profile", /1\.0의 conformance profile은 문서화된 profile/], + ["no runner package", /별도 npm package[\s\S]*CLI runner[\s\S]*1\.0 범위에 포함하지 않는다/], + ["public entrypoint", /public package entrypoint/], + ["profile artifacts", /public-contract\.json[\s\S]*signature-contract\.test-d\.ts[\s\S]*semantic-contract\.test\.ts[\s\S]*result-contract\.test\.ts[\s\S]*standard-conformance\.test\.ts/], + ["included semantics", /JSON Pointer[\s\S]*JSONPath[\s\S]*selectionAfter[\s\S]*clipboard[\s\S]*undo\/redo/], + ["excluded surfaces", /official extension[\s\S]*lab extension[\s\S]*DOM focus/], + ["breaking criteria", /breaking change[\s\S]*public export[\s\S]*error code[\s\S]*selectionAfter/], +]) { + requirePattern("conformance profile", conformanceProfile, pattern); +} + for (const token of [ "src/index.ts", "src/react.ts", @@ -63,6 +76,7 @@ for (const token of [ for (const [label, pattern] of [ ["foundation tree", /RFC급 foundation/], ["normative artifact", /core-standard\.md/], + ["conformance profile artifact", /conformance-profile\.md/], ["result freeze artifact", /result-contract\.md/], ["selection freeze artifact", /selection-contract\.md/], ["schema freeze artifact", /schema-introspection-contract\.md/],