sdoc-editor-cli 0.10.2 → 0.12.0

package/README.md

@@ -143,7 +143,7 @@ sdoc capabilities --human
   },
   "commands": ["capabilities", "inspect", "validate", "apply", "rename-heading", "set-document-title", "create"],
   "projections": ["catalog", "target", "section", "document"],
-  "catalogKinds": ["blocks", "outline", "references", "referenceables"],
+  "catalogKinds": ["blocks", "outline", "references", "referenceables", "endnotes"],
   "builtInTemplateIds": ["builtin:blank", "builtin:technical-report", "builtin:design-specification", "builtin:verification-report"]
 }
 ```
@@ -189,9 +189,18 @@ slash-delimited content path. For example, `/1/0` selects
 
 Copy `target.operationTarget` directly instead of assembling a snapshot
 target. Every `blocks[]` entry also includes its canonical `operationTarget`.
-Referenceable nodes receive an ID target; other blocks receive a snapshot
-target. A provisional ID is valid only for that inspected revision; applying
-it persists the ID.
+A block with a persistent ID receives an ID target. A non-referenceable block
+without one receives a snapshot target. Provisional IDs remain limited to
+referenceable nodes, are valid only for the inspected revision, and persist
+when applied. Inspection does not add IDs to the source document.
+
+Optional stable IDs are omitted when absent; `attrs.id: null` is invalid for
+these newly identity-bearing blocks. When present, newly authored stable IDs
+are non-empty Unicode strings of at most 128 code points and cannot use the
+reserved `provisional:` prefix. Korean and
+numeric-leading heading slugs are valid. Existing `.sdoc` 1.0 referenceable
+anchors remain loadable because that schema already allowed arbitrary strings;
+they are not silently migrated on inspect or save.
 
 An explicit `--projection` selects the additive bounded `sdoc.read/1`
 contract. Projected JSON still uses `contract: "sdoc.cli.response/1"` as its
@@ -228,6 +237,10 @@ projection. Catalog, section, and document results can return
 `page.complete` is true. Cursors bind the exact source bytes and query scope.
 They are opaque integrity tokens, not authentication credentials.
 
+The `endnotes` catalog reports canonical inline notes in body order as
+`id`, `number`, `body`, and `path`. Endnotes are inline content rather than
+operation block targets, and they do not enter the `referenceables` catalog.
+
 ### `validate`
 
 Checks the persisted document contract and semantic invariants without writing:
@@ -384,8 +397,15 @@ or revision-scoped provisional IDs:
 { "kind": "id", "id": "intro", "expectedType": "heading" }
 ```
 
-Other mutable blocks, including `paragraph`, `codeBlock`, and `diagram`, use a
-protected snapshot locator:
+Identity-bearing and referenceable are not synonyms. `paragraph`, `bulletList`,
+`orderedList`, `listItem`, `taskList`, `codeBlock`, `blockquote`, `callout`, and `diagram`
+may carry an optional stable `attrs.id`. When present, inspection exposes the
+persistent ID and returns an ID operation target, but the block does not enter
+the `referenceables` catalog and cannot be an xref target. No IDs are inserted
+automatically into existing documents.
+
+A mutable non-referenceable block without a persistent ID uses a protected
+snapshot locator:
 
 ```json
 {
@@ -397,8 +417,9 @@ protected snapshot locator:
 ```
 
 Prefer the ready-to-use `operationTarget` returned by `inspect` over copying
-these fields manually. A `diagram` is snapshot-targeted; it is not a
-persistent-ID node.
+these fields manually. For example, a `diagram` with `attrs.id` is ID-targeted;
+without one it is snapshot-targeted. In both cases it remains
+non-referenceable.
 
 Snapshot targets and provisional IDs are revision-scoped. Re-inspect after any
 source-byte change. A batch resolves all targets before applying its first
@@ -500,21 +521,29 @@ the operation-relevant node types and required attributes:
 | Nodes | Required attributes | Target kind and notes |
 |---|---|---|
 | `heading` | `attrs.level` (1-6) | ID target; rename with `renameHeading`, and move/delete as a complete section |
-| `paragraph`, `blockquote`, `bulletList`, `orderedList`, `taskList`, `taskItem` | None | Snapshot target |
-| `codeBlock` | None (`attrs.language` optional) | Snapshot target |
+| `paragraph`, `blockquote`, `bulletList`, `orderedList`, `listItem`, `taskList` | None (`attrs.id` optional) | ID target when `attrs.id` is present; otherwise snapshot target; not referenceable |
+| `taskItem` | None | Snapshot target |
+| `codeBlock` | None (`attrs.language` and `attrs.id` optional) | ID target when `attrs.id` is present; otherwise snapshot target; not referenceable |
 | `table` | None | ID target |
 | `tableCell`, `tableHeader` | None | Snapshot target; span, width, and alignment attrs are optional |
 | `image` | None | ID target; a new `src`, when present, must be portable |
 | `mathBlock` | `attrs.latex` | ID target |
-| `diagram` | `attrs.language`, `attrs.code` | Snapshot target; stores source such as Mermaid, PlantUML, or D2 |
-| `horizontalRule`, `hardBreak`, `callout` | None | Snapshot target; callout `variant` is optional |
-| `listItem`, `tableRow` | None | Structural container, not an operation block target |
+| `diagram` | `attrs.language`, `attrs.code` (`attrs.id` optional) | ID target when `attrs.id` is present; otherwise snapshot target; not referenceable; stores source such as Mermaid, PlantUML, or D2 |
+| `callout` | None (`attrs.variant` and `attrs.id` optional) | ID target when `attrs.id` is present; otherwise snapshot target; not referenceable |
+| `horizontalRule` | None | Snapshot target; a historical ASCII-shaped `attrs.id` is preserved and collision-reserved, but is not exposed as identity or xref anchor |
+| `hardBreak` | None | Snapshot target |
+| `tableRow` | None | Structural container, not an operation block target |
 | `text`, `mathInline` | `mathInline.attrs.latex` only | Inline content, not an operation target |
 
 `updateBlockAttrs` accepts only the attrs defined for that node type.
 `replaceBlock` must preserve the node type, while headings require the
 heading/section operations.
 
+Stable IDs may key provenance records in an external sidecar. Provenance is not
+part of the core `.sdoc` schema. The engineering-canonical profile tracked in
+#183 may build on this identity contract, but that profile is outside the CLI
+contract documented here.
+
 Portable image assets use `./images/...`. Draw.io content is an `image` node
 whose `src` is under `./drawio/` and ends in `.drawio.svg`; it is not a
 `diagram` node. The CLI validates document structure and portable references
@@ -612,7 +641,7 @@ must branch on `diagnostics[].code` from explicit `--json` output.
 | `INVALID_HEADING_LEVEL`, `SECTION_LEVEL_OUT_OF_RANGE` | A requested heading level is outside 1-6, or shifting the section would push a descendant outside that range | Choose a valid target level that keeps every descendant heading within 1-6 |
 | `FORMATTED_HEADING` | Replacing a rich heading would discard marks or inline nodes | Preserve it, or explicitly use `discardFormatting` / `--discard-formatting` |
 | `ATTRIBUTE_NOT_ALLOWED`, `NODE_TYPE_CHANGE` | An attr is not allowed for the node, or replacement changes its type | Consult the node catalog/schema and keep replacements type-compatible |
-| `ID_RENAME_NOT_SUPPORTED`, `ID_RENAME_REQUIRES_EXISTING_ID`, `INVALID_NEW_ID` | An ID rename targeted an unsupported or provisional node, or supplied an invalid new ID | Target an inspected heading/table with an existing persistent ID and choose a unique non-reserved ID |
+| `ID_RENAME_NOT_SUPPORTED`, `ID_RENAME_REQUIRES_EXISTING_ID`, `INVALID_NEW_ID` | An ID creation or rename targeted an unsupported/provisional node or supplied an invalid ID | For renames, target an inspected heading/table; choose a unique, bounded, non-reserved ID for renames and inserted sections |
 | `NEW_NONPORTABLE_ASSET`, `NEW_DANGLING_REFERENCE`, `NEW_UNSAFE_LINK` | The batch introduces an invalid asset path, missing internal target, or unsafe link | Use `./images/...` or `./drawio/*.drawio.svg`, create referenced IDs, and use a safe URL |
 | `DUPLICATE_ID` | The document contains conflicting persistent IDs | Assign unique IDs before retrying |
 | `CLI_TEMPLATE_INVALID` | An explicit template has malformed UTF-8, invalid JSON, or violates the template contract | Repair or re-encode the template as UTF-8; creation leaves the destination absent |

package/dist/schemas/sdoc.cli.response.schema.json

@@ -82,6 +82,7 @@
         "outline",
         "references",
         "referenceables",
+        "endnotes",
         "blocks",
         "blockCount",
         "blocksTruncated",
@@ -99,6 +100,7 @@
         "outline": { "type": "array" },
         "references": { "type": "array" },
         "referenceables": { "type": "array" },
+        "endnotes": { "type": "array" },
         "blocks": { "type": "array" },
         "blockCount": { "type": "integer", "minimum": 0 },
         "blocksTruncated": { "type": "boolean" },
@@ -139,7 +141,7 @@
       "type": "object",
       "required": ["kind", "items"],
       "properties": {
-        "kind": { "enum": ["blocks", "outline", "references", "referenceables"] },
+        "kind": { "enum": ["blocks", "outline", "references", "referenceables", "endnotes"] },
         "items": { "type": "array", "items": { "type": "object" } }
       },
       "additionalProperties": true
@@ -421,7 +423,7 @@
           "type": "array",
           "minItems": 1,
           "uniqueItems": true,
-          "items": { "enum": ["blocks", "outline", "references", "referenceables"] }
+          "items": { "enum": ["blocks", "outline", "references", "referenceables", "endnotes"] }
         },
         "builtInTemplateIds": {
           "type": "array",

package/dist/schemas/sdoc.operations.schema.json

@@ -16,6 +16,13 @@
   },
   "additionalProperties": false,
   "definitions": {
+    "authoredPersistentId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "not": { "pattern": "^provisional:" },
+      "description": "A non-empty Unicode ID of at most 128 code points outside the reserved provisional: namespace."
+    },
     "sha256": {
       "type": "string",
       "pattern": "^sha256:[0-9a-f]{64}$"
@@ -128,7 +135,7 @@
         "op": { "const": "insertSection" },
         "target": { "$ref": "#/definitions/target" },
         "title": { "type": "string" },
-        "id": { "type": "string" },
+        "id": { "$ref": "#/definitions/authoredPersistentId" },
         "position": { "enum": ["child", "before", "after"] },
         "blocks": {
           "type": "array",
@@ -201,12 +208,7 @@
       "properties": {
         "op": { "const": "renameBlockId" },
         "target": { "$ref": "#/definitions/target" },
-        "newId": {
-          "type": "string",
-          "minLength": 1,
-          "maxLength": 128,
-          "not": { "pattern": "^provisional:" }
-        }
+        "newId": { "$ref": "#/definitions/authoredPersistentId" }
       },
       "additionalProperties": false
     },

package/dist/schemas/sdoc.read.schema.json

@@ -55,7 +55,7 @@
       "properties": {
         "contract": { "const": "sdoc.read/1" },
         "projection": { "const": "catalog" },
-        "kind": { "enum": ["blocks", "outline", "references", "referenceables"] },
+        "kind": { "enum": ["blocks", "outline", "references", "referenceables", "endnotes"] },
         "limit": { "type": "integer", "minimum": 1, "maximum": 10000 },
         "cursor": { "$ref": "#/definitions/cursor" },
         "maxBytes": { "type": "integer", "minimum": 1, "maximum": 33554432 },

package/dist/schemas/sdoc.schema.json

@@ -78,6 +78,25 @@
       "additionalProperties": false
     },
 
+    "legacyReferenceId": {
+      "type": ["string", "null"],
+      "description": "Backward-compatible cross-reference anchor. Existing .sdoc 1.0 documents allowed any string; newly authored IDs should follow stableId."
+    },
+
+    "stableId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "not": { "pattern": "^provisional:" },
+      "description": "Optional stable block identity. Omit attrs.id when absent; when present, authored values are non-empty strings of at most 128 Unicode code points and cannot use the reserved provisional: namespace."
+    },
+
+    "historicalHorizontalRuleId": {
+      "type": ["string", "null"],
+      "pattern": "^[A-Za-z][A-Za-z0-9._:-]*$",
+      "description": "Historical horizontal-rule ID shape retained for .sdoc 1.0 compatibility; it is collision-reserved but is not an operation identity or cross-reference anchor."
+    },
+
     "docNode": {
       "type": "object",
       "required": ["type"],
@@ -114,6 +133,7 @@
       "oneOf": [
         { "$ref": "#/definitions/textNode" },
         { "$ref": "#/definitions/mathInlineNode" },
+        { "$ref": "#/definitions/endnoteNode" },
         { "$ref": "#/definitions/hardBreakNode" }
       ]
     },
@@ -128,7 +148,7 @@
           "required": ["level"],
           "properties": {
             "level": { "type": "integer", "minimum": 1, "maximum": 6 },
-            "id": { "type": ["string", "null"], "description": "Anchor id for cross-references." },
+            "id": { "$ref": "#/definitions/legacyReferenceId" },
             "textAlign": { "type": ["string", "null"], "enum": ["left", "center", "right", "justify", null] },
             "numbered": { "type": ["boolean", "null"], "description": "false면 자동 번호 매김에서 제외 (예: Introduction, Glossary, References). 생략 또는 null이면 번호 매김 대상." }
           },
@@ -150,7 +170,8 @@
         "attrs": {
           "type": "object",
           "properties": {
-            "textAlign": { "type": ["string", "null"], "enum": ["left", "center", "right", "justify", null] }
+            "textAlign": { "type": ["string", "null"], "enum": ["left", "center", "right", "justify", null] },
+            "id": { "$ref": "#/definitions/stableId" }
           },
           "additionalProperties": false
         },
@@ -167,6 +188,13 @@
       "required": ["type"],
       "properties": {
         "type": { "const": "bulletList" },
+        "attrs": {
+          "type": "object",
+          "properties": {
+            "id": { "$ref": "#/definitions/stableId" }
+          },
+          "additionalProperties": false
+        },
         "content": {
           "type": "array",
           "items": { "$ref": "#/definitions/listItemNode" }
@@ -184,7 +212,8 @@
           "type": "object",
           "properties": {
             "start": { "type": ["integer", "null"], "default": 1 },
-            "type": { "type": ["string", "null"] }
+            "type": { "type": ["string", "null"] },
+            "id": { "$ref": "#/definitions/stableId" }
           },
           "additionalProperties": false
         },
@@ -201,6 +230,13 @@
       "required": ["type"],
       "properties": {
         "type": { "const": "listItem" },
+        "attrs": {
+          "type": "object",
+          "properties": {
+            "id": { "$ref": "#/definitions/stableId" }
+          },
+          "additionalProperties": false
+        },
         "content": {
           "type": "array",
           "items": { "$ref": "#/definitions/blockNode" }
@@ -214,6 +250,13 @@
       "required": ["type"],
       "properties": {
         "type": { "const": "taskList" },
+        "attrs": {
+          "type": "object",
+          "properties": {
+            "id": { "$ref": "#/definitions/stableId" }
+          },
+          "additionalProperties": false
+        },
         "content": {
           "type": "array",
           "items": { "$ref": "#/definitions/taskItemNode" }
@@ -249,7 +292,8 @@
         "attrs": {
           "type": "object",
           "properties": {
-            "language": { "type": ["string", "null"] }
+            "language": { "type": ["string", "null"] },
+            "id": { "$ref": "#/definitions/stableId" }
           },
           "additionalProperties": false
         },
@@ -272,7 +316,7 @@
             "caption": { "type": ["string", "null"], "description": "Table caption text." },
             "align": { "type": "string", "enum": ["left", "center", "right"], "default": "left" },
             "width": { "type": "string", "description": "CSS width value (e.g., '100%', '50%', 'auto').", "default": "auto" },
-            "id": { "type": ["string", "null"], "description": "Anchor id for cross-references." }
+            "id": { "$ref": "#/definitions/legacyReferenceId" }
           },
           "additionalProperties": false
         },
@@ -363,7 +407,7 @@
             "align": { "type": "string", "enum": ["left", "center", "right"], "default": "center" },
             "width": { "type": ["string", "number", "null"] },
             "height": { "type": ["string", "number", "null"] },
-            "id": { "type": ["string", "null"], "description": "Anchor id for cross-references." }
+            "id": { "$ref": "#/definitions/legacyReferenceId" }
           },
           "additionalProperties": false
         }
@@ -381,7 +425,7 @@
           "required": ["latex"],
           "properties": {
             "latex": { "type": "string", "description": "LaTeX math expression." },
-            "id": { "type": ["string", "null"], "description": "Anchor id for cross-references." }
+            "id": { "$ref": "#/definitions/legacyReferenceId" }
           },
           "additionalProperties": false
         }
@@ -406,6 +450,28 @@
       "additionalProperties": false
     },
 
+    "endnoteNode": {
+      "type": "object",
+      "required": ["type", "attrs"],
+      "properties": {
+        "type": { "const": "endnote" },
+        "attrs": {
+          "type": "object",
+          "required": ["id", "body"],
+          "properties": {
+            "id": { "$ref": "#/definitions/stableId" },
+            "body": {
+              "type": "string",
+              "pattern": "^[^\\r\\n]*$",
+              "description": "Single-line plain-text endnote body. The document-end list is derived from this canonical value."
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+
     "diagramNode": {
       "type": "object",
       "required": ["type"],
@@ -416,7 +482,8 @@
           "required": ["language", "code"],
           "properties": {
             "language": { "type": "string", "description": "Diagram language, e.g. mermaid, plantuml, d2." },
-            "code": { "type": "string", "description": "Diagram source code." }
+            "code": { "type": "string", "description": "Diagram source code." },
+            "id": { "$ref": "#/definitions/stableId" }
           },
           "additionalProperties": false
         }
@@ -441,10 +508,7 @@
         "attrs": {
           "type": "object",
           "properties": {
-            "id": {
-              "type": ["string", "null"],
-              "pattern": "^[A-Za-z][A-Za-z0-9._:-]*$"
-            }
+            "id": { "$ref": "#/definitions/historicalHorizontalRuleId" }
           },
           "additionalProperties": false
         }
@@ -457,6 +521,13 @@
       "required": ["type"],
       "properties": {
         "type": { "const": "blockquote" },
+        "attrs": {
+          "type": "object",
+          "properties": {
+            "id": { "$ref": "#/definitions/stableId" }
+          },
+          "additionalProperties": false
+        },
         "content": {
           "type": "array",
           "items": { "$ref": "#/definitions/blockNode" }
@@ -477,7 +548,8 @@
               "type": "string",
               "enum": ["note", "info", "tip", "warning", "danger"],
               "description": "Visual style of the callout block."
-            }
+            },
+            "id": { "$ref": "#/definitions/stableId" }
           },
           "additionalProperties": false
         },