@stackline/stable-stringify 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes are documented here. This project follows Semantic
 Versioning.
 
+## [1.0.2] - 2026-08-21
+
+### Added
+
+- Executable examples for deterministic cache keys, RFC 8785 content digests,
+  and bounded cyclic logging.
+- Adoption guidance for direct installs, npm aliases, safe diagnostics, and
+  canonical signatures.
+- Reproducible benchmark methodology and Stackline package catalog link.
+- First-party documentation analytics that never records serialized input.
+- Trusted-publishing workflow for provenance-enabled future releases.
+
+### Changed
+
+- Package tarballs now include the public guides and executable examples.
+
+No runtime API or declaration behavior changed in this release.
+
 ## [1.0.1] - 2026-08-16
 
 ### Fixed
@@ -32,3 +50,4 @@ Versioning.
 
 [1.0.1]: https://github.com/alexandroit/stackline-stable-stringify/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/alexandroit/stackline-stable-stringify/releases/tag/v1.0.0
+[1.0.2]: https://github.com/alexandroit/stackline-stable-stringify/compare/v1.0.1...v1.0.2

package/README.md

@@ -264,6 +264,16 @@ on the same payload. Native JSON is shown only as a throughput baseline; it
 does not recursively sort object keys. Measure with representative production
 data before selecting limits or modes.
 
+## Adoption resources
+
+- [Stable, safe, canonical, and drop-in adoption guide](docs/ADOPTION.md)
+- [Reproducible benchmark methodology](docs/BENCHMARKS.md)
+- [Executable examples](examples)
+- [Stackline open-source catalog](https://alexandro.net/docs/open-source/)
+
+The examples ship in the npm tarball and cover deterministic cache keys,
+canonical content digests, and bounded logging of cyclic BigInt data.
+
 ## Verification
 
 Every release runs:

package/dist/index.cjs

@@ -1,4 +1,4 @@
-/*! @stackline/stable-stringify v1.0.1 | MIT */
+/*! @stackline/stable-stringify v1.0.2 | MIT */
 var StacklineStableStringifyModule = (() => {
   var __defProp = Object.defineProperty;
   var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/index.js

@@ -1,4 +1,4 @@
-/*! @stackline/stable-stringify v1.0.1 | MIT */
+/*! @stackline/stable-stringify v1.0.2 | MIT */
 
 // src/index.js
 var hasOwn = Object.prototype.hasOwnProperty;

package/dist/index.min.js

@@ -1,4 +1,4 @@
-/*! @stackline/stable-stringify v1.0.1 | MIT */
+/*! @stackline/stable-stringify v1.0.2 | MIT */
 var StacklineStableStringifyModule=(()=>{var b=Object.defineProperty;var k=Object.getOwnPropertyDescriptor;var P=Object.getOwnPropertyNames;var F=Object.prototype.hasOwnProperty;var V=(e,n)=>{for(var t in n)b(e,t,{get:n[t],enumerable:!0})},_=(e,n,t,r)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of P(n))!F.call(e,o)&&o!==t&&b(e,o,{get:()=>n[o],enumerable:!(r=k(n,o))||r.enumerable});return e};var R=e=>_(b({},"__esModule",{value:!0}),e);var ue={};V(ue,{CanonicalizationError:()=>s,StableStringifyLimitError:()=>f,canonicalize:()=>N,canonicalizeBytes:()=>I,configure:()=>C,default:()=>se,safeStringify:()=>E,stableStringify:()=>u,stringify:()=>M});var U=Object.prototype.hasOwnProperty,B=Object.prototype.propertyIsEnumerable,v=Object.prototype.toString,m=Symbol("omit"),x=null,w=Object.freeze({bigint:"string",cycleValue:"[Circular]",maxDepth:100,maxEntries:1e5,maxLength:1e6,onCycle:"marker"}),S=Object.freeze({maxDepth:1e3,maxEntries:1e5,maxLength:16*1024*1024}),f=class extends RangeError{constructor(n,t,r){let o=h(r);super(`Stable stringify ${n} limit of ${t} exceeded at ${o}`),this.name="StableStringifyLimitError",this.code="ERR_STABLE_STRINGIFY_LIMIT",this.kind=n,this.limit=t,this.path=o}},s=class extends TypeError{constructor(n,t){let r=h(t);super(`JSON canonicalization failed at ${r}: ${n}`),this.name="CanonicalizationError",this.code="ERR_JSON_CANONICALIZATION",this.path=r,this.reason=n}};function u(e,n){let t=$(n);return A(e,t,!1)}var M=u;function C(e){let n=typeof e=="function"?{cmp:e}:y(e);return $(n),function(r,o){let i=typeof o=="function"?{cmp:o}:y(o);return u(r,{...n,...i})}}function E(e,n,t,r){let o=y(r),i={...w,...o,maxDepth:o.maxDepth===void 0?o.depthLimit:o.maxDepth,maxEntries:o.maxEntries===void 0?o.edgesLimit:o.maxEntries,replacer:n===void 0?o.replacer:n,space:t===void 0?o.space:t};i.maxDepth===void 0&&(i.maxDepth=w.maxDepth),i.maxEntries===void 0&&(i.maxEntries=w.maxEntries);try{return u(e,i)}catch(c){if(o.throwOnError===!0)throw c;let l="UnknownError";try{c&&typeof c.name=="string"&&(l=c.name.slice(0,80))}catch(ae){}return JSON.stringify(`[Unable to serialize: ${l}]`)}}function N(e,n){let t=re(n);return A(e,t,!0)}function I(e,n){return ce(N(e,n))}function A(e,n,t){let r={ancestors:new WeakMap,canonical:t,chunks:[],entries:0,length:0,options:n},i=O(e,{"":e},"",x,r);if(i===m)return;let c=[{depth:0,path:x,prepared:i,type:"value"}];for(;c.length>0;){let l=c.pop();l.type==="value"?Z(l,c,r):G(l,c,r)}return r.chunks.join("")}function Z(e,n,t){if(e.prepared.kind==="primitive"){a(t,e.prepared.text,e.path);return}let r=e.prepared.value,o=t.ancestors.get(r);if(o!==void 0||t.ancestors.has(r)){ne(t,o,e.path);return}te(t,e.depth,e.path);let i=Array.isArray(r);t.canonical&&(ee(r,e.path),i||X(r,e.path)),t.ancestors.set(r,e.path);let c=W(r,i,e.depth,e.path,t);if(a(t,i?"[":"{",e.path),c.total===0){a(t,i?"]":"}",e.path),t.ancestors.delete(r);return}n.push(c)}function G(e,n,t){if(e.index>=e.total){e.emitted&&t.options.gap!==""&&a(t,`
 ${e.indent}`,e.path),a(t,e.isArray?"]":"}",e.path),t.ancestors.delete(e.value);return}if(e.isArray){let r=e.index;e.index+=1;let o=g(e.path,r);L(t,o);let i=q(e.value,r,o,t),c=O(i,e.value,String(r),o,t);c===m&&(c=p("null")),J(e,o,t),n.push(e),n.push({depth:e.depth+1,path:o,prepared:c,type:"value"});return}for(;e.index<e.total;){let r=e.keys[e.index];e.index+=1;let o=g(e.path,r);L(t,o);let i=Q(e.value,r,o,t),c=O(i,e.value,r,o,t);if(c!==m){J(e,o,t),a(t,JSON.stringify(r),o),a(t,t.options.gap===""?":":": ",o),n.push(e),n.push({depth:e.depth+1,path:o,prepared:c,type:"value"});return}}n.push(e)}function W(e,n,t,r,o){let i,c;return n?c=e.length:(i=H(e,r,o),c=i.length),{depth:t,emitted:!1,indent:o.options.gap===""?"":o.options.gap.repeat(t),index:0,isArray:n,keys:i,path:r,total:c,type:"container",value:e}}function H(e,n,t){let r;if(t.canonical||t.options.propertyList===void 0?r=Object.keys(e):r=t.options.propertyList.slice(),t.canonical){for(let o of r)if(z(o))throw new s("property names must not contain lone UTF-16 surrogates",g(n,o));return r.sort()}if(t.options.accessors!=="invoke"&&(r=r.filter(o=>{let i=Object.getOwnPropertyDescriptor(e,o);if(!i||!i.get&&!i.set)return!0;if(t.options.accessors==="throw")throw new TypeError(`Refusing to invoke accessor at ${h(g(n,o))}`);return!1})),t.options.cmp){let o=t.options.cmp;r.sort((i,c)=>o({key:i,value:T(e,i,n,t)},{key:c,value:T(e,c,n,t)}))}else r.sort();return r}function O(e,n,t,r,o){if(o.canonical)return K(e,r);let i=e;if(o.options.toJSON&&i!==null&&i!==void 0){let c=i.toJSON;typeof c=="function"&&(i=c.call(i))}if(o.options.replacerFunction&&(i=o.options.replacerFunction.call(n,t,i)),i===null)return p("null");switch(typeof i){case"string":return p(JSON.stringify(i));case"number":return p(Number.isFinite(i)?String(i):"null");case"boolean":return p(i?"true":"false");case"bigint":return Y(i,o.options.bigint,r);case"object":return{kind:"object",value:i};default:return m}}function K(e,n){if(e===null)return p("null");switch(typeof e){case"string":if(z(e))throw new s("strings must not contain lone UTF-16 surrogates",n);return p(JSON.stringify(e));case"number":if(!Number.isFinite(e))throw new s("NaN and Infinity are not valid I-JSON numbers",n);return p(JSON.stringify(e));case"boolean":return p(e?"true":"false");case"object":return{kind:"object",value:e};case"bigint":throw new s("BigInt values must be represented as JSON strings",n);default:throw new s(`values of type ${typeof e} are not valid JSON data`,n)}}function Y(e,n,t){if(n==="string")return p(JSON.stringify(String(e)));if(n==="number"){let r=Number(e);if(!Number.isSafeInteger(r))throw new RangeError(`BigInt at ${h(t)} cannot be represented as a safe JSON number`);return p(String(r))}throw new TypeError("Do not know how to serialize a BigInt")}function p(e){return{kind:"primitive",text:e}}function q(e,n,t,r){if(r.canonical){if(!U.call(e,n))throw new s("sparse arrays are not valid I-JSON data",t);return D(e,String(n),t)}return j(e,String(n),t,r.options.accessors)}function Q(e,n,t,r){return r.canonical?D(e,n,t):j(e,n,t,r.options.accessors)}function D(e,n,t){let r=Object.getOwnPropertyDescriptor(e,n);if(!r||r.get||r.set)throw new s("accessor properties are not valid canonical JSON input",t);return r.value}function j(e,n,t,r){if(r==="invoke")return e[n];let o=new WeakSet,i=e;for(;i!==null&&!o.has(i);){o.add(i);let c=Object.getOwnPropertyDescriptor(i,n);if(c){if(!c.get&&!c.set)return c.value;if(r==="throw")throw new TypeError(`Refusing to invoke accessor at ${h(t)}`);return}i=Object.getPrototypeOf(i)}}function T(e,n,t,r){return j(e,n,g(t,n),r.options.accessors)}function X(e,n){let t=Object.getPrototypeOf(e);if(t!==null&&Object.getPrototypeOf(t)!==null)throw new s("class instances must be converted to plain JSON objects",n)}function ee(e,n){if(typeof Object.getOwnPropertySymbols!="function")return;if(Object.getOwnPropertySymbols(e).some(r=>B.call(e,r)))throw new s("symbol properties are not valid JSON object members",n)}function J(e,n,t){if(t.options.gap==="")e.emitted&&a(t,",",n);else{let r=t.options.gap.repeat(e.depth+1);a(t,e.emitted?`,
 ${r}`:`

package/docs/ADOPTION.md

@@ -0,0 +1,37 @@
+# Adoption Guide
+
+## Stable cache keys
+
+Use the default export when object insertion order must not change a cache key,
+snapshot, deduplication identifier, or content hash.
+
+```js
+import stringify from '@stackline/stable-stringify';
+
+const key = stringify({ tenant: 42, query: { status: 'open' } });
+```
+
+## Drop-in package alias
+
+Applications already using `fast-json-stable-stringify` can preserve their
+imports:
+
+```bash
+npm uninstall fast-json-stable-stringify
+npm install fast-json-stable-stringify@npm:@stackline/stable-stringify
+```
+
+Commit the lockfile and run the complete application suite. The default call
+shape and comparator contract are covered by differential compatibility tests.
+
+## Safe diagnostics
+
+Use `safeStringify` for logs and error paths that can contain cycles, BigInt,
+getters, or deeply nested data. Its bounded defaults keep diagnostic output
+from becoming another failure source.
+
+## Cryptographic canonicalization
+
+Use `canonicalize` or `canonicalizeBytes` only when strict RFC 8785 behavior is
+required. Canonical mode intentionally rejects values outside its I-JSON
+contract instead of silently applying safe-logging policies.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,103 @@
+# Architecture
+
+## Scope
+
+The runtime converts a JavaScript value into deterministic JSON text through
+three policy surfaces:
+
+- stable mode for compatibility and cache or snapshot keys;
+- safe mode for bounded diagnostics and logs;
+- canonical mode for RFC 8785 interoperable bytes.
+
+All modes share one iterative serialization engine and have zero runtime
+dependencies.
+
+## Iterative task stack
+
+Recursive serializers fail when object depth exceeds the JavaScript call-stack
+limit. This implementation prepares a root value and processes explicit
+`value` and `container` tasks in a loop. A container frame stores its key list,
+index, depth, indentation, path, and emission state.
+
+The approach makes nesting depth a policy decision instead of a runtime stack
+accident. Stable mode is tested with 25,000 nested arrays. Safe and canonical
+modes intentionally apply finite defaults.
+
+## Preparation and emission
+
+Each value goes through preparation before output:
+
+1. stable mode optionally invokes `toJSON` and a replacer;
+2. the value is classified as primitive, container, or omitted;
+3. object keys are selected and sorted;
+4. descriptors or accessors are read according to policy;
+5. text chunks are appended while enforcing the output budget.
+
+Arrays preserve order. Unsupported stable-mode array items become `null`,
+matching JSON semantics. Unsupported object members are omitted.
+
+## Cycle detection
+
+An operation-scoped `WeakMap` tracks active ancestors and their paths. Entries
+are removed when a container closes, so repeated sibling references are not
+misclassified as cycles. The current ancestor path supports strict errors,
+markers, null substitution, and descriptive path markers.
+
+No graph is retained after serialization.
+
+## Stable mode
+
+Stable mode sorts own enumerable string keys by UTF-16 code units. A comparator
+can instead order `{ key, value }` records. Property-list replacers are
+normalized once, deduplicated, and applied at every object depth.
+
+Compatibility defaults intentionally leave depth, entry, and length budgets
+unlimited. BigInt throws, accessors and `toJSON` are invoked, and cycles throw
+unless configured otherwise.
+
+## Safe mode
+
+Safe mode delegates to the same engine with cycle markers, BigInt strings, and
+finite budgets. It catches traversal failures and returns a controlled JSON
+string unless `throwOnError` is enabled. This prevents the diagnostic path from
+hiding the original application error behind a second serialization error.
+
+## Canonical mode
+
+Canonical mode validates I-JSON data while traversing:
+
+- keys use recursive UTF-16 ordering required by RFC 8785;
+- numbers and strings use ECMAScript JSON serialization;
+- malformed Unicode and non-finite numbers are rejected;
+- only arrays, plain objects, and null-prototype objects are accepted;
+- data descriptors are read without invoking accessors;
+- symbols, cycles, sparse arrays, and non-JSON values are rejected;
+- output contains no insignificant whitespace.
+
+`canonicalizeBytes` encodes the resulting string as UTF-8. It uses
+`TextEncoder` where available and includes a small standards-compatible
+fallback for older environments.
+
+## Resource accounting
+
+The engine tracks:
+
+- container depth;
+- visited object keys and array positions;
+- UTF-16 output length.
+
+Limit errors include a structured kind, configured limit, and a path such as
+`<root>.request.headers` or `<root>.items[4]`.
+
+## Distribution
+
+One source module builds to:
+
+- `dist/index.js` for ESM;
+- `dist/index.cjs` for callable CommonJS;
+- `dist/index.min.js` for the `StacklineStableStringify` browser global;
+- resolver-specific `.d.mts`, `.d.cts`, and `.d.ts` declarations;
+- source maps for every JavaScript artifact.
+
+The build banner identifies package version and MIT license. Package tests load
+all three JavaScript forms and execute the browser artifact in an isolated VM.

package/docs/BENCHMARKS.md

@@ -0,0 +1,25 @@
+# Benchmark Methodology
+
+The benchmark runs native `JSON.stringify`,
+`fast-json-stable-stringify@2.1.0`, stable mode, safe mode, and RFC 8785 mode
+against the same representative payload in one Node.js process.
+
+```bash
+npm ci
+npm run benchmark
+```
+
+Control the sample size with `BENCHMARK_ITERATIONS`:
+
+```bash
+BENCHMARK_ITERATIONS=250000 npm run benchmark
+```
+
+Native JSON is a throughput baseline only. It does not recursively sort object
+keys and is not behaviorally equivalent. Stable, safe, and canonical modes
+also implement different contracts, so compare a mode only with alternatives
+that provide the same guarantees.
+
+When publishing results, include the command, Node.js version, CPU, complete
+raw output, and payload shape. Do not present one machine's result as a
+universal ranking.

package/docs/COMPATIBILITY.md

@@ -0,0 +1,79 @@
+# Compatibility
+
+## Default contract
+
+The default export follows documented `fast-json-stable-stringify@2.1.0`
+behavior:
+
+- object keys are sorted recursively;
+- arrays retain their order;
+- a comparator receives `{ key, value }` records;
+- comparator functions can be passed directly or as `cmp`;
+- `{ cycles: true }` writes `__cycle__` for circular objects;
+- `toJSON` runs before value serialization;
+- JSON omission, primitive, wrapper-object, and non-finite number behavior is
+  preserved.
+
+The suite performs 30,000 deterministic differential serializations across
+generated JSON-compatible values, comparators, and option forms.
+
+## Intentional additions
+
+| Area | Compatible default | Addition |
+| :--- | :--- | :--- |
+| Circular arrays | Upstream can overflow | Same policy as circular objects |
+| Deep input | Recursive stack limit | Iterative traversal |
+| Cycles | Throw or `__cycle__` | Path, null, and custom marker policies |
+| BigInt | Throw | String or safe-number policies |
+| Replacer | Not exposed | Function and JSON property list |
+| Formatting | Compact | JSON-style `space` option |
+| Accessors | Invoke | Omit or throw policies |
+| Resources | Unbounded | Opt-in depth, entry, and length limits |
+| Diagnostics | Separate ecosystem | `safeStringify` named export |
+| Canonical JSON | Separate ecosystem | RFC 8785 string and byte exports |
+
+No addition changes output unless its option or named API is used, except that
+circular arrays now return the configured cycle behavior instead of causing a
+call-stack failure.
+
+## Package forms
+
+| Consumer | Supported form |
+| :--- | :--- |
+| ESM | default and named imports |
+| CommonJS | callable `require()` plus static helpers |
+| Browser | `StacklineStableStringify` global |
+| TypeScript | resolver-specific declarations |
+| npm alias | `fast-json-stable-stringify@npm:@stackline/stable-stringify` |
+
+## TypeScript
+
+The public declarations use syntax accepted by TypeScript 3.9. ESM-specific
+`.d.mts` resolution is validated from TypeScript 4.7 onward. The release matrix
+currently covers 3.9.10, 4.7.4, 4.9.5, 5.9.3, 6.0.2, and 7.0.2.
+
+Return types remain `string | undefined`, matching JSON root-value behavior.
+Canonical APIs return `string` or `Uint8Array` because invalid values throw.
+
+## Migration
+
+Direct migration:
+
+```js
+import stringify from '@stackline/stable-stringify';
+```
+
+No-import-change migration:
+
+```bash
+npm install fast-json-stable-stringify@npm:@stackline/stable-stringify
+```
+
+The clean-install test executes both names in ESM and CommonJS from the packed
+tarball, rather than resolving against the development workspace.
+
+## Standards boundary
+
+Stable output is deterministic for the same JavaScript data and options. It is
+not automatically RFC 8785 canonical output. Use `canonicalize` when another
+system, signature specification, or protocol requires JCS.

package/docs/MARKET_RESEARCH.md

@@ -0,0 +1,100 @@
+# Market Research
+
+## Decision
+
+The selected opportunity is a unified deterministic JSON serializer with a
+compatible stable API, safe diagnostic mode, and RFC 8785 canonical mode.
+
+It addresses a mature, high-volume need without copying an abandoned codebase.
+The runtime is original; comparison packages are development references only.
+
+## Evidence window
+
+The research uses the official npm downloads and registry APIs. The fixed
+30-day window is 2026-07-17 through 2026-08-15. The comparison window is
+2026-06-17 through 2026-07-16. Fixed dates make the findings reproducible.
+
+| Package | Recent 30 days | Prior 30 days | Change | Latest release |
+| :--- | ---: | ---: | ---: | :--- |
+| `fast-json-stable-stringify` | 587,334,858 | 581,507,983 | +1.00% | 2.1.0, 2019-12-14 |
+| `safe-stable-stringify` | 210,997,298 | 206,370,668 | +2.24% | 2.5.0, 2024-08-24 |
+| `fast-safe-stringify` | 172,544,640 | 161,813,217 | +6.63% | 2.1.1, 2021-09-08 |
+| `json-stringify-safe` | 157,096,721 | 154,552,336 | +1.65% | 5.0.1, 2015-05-19 |
+| **Combined package activity** | **1,127,973,517** | **1,104,244,204** | **+2.15%** | four contracts |
+
+The same packages recorded 9,395,146,202 combined downloads from 2025-08-16
+through 2026-08-15.
+
+These sums measure package activity, not unique users. Dependency trees can
+install more than one package and repeated CI installs count again. The figures
+demonstrate category scale and fragmentation; they do not guarantee adoption
+for a new package.
+
+## Primary sources
+
+- [fast-json-stable-stringify downloads](https://api.npmjs.org/downloads/point/2026-07-17:2026-08-15/fast-json-stable-stringify)
+- [safe-stable-stringify downloads](https://api.npmjs.org/downloads/point/2026-07-17:2026-08-15/safe-stable-stringify)
+- [fast-safe-stringify downloads](https://api.npmjs.org/downloads/point/2026-07-17:2026-08-15/fast-safe-stringify)
+- [json-stringify-safe downloads](https://api.npmjs.org/downloads/point/2026-07-17:2026-08-15/json-stringify-safe)
+- [npm registry metadata](https://registry.npmjs.org/fast-json-stable-stringify)
+- [RFC 8785: JSON Canonicalization Scheme](https://www.rfc-editor.org/rfc/rfc8785.html)
+- [ECMAScript JSON.stringify algorithm](https://tc39.es/ecma262/multipage/structured-data.html#sec-json.stringify)
+
+## Product gap
+
+The category is split by concern:
+
+- the largest compatibility package offers stable key order but no current ESM
+  declaration surface, safe diagnostic mode, resource limits, or JCS API;
+- safe serializers focus on cycles and logging but differ in BigInt, getter,
+  `toJSON`, depth, edge, and fallback behavior;
+- canonical JSON implementations form another package category even though
+  cache keys and signatures often exist in the same systems;
+- several established releases are between two and eleven years old while
+  download activity continues to grow.
+
+Open issue themes in the comparison repositories include ESM, TypeScript
+options, RFC 8785 support, wrapper semantics, output limits, getters, `toJSON`,
+BigInt, and deep-stack behavior. The product contract directly tests those
+boundaries instead of bundling unrelated utilities.
+
+## Why this shape can grow
+
+The adoption path has three levels:
+
+1. existing users can keep the established function signature;
+2. npm alias users can keep the existing import specifier;
+3. new users gain safe and canonical modes without adding two more packages.
+
+Zero runtime dependencies reduce supply-chain exposure. TypeScript 3.9 through
+7.0, Node.js 14.17+, browsers, Deno, and Bun widen the usable install base.
+
+## Rejected directions
+
+### Another generic utility collection
+
+Broad utility packages compete on dozens of unrelated APIs and create a larger
+maintenance and security surface. The selected package owns one data boundary.
+
+### Canonical JSON only
+
+Standards compliance is valuable but is a smaller migration surface. Combining
+it with the established stable call shape creates a practical entry point.
+
+### Forking a legacy serializer
+
+Forking would accelerate initial code volume but inherit architecture and
+maintenance constraints. Behavioral compatibility is validated through tests;
+the runtime remains independently designed and licensed.
+
+## Success metrics
+
+Potential is evaluated through measurable signals, not a promised download
+number:
+
+- direct and alias installs that need no code changes;
+- issue resolution time and compatibility reports;
+- reverse dependencies and weekly npm downloads;
+- bundle size and runtime dependency count;
+- regression-free releases across the supported matrix;
+- adoption of safe and canonical named APIs.

package/docs/RELEASING.md

@@ -0,0 +1,68 @@
+# Releasing
+
+## Preconditions
+
+- `main` is the only default development branch.
+- Version and changelog agree.
+- Runtime dependencies remain zero or the exception is documented.
+- The full local suite and GitHub CI pass.
+- The npm and Verdaccio package names are available or authenticated.
+
+## Local release gate
+
+```bash
+npm ci
+npm test
+npm run test:attw
+npm run audit:dependencies
+npm pack --dry-run
+```
+
+Run the benchmark for regression evidence, not as a pass/fail release gate.
+
+## Artifact creation
+
+Build once and retain one immutable tarball:
+
+```bash
+version="$(node -p "require('./package.json').version")"
+mkdir -p "release/$version"
+npm pack --ignore-scripts --pack-destination "release/$version"
+(cd "release/$version" && sha512sum *.tgz > SHA512SUMS)
+npm sbom --omit=dev --sbom-format cyclonedx > "release/$version/sbom.cdx.json"
+```
+
+Run `scripts/smoke-install.mjs` against the retained path. The same bytes must
+be published to Verdaccio and public npm.
+
+## Registry order
+
+1. publish the retained tarball to Verdaccio;
+2. install directly and through the compatibility alias;
+3. compare tarball integrity and run smoke tests;
+4. run `publish.yml` with the expected SHA-512; the trusted workflow rebuilds
+   the reviewed commit and stops unless its tarball is byte-identical;
+5. let the workflow publish with npm provenance, then download it and compare
+   SHA-512;
+6. verify `latest`, provenance metadata, dependency audit, and registry
+   signature where available.
+
+Never rebuild between registry publications.
+
+## GitHub release
+
+Tag the exact tested commit as `vX.Y.Z`. Attach the tarball, `SHA512SUMS`, and
+CycloneDX SBOM. Confirm CI and CodeQL are green for the tagged source.
+
+## Documentation
+
+Build and test the static site, deploy it under
+`/docs/vanilla/stable-stringify/`, update the central sitemap, and verify HTML,
+CSS, JavaScript, image, robots, sitemap, metadata, LLM references, mobile
+layout, and playground behavior in production.
+
+## Rollback
+
+npm versions are immutable. Do not unpublish a consumed release except for a
+compelling security or legal reason. Deprecate a bad version with a precise
+message and publish a patch from the last known-good source.

package/examples/cache-key.mjs

@@ -0,0 +1,12 @@
+import assert from 'node:assert/strict';
+
+import stringify from '@stackline/stable-stringify';
+
+const first = { query: { page: 2, status: 'open' }, tenant: 42 };
+const second = { tenant: 42, query: { status: 'open', page: 2 } };
+
+const firstKey = stringify(first);
+const secondKey = stringify(second);
+
+assert.equal(firstKey, secondKey);
+console.log(firstKey);

package/examples/content-digest.mjs

@@ -0,0 +1,17 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+
+import { canonicalizeBytes } from '@stackline/stable-stringify';
+
+const document = {
+  issuedAt: '2026-08-21T00:00:00Z',
+  subject: 'release-manifest',
+  version: 1
+};
+
+const digest = createHash('sha256')
+  .update(canonicalizeBytes(document))
+  .digest('hex');
+
+assert.equal(digest.length, 64);
+console.log(digest);

package/examples/safe-logging.mjs

@@ -0,0 +1,14 @@
+import assert from 'node:assert/strict';
+
+import { safeStringify } from '@stackline/stable-stringify';
+
+const event = { id: 42n, name: 'checkout.failed' };
+event.context = event;
+
+const output = safeStringify(event);
+
+assert.equal(
+  output,
+  '{"context":"[Circular]","id":"42","name":"checkout.failed"}'
+);
+console.log(output);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackline/stable-stringify",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Deterministic, cycle-aware JSON serialization with a fast-json-stable-stringify-compatible API and RFC 8785 canonicalization",
   "keywords": [
     "stable-stringify",
@@ -62,6 +62,8 @@
   },
   "files": [
     "dist",
+    "docs",
+    "examples",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "LICENSE",
@@ -76,10 +78,11 @@
     "clean": "node scripts/clean.mjs",
     "build": "node scripts/build.mjs",
     "lint": "eslint . && node scripts/check-markdown.mjs",
-    "test": "npm run build && npm run lint && npm run test:coverage && npm run test:types && npm run test:package && npm run test:install && npm run test:docs",
+    "test": "npm run build && npm run lint && npm run test:coverage && npm run test:types && npm run test:examples && npm run test:package && npm run test:install && npm run test:docs",
     "test:unit": "node --test --test-reporter=spec test/*.test.mjs",
     "test:coverage": "c8 --all --src src --check-coverage --lines 100 --functions 100 --statements 100 --branches 95 node --test test/core.test.mjs test/compatibility.test.mjs test/cycles-limits.test.mjs test/canonical.test.mjs test/safe.test.mjs",
     "test:types": "node scripts/test-types.mjs",
+    "test:examples": "node examples/cache-key.mjs && node examples/content-digest.mjs && node examples/safe-logging.mjs",
     "test:package": "node --test test/package.test.mjs && node scripts/check-dist.mjs && publint",
     "test:install": "node scripts/smoke-install.mjs",
     "test:docs": "npm run docs:build && node scripts/check-docs.mjs",