git-span 1.1.26 → 1.1.28

package/README.md

@@ -61,6 +61,25 @@ Install integrations separately after putting `git span` on `PATH`. See [git-spa
 
 Commands with `--format json` provide machine-readable output. `git span context <address>... --format json` returns an exact repository snapshot for paths and inclusive line ranges, including selected spans, whys, current status, and resolver sources. Published JSON Schemas and their contracts are documented at [git-span.com](https://git-span.com).
 
+## Commit-associated JSON notes
+
+Attach arbitrary supporting JSON to a commit and consume records by their sequential IDs:
+
+```bash
+git span notes add HEAD '{"session_id":"session-42"}'
+git span notes add HEAD < metadata.json
+git span notes list main..feature --format json
+git span notes list HEAD --exact --format json
+git span notes show 1 --format json
+git span notes remove 1 --format json
+```
+
+Every leaf accepts `--format human|json`. Machine output is a schema-version 1 envelope with `operation` and an ascending `notes` array; each record contains numeric `id`, full `commit_sha`, and parsed `document`. Empty lists contain `notes: []`; add/show/remove return one record, including the deleted record for removal.
+
+Notes remain in the clone's shared Git directory until removed, independently of resolver-cache maintenance. IDs are atomic across worktrees, never reused, and bounded to JavaScript-safe positive integers. Retrying identical JSON on the same commit returns its existing ID: object key order and decoded string escapes do not matter, arrays retain order, and the parser's arbitrary-precision numeric representation is significant (`1` differs from `1.0`). The full commit association survives branch movement.
+
+Input accepts one UTF-8 JSON value from an argument or nonterminal stdin, up to 16 MiB with bounded nesting. Invalid/conflicting input, ambiguous or noncommit revisions, missing IDs, and incompatible/corrupt storage fail without a success result. Notes provide local storage and Git selection; clients own processing and there is no remote synchronization. See the [command reference](https://git-span.com/docs/commands#notes-add) for the complete contract.
+
 ## Documentation
 
 - [git-span.com](https://git-span.com) — installation, concepts, command reference, agent integration, and CI guidance

package/man/git-span.1

@@ -1,7 +1,7 @@
 .\" GENERATED by gen-manpage. Do not edit by hand.
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
-.TH git-span 1  "git-span 1.1.26"
+.TH git-span 1  "git-span 1.1.28"
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH NAME
@@ -98,6 +98,9 @@ Print version
 .el .ds Aq '
 .SH SUBCOMMANDS
 .TP
+git\-span\-notes(1)
+Attach, inspect, and remove durable arbitrary JSON documents associated with commits
+.TP
 git\-span\-show(1)
 Show the named span — its anchors, why, and config. The bare `git span <name>` positional form is equivalent to `git span show <name>`
 .TP
@@ -148,7 +151,41 @@ Print this message or the help of the given subcommand(s)
 .ie \n(.g .ds Aq \(aq
 .el .ds Aq '
 .SH VERSION
-v1.1.26
+v1.1.28
+.SH COMMIT-ASSOCIATED JSON NOTES
+.B git span notes add <git-ref> [<json>] [--format human|json]
+attaches one arbitrary UTF-8 JSON value to an unambiguous commit, peeling annotated tags.
+Omit the JSON argument to read nonterminal stdin. Missing terminal input, empty or
+invalid JSON, excessive nesting, input over 16 MiB, and nonempty stdin combined with
+an argument fail before storage mutation. Tree/blob objects and options are refused.
+.PP
+.B git span notes list [<git-ref>] [--exact] [--format human|json]
+returns records by ascending ID. Without a revision it includes unreachable commits;
+a tip selects reachable history, and two-dot/three-dot ranges use native Git sets,
+including omitted-endpoint HEAD defaults. Exact mode requires one revision.
+.PP
+.B git span notes show <note-id> [--format human|json]
+returns one document and its full SHA association.
+.B git span notes remove <note-id> [--format human|json]
+deletes only that ID and returns the deleted record. Missing/invalid IDs fail.
+.PP
+Each new ID is a repository-wide positive integer through 9007199254740991,
+allocated atomically across worktrees, never reused after removal or restart.
+Retrying an identical still-present document on the same SHA returns its existing ID.
+Identity sorts object keys, decodes strings, preserves array order and arbitrary-precision
+parsed numeric representation (1 differs from 1.0); parser-normalized exponent spellings
+agree and duplicate object keys use their last value. Associations use frozen full SHAs.
+.PP
+JSON output is one schema_version 1 envelope with operation and notes fields.
+Every note has numeric id, full commit_sha, and parsed document.
+Add/show/remove return one record; empty lists return an empty notes array.
+Human is the default format. Storage/selection failures emit no JSON success.
+.PP
+Notes remain at <git-common-dir>/span/notes.db until explicitly removed,
+independent of disposable resolver cache state and span-root settings.
+Corrupt, foreign, or incompatible storage is left intact and refused;
+lock contention fails after a 30-second busy timeout. There is no migration,
+remote synchronization, native Git-notes interchange, or processing lifecycle.
 .SH EXAMPLES
 Anchor a new span alongside a code change:
 .PP
@@ -187,6 +224,19 @@ git span billing/charge-request-contract
 git span show billing/charge-request-contract
 .fi
 .RE
+.PP
+Attach and consume a commit-associated JSON record:
+.PP
+.RS 4
+.nf
+git span notes add HEAD '{"session_id":"session-42"}'
+git span notes add HEAD < metadata.json
+git span notes list main..feature --format json
+git span notes list HEAD --exact --format json
+git span notes show 1 --format json
+git span notes remove 1 --format json
+.fi
+.RE
 .SH SEE ALSO
 .BR git (1),
 .BR gitcli (7)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-span",
-  "version": "1.1.26",
+  "version": "1.1.28",
   "bin": "bin/git-span.exe",
   "man": [
     "man/git-span.1"
@@ -27,11 +27,11 @@
     "scripts/postinstall.js"
   ],
   "optionalDependencies": {
-    "git-span-darwin-arm64": "1.1.26",
-    "git-span-darwin-x64": "1.1.26",
-    "git-span-linux-arm64": "1.1.26",
-    "git-span-linux-x64": "1.1.26",
-    "git-span-win32-x64": "1.1.26"
+    "git-span-darwin-arm64": "1.1.28",
+    "git-span-darwin-x64": "1.1.28",
+    "git-span-linux-arm64": "1.1.28",
+    "git-span-linux-x64": "1.1.28",
+    "git-span-win32-x64": "1.1.28"
   },
   "repository": {
     "type": "git",