typesea 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to TypeSea are recorded here.
 
+## 0.3.1 - Unreleased
+
+### Changed
+
+- Hardened the manual GitHub Release workflow so `workflow_dispatch` tag input
+  is passed through environment variables and validated as a release tag before
+  it reaches shell output.
+- Added `SECURITY.md` with supported versions, reporting guidance, and the
+  security boundary for safe, unsafe, unchecked, AOT, and dynamic compilation.
+- Added a post-publish npm registry verification step to the GitHub Publish
+  workflow.
+- Added `release:publish` so the repository-owned publish command always uses
+  `npm publish --provenance --access public --ignore-scripts`.
+- Removed the version-pinned Socket badge URL from the README.
+- Refreshed the benchmark snapshot and docs graph from the 2026-07-05 local
+  `bench/ecosystem.bench.ts` run.
+- Clarified the release path: local npm publishing is allowed for emergency
+  manual releases, but normal releases should go through GitHub Release so npm
+  provenance is attached.
+- Expanded decoder documentation around method chaining with `transform`,
+  `default`, `prefault`, and `catch`.
+
 ## 0.3.0 - 2026-07-05
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # TypeSea
 
 [![CI](https://github.com/Feralthedogg/TypeSea/actions/workflows/ci.yml/badge.svg)](https://github.com/Feralthedogg/TypeSea/actions/workflows/ci.yml)
-[![Socket Badge](https://badge.socket.dev/npm/package/typesea/0.3.0)](https://badge.socket.dev/npm/package/typesea/0.3.0)
+[![Socket Badge](https://badge.socket.dev/npm/package/typesea)](https://socket.dev/npm/package/typesea)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 ![TypeScript](https://img.shields.io/badge/language-TypeScript-informational)
 ![Dependencies](https://img.shields.io/badge/runtime%20deps-zero-brightgreen)
@@ -17,7 +17,7 @@ runtime compilation, and AOT source generation.
 
 ## Benchmark Headline
 
-Last local benchmark on 2026-07-04 KST:
+Last local benchmark on 2026-07-05 KST:
 `npm run bench -- bench/ecosystem.bench.ts --run`, strict-object contract,
 operations per second on one machine.
 
@@ -40,6 +40,12 @@ loads, allocation-light strict-key loops, and V8-friendly monomorphic codegen.
 > return frozen `Result` values — `any`, `try`, and `catch` are banned from the
 > entire codebase and enforced by policy gates.
 
+> [!WARNING]
+> `unsafe` and `unchecked` are **not public-boundary modes**. They are for
+> trusted, already-normalized data where the caller accepts getter execution,
+> prototype-backed values, and weaker strict-extra-key guarantees. Use the
+> default safe mode for external input.
+
 ---
 
 ## Why
@@ -222,50 +228,50 @@ failed check() -> schema-aware diagnostic collector
 
 ## Performance Snapshot
 
-Last local benchmark on 2026-07-04 KST, using
+Last local benchmark on 2026-07-05 KST, using
 `npm run bench -- bench/ecosystem.bench.ts --run` on the benchmark strict-object
 contract. These are operations per second on one machine, not release
 guarantees.
 
 | Valid object path | hz |
 | --- | ---: |
-| TypeSea interpreted `is()` | 513,701 |
-| TypeSea compiled safe `is()` | 4,297,306 |
-| TypeSea compiled unsafe `is()` | 36,297,653 |
-| TypeSea compiled unchecked `is()` | 42,581,174 |
-| Zod `safeParse` | 1,343,756 |
-| Valibot `safeParse` | 1,406,528 |
-| Ajv compiled | 4,275,389 |
+| TypeSea interpreted `is()` | 478,576 |
+| TypeSea compiled safe `is()` | 5,109,602 |
+| TypeSea compiled unsafe `is()` | 36,777,097 |
+| TypeSea compiled unchecked `is()` | 42,620,570 |
+| Zod `safeParse` | 1,400,045 |
+| Valibot `safeParse` | 1,400,599 |
+| Ajv compiled | 4,238,036 |
 
 | Valid diagnostic path | hz |
 | --- | ---: |
-| TypeSea interpreted `check()` | 503,232 |
-| TypeSea compiled safe `check()` | 3,903,929 |
-| TypeSea compiled unsafe `check()` | 35,568,425 |
-| TypeSea compiled unchecked `check()` | 40,084,605 |
-| Zod `safeParse` | 1,355,014 |
-| Valibot `safeParse` | 1,378,266 |
-| Ajv compiled | 4,278,587 |
+| TypeSea interpreted `check()` | 424,989 |
+| TypeSea compiled safe `check()` | 4,642,948 |
+| TypeSea compiled unsafe `check()` | 37,184,199 |
+| TypeSea compiled unchecked `check()` | 42,487,325 |
+| Zod `safeParse` | 1,278,859 |
+| Valibot `safeParse` | 1,391,040 |
+| Ajv compiled | 4,338,063 |
 
 | Invalid object path | hz |
 | --- | ---: |
-| TypeSea interpreted `is()` | 3,636,369 |
-| TypeSea compiled safe `is()` | 42,080,241 |
-| TypeSea compiled unsafe `is()` | 49,654,076 |
-| TypeSea compiled unchecked `is()` | 50,482,732 |
-| Zod `safeParse` | 84,272 |
-| Valibot `safeParse` | 878,521 |
-| Ajv compiled | 27,820,643 |
+| TypeSea interpreted `is()` | 3,325,603 |
+| TypeSea compiled safe `is()` | 43,094,061 |
+| TypeSea compiled unsafe `is()` | 50,738,235 |
+| TypeSea compiled unchecked `is()` | 50,898,012 |
+| Zod `safeParse` | 84,647 |
+| Valibot `safeParse` | 866,013 |
+| Ajv compiled | 30,535,761 |
 
 | Invalid diagnostic path | hz |
 | --- | ---: |
-| TypeSea interpreted `check()` | 420,446 |
-| TypeSea compiled safe `check()` | 2,086,129 |
-| TypeSea compiled unsafe `check()` | 3,077,367 |
-| TypeSea compiled unchecked `check()` | 3,673,508 |
-| Zod `safeParse` | 79,613 |
-| Valibot `safeParse` | 887,991 |
-| Ajv compiled | 28,713,035 |
+| TypeSea interpreted `check()` | 405,590 |
+| TypeSea compiled safe `check()` | 2,107,460 |
+| TypeSea compiled unsafe `check()` | 3,186,702 |
+| TypeSea compiled unchecked `check()` | 3,509,673 |
+| Zod `safeParse` | 85,355 |
+| Valibot `safeParse` | 788,870 |
+| Ajv compiled | 29,951,403 |
 
 The safe compiled path stays close to Ajv while retaining TypeSea hostile-input
 semantics: descriptor-based property reads, symbol/non-enumerable strict-key
@@ -407,6 +413,7 @@ npm run check:consumer  # tarball install + runtime/type smoke in a temp project
 npm run bench -- --run  # benchmark smoke
 npm run pack:dry        # package contents dry run
 npm run release:check   # the full pre-publish gate (everything above)
+npm run release:publish # npm publish with provenance and ignored lifecycle scripts
 ```
 
 `npm run release:check` runs the same gate expected before publishing:
@@ -414,6 +421,16 @@ typecheck, lint, tests, build, docs smoke, dist policy, public API snapshot,
 package contents, consumer install, benchmark smoke, and pack dry run.
 CI executes it on Node 20.19, 22, and 24; releases publish with npm provenance.
 
+Release path:
+
+1. Push a `vX.Y.Z` tag or run the GitHub `Release` workflow with that tag.
+2. The release workflow verifies that the tag matches `package.json`.
+3. Publishing happens from the GitHub `Publish` workflow through `npm run release:publish`, which expands to `npm publish --provenance --access public --ignore-scripts`.
+
+Local publishing with `NPM_TOKEN` is reserved for manual recovery releases. It
+must still run `npm run release:check` first, and it cannot attach GitHub OIDC
+provenance.
+
 > [!NOTE]
 > Benchmark comparison packages (Zod, Valibot, Ajv) are dev dependencies only —
 > package policy rejects them from every runtime dependency field. The
@@ -427,6 +444,18 @@ CI executes it on Node 20.19, 22, and 24; releases publish with npm provenance.
 - [Documentation site](https://feralthedogg.github.io/TypeSea/)
 - [API reference](docs/api.md)
 - [Engine notes](docs/engine-notes.md)
+- [Security policy](https://github.com/Feralthedogg/TypeSea/blob/main/SECURITY.md)
+
+---
+
+## Migration Notes
+
+### 0.3.0 to 0.3.1
+
+No application code changes are required. `0.3.1` is a release-hardening patch:
+it tightens manual release tag handling, documents npm provenance expectations,
+adds a security policy, and verifies that npm exposes the published version after
+the GitHub publish workflow completes.
 
 ---
 

package/SECURITY.md

@@ -0,0 +1,52 @@
+# Security Policy
+
+## Supported Versions
+
+TypeSea supports the latest published minor line. Security fixes are released as
+patch versions whenever a fix can be shipped without changing the public API.
+
+| Version | Supported |
+| --- | --- |
+| 0.3.x | yes |
+| 0.2.x | no |
+
+## Reporting A Vulnerability
+
+Please report security issues through GitHub Security Advisories for
+`Feralthedogg/TypeSea`. If that is unavailable, open a GitHub issue with the
+minimum public detail needed to start coordination and mark the title as a
+security report.
+
+Useful reports include:
+
+- affected TypeSea version
+- minimal schema and input needed to reproduce the issue
+- whether the issue affects `safe`, `unsafe`, `unchecked`, AOT, JSON Schema, or
+  an adapter
+- expected verdict and actual verdict
+- generated source or stack output that helps reproduce the issue
+
+## Security Boundary
+
+The default validation mode is `safe`. It is the mode intended for hostile
+boundary data. Safe mode avoids user getter execution, treats prototype-backed
+data as untrusted, handles `__proto__` and `constructor` keys with
+null-prototype lookups, checks strict-object symbol and non-enumerable extras,
+and returns explicit `Result` values for expected failures.
+
+`unsafe` and `unchecked` are performance escape hatches for trusted,
+already-normalized data. They may execute getters, may accept prototype-backed
+values, and may relax strict-object extra-key guarantees. Do not use these modes
+on public input boundaries unless a separate normalization step has already
+converted the input into plain owned data.
+
+`compile()` uses `new Function` by design. If a deployment forbids dynamic code
+generation through Content Security Policy, use normal guards or
+`emitAotModule()` instead.
+
+## Release Integrity
+
+The package is expected to have zero runtime, peer, optional, and bundled
+dependencies. Release checks verify package contents, public API drift, docs,
+tests, consumer install smoke, benchmarks, and dist policy before publishing.
+Normal releases should go through GitHub Releases so npm provenance is attached.

package/docs/api.md

@@ -148,6 +148,12 @@ const Count = t.pipe(t.coerce.number(), t.number.int().gte(0));
 const result = Count.decode("42");
 
 const Name = t.default(t.string.min(1), "anonymous");
+const NormalizedName = t.string
+  .trim()
+  .pipe(t.string.min(1))
+  .transform((value) => value.toLowerCase())
+  .default("anonymous")
+  .catch("anonymous");
 const NumberText = t.codec(
   t.string.regex(/^\d+$/u, "digits"),
   t.number.int().nonnegative(),
@@ -163,12 +169,11 @@ Decoders are for output-producing operations. They return `Result` from
 not be the same runtime value as the input.
 
 - `t.transform(source, mapper)` decodes `source`, then maps the decoded value.
-- `t.pipe(source, next)` feeds a successful decoded value into the next guard or
-  decoder.
+- `t.pipe(source, next)` feeds a successful decoded value into the next guard or decoder.
 - `t.default(source, value)` returns a fallback output for `undefined` input.
 - `t.prefault(source, value)` feeds a fallback input through the source.
-- `t.codec(input, output, mapping)` validates both sides of a bidirectional
-  decode/encode pair.
+- `t.catch(source, value)` returns a fallback output after a failed decode.
+- `t.codec(input, output, mapping)` validates both sides of a bidirectional decode/encode pair.
 - `t.coerce.string`, `t.coerce.number`, and `t.coerce.boolean` provide explicit
   primitive coercion.
 - `t.string.trim()`, `t.string.toLowerCase()`, and `t.string.toUpperCase()`
@@ -320,9 +325,10 @@ const fastParser = toTrpcParser(FastUser);
 const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);
 ```
 
-Use the default compiled mode at public input boundaries. For trusted,
-already-normalized internal data, the faster modes can be wired through adapters
-the same way.
+Use the default compiled mode at public input boundaries. It keeps the safe
+descriptor-read contract even when an adapter hides the direct `is()` call. For
+trusted, already-normalized internal data, the faster modes can be wired through
+adapters the same way.
 
 ```ts
 const UnsafeUser = compile(User, { mode: "unsafe" });

package/docs/assets/benchmark-headline.svg

@@ -58,92 +58,92 @@
     <circle cx="84" cy="690" r="220" fill="#38bdf8" opacity="0.07"/>
 
     <text id="headline" x="44" y="58" class="title">TypeSea benchmark comparison</text>
-    <text x="46" y="88" class="subtitle">Local run on 2026-07-04 KST, strict-object contract, ops/sec. Higher is better.</text>
+    <text x="46" y="88" class="subtitle">Local run on 2026-07-05 KST, strict-object contract, ops/sec. Higher is better.</text>
 
     <g filter="url(#shadow)">
         <rect x="44" y="118" width="322" height="108" rx="18" fill="url(#panel)" stroke="#1f2937"/>
         <text x="66" y="148" class="metric-label">Unchecked valid hot path</text>
-        <text x="66" y="188" class="metric-value">42.58M</text>
-        <text x="66" y="210" class="metric-sub">31.7x Zod, 10.0x Ajv</text>
+        <text x="66" y="188" class="metric-value">42.62M</text>
+        <text x="66" y="210" class="metric-sub">30.4x Zod, 10.1x Ajv</text>
 
         <rect x="399" y="118" width="322" height="108" rx="18" fill="url(#panel)" stroke="#1f2937"/>
         <text x="421" y="148" class="metric-label">Safe invalid fast-fail</text>
-        <text x="421" y="188" class="metric-value">42.08M</text>
-        <text x="421" y="210" class="metric-sub">1.51x Ajv, 499x Zod</text>
+        <text x="421" y="188" class="metric-value">43.09M</text>
+        <text x="421" y="210" class="metric-sub">1.41x Ajv, 509x Zod</text>
 
         <rect x="754" y="118" width="322" height="108" rx="18" fill="url(#panel)" stroke="#1f2937"/>
         <text x="776" y="148" class="metric-label">Safe valid path</text>
-        <text x="776" y="188" class="metric-value">4.30M</text>
-        <text x="776" y="210" class="metric-sub">Ajv-class while staying safe</text>
+        <text x="776" y="188" class="metric-value">5.11M</text>
+        <text x="776" y="210" class="metric-sub">1.21x Ajv while staying safe</text>
     </g>
 
     <g filter="url(#shadow)">
         <rect x="44" y="260" width="1032" height="136" rx="18" fill="url(#panel)" stroke="#1f2937"/>
         <text x="66" y="291" class="card-title">Valid object path</text>
-        <text x="230" y="291" class="card-note">linear scale to 42.58M</text>
+        <text x="230" y="291" class="card-note">linear scale to 42.62M</text>
         <line x1="270" y1="318" x2="1010" y2="318" class="axis"/>
 
         <text x="66" y="326" class="bar-label">TypeSea unchecked</text>
         <rect x="270" y="312" width="740" height="15" rx="7.5" fill="url(#unchecked)"/>
-        <text x="1024" y="326" class="bar-value">42.58M</text>
+        <text x="1024" y="326" class="bar-value">42.62M</text>
 
         <text x="66" y="350" class="bar-label">TypeSea unsafe</text>
-        <rect x="270" y="336" width="631" height="15" rx="7.5" fill="url(#unsafe)"/>
-        <text x="915" y="350" class="bar-value">36.30M</text>
+        <rect x="270" y="336" width="639" height="15" rx="7.5" fill="url(#unsafe)"/>
+        <text x="923" y="350" class="bar-value">36.78M</text>
 
         <text x="66" y="374" class="bar-label">TypeSea safe / Ajv / Zod</text>
-        <rect x="270" y="360" width="75" height="15" rx="7.5" fill="url(#safe)"/>
-        <rect x="354" y="360" width="74" height="15" rx="7.5" fill="url(#ajv)"/>
-        <rect x="437" y="360" width="24" height="15" rx="7.5" fill="url(#valibot)"/>
-        <rect x="470" y="360" width="23" height="15" rx="7.5" fill="url(#zod)"/>
-        <text x="506" y="374" class="bar-value">safe 4.30M, Ajv 4.28M, Valibot 1.41M, Zod 1.34M</text>
+        <rect x="270" y="360" width="89" height="15" rx="7.5" fill="url(#safe)"/>
+        <rect x="368" y="360" width="74" height="15" rx="7.5" fill="url(#ajv)"/>
+        <rect x="451" y="360" width="24" height="15" rx="7.5" fill="url(#valibot)"/>
+        <rect x="484" y="360" width="24" height="15" rx="7.5" fill="url(#zod)"/>
+        <text x="522" y="374" class="bar-value">safe 5.11M, Ajv 4.24M, Valibot 1.40M, Zod 1.40M</text>
     </g>
 
     <g filter="url(#shadow)">
         <rect x="44" y="418" width="1032" height="150" rx="18" fill="url(#panel)" stroke="#1f2937"/>
         <text x="66" y="449" class="card-title">Invalid object fast-fail</text>
-        <text x="268" y="449" class="card-note">linear scale to 50.48M</text>
+        <text x="268" y="449" class="card-note">linear scale to 50.90M</text>
         <line x1="270" y1="476" x2="1010" y2="476" class="axis"/>
 
         <text x="66" y="482" class="bar-label">TypeSea unchecked</text>
         <rect x="270" y="468" width="740" height="15" rx="7.5" fill="url(#unchecked)"/>
-        <text x="1024" y="482" class="bar-value">50.48M</text>
+        <text x="1024" y="482" class="bar-value">50.90M</text>
 
         <text x="66" y="506" class="bar-label">TypeSea unsafe</text>
-        <rect x="270" y="492" width="728" height="15" rx="7.5" fill="url(#unsafe)"/>
-        <text x="1024" y="506" class="bar-value">49.65M</text>
+        <rect x="270" y="492" width="738" height="15" rx="7.5" fill="url(#unsafe)"/>
+        <text x="1024" y="506" class="bar-value">50.74M</text>
 
         <text x="66" y="530" class="bar-label">TypeSea safe</text>
-        <rect x="270" y="516" width="617" height="15" rx="7.5" fill="url(#safe)"/>
-        <text x="902" y="530" class="bar-value">42.08M</text>
+        <rect x="270" y="516" width="627" height="15" rx="7.5" fill="url(#safe)"/>
+        <text x="912" y="530" class="bar-value">43.09M</text>
 
         <text x="66" y="554" class="bar-label">Ajv / Valibot / Zod</text>
-        <rect x="270" y="540" width="408" height="15" rx="7.5" fill="url(#ajv)"/>
-        <rect x="690" y="540" width="13" height="15" rx="7.5" fill="url(#valibot)"/>
-        <rect x="714" y="540" width="3" height="15" rx="1.5" fill="url(#zod)"/>
-        <text x="734" y="554" class="bar-value">Ajv 27.82M, Valibot 0.88M, Zod 0.08M</text>
+        <rect x="270" y="540" width="444" height="15" rx="7.5" fill="url(#ajv)"/>
+        <rect x="726" y="540" width="13" height="15" rx="7.5" fill="url(#valibot)"/>
+        <rect x="750" y="540" width="3" height="15" rx="1.5" fill="url(#zod)"/>
+        <text x="770" y="554" class="bar-value">Ajv 30.54M, Valibot 0.87M, Zod 0.08M</text>
     </g>
 
     <g filter="url(#shadow)">
         <rect x="44" y="576" width="1032" height="136" rx="18" fill="url(#panel)" stroke="#1f2937"/>
         <text x="66" y="607" class="card-title">Invalid diagnostic path</text>
-        <text x="270" y="607" class="card-note">linear scale to 28.71M; Ajv is a boolean baseline</text>
+        <text x="270" y="607" class="card-note">linear scale to 29.95M; Ajv is a boolean baseline</text>
         <line x1="270" y1="634" x2="1010" y2="634" class="axis"/>
 
         <text x="66" y="642" class="bar-label">Ajv compiled</text>
         <rect x="270" y="628" width="740" height="15" rx="7.5" fill="url(#ajv)"/>
-        <text x="1024" y="642" class="bar-value">28.71M</text>
+        <text x="1024" y="642" class="bar-value">29.95M</text>
 
         <text x="66" y="666" class="bar-label">TypeSea modes</text>
-        <rect x="270" y="652" width="95" height="15" rx="7.5" fill="url(#unchecked)"/>
+        <rect x="270" y="652" width="87" height="15" rx="7.5" fill="url(#unchecked)"/>
         <rect x="374" y="652" width="79" height="15" rx="7.5" fill="url(#unsafe)"/>
-        <rect x="462" y="652" width="54" height="15" rx="7.5" fill="url(#safe)"/>
-        <text x="532" y="666" class="bar-value">unchecked 3.67M, unsafe 3.08M, safe 2.09M</text>
+        <rect x="462" y="652" width="52" height="15" rx="7.5" fill="url(#safe)"/>
+        <text x="532" y="666" class="bar-value">unchecked 3.51M, unsafe 3.19M, safe 2.11M</text>
 
         <text x="66" y="690" class="bar-label">Valibot / Zod</text>
-        <rect x="270" y="676" width="23" height="15" rx="7.5" fill="url(#valibot)"/>
+        <rect x="270" y="676" width="20" height="15" rx="7.5" fill="url(#valibot)"/>
         <rect x="302" y="676" width="3" height="15" rx="1.5" fill="url(#zod)"/>
-        <text x="322" y="690" class="bar-value">Valibot 0.89M, Zod 0.08M</text>
+        <text x="322" y="690" class="bar-value">Valibot 0.79M, Zod 0.09M</text>
     </g>
 
     <g transform="translate(44 730)">

package/docs/engine-notes.md

@@ -185,15 +185,15 @@ Zod, Valibot, and Ajv are dev dependencies for measurement only. They are not
 imported by `src`, and package policy rejects runtime, peer, optional, or
 bundled dependency fields before release.
 
-Last local benchmark on 2026-07-04 KST reported these ecosystem paths over the
+Last local benchmark on 2026-07-05 KST reported these ecosystem paths over the
 JSON-compatible strict-object benchmark:
 
 | Case | TypeSea runtime plan | TypeSea compiled safe | TypeSea compiled unsafe | TypeSea compiled unchecked | Ajv compiled |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Valid `is()` | 513,701 hz | 4,297,306 hz | 36,297,653 hz | 42,581,174 hz | 4,275,389 hz |
-| Valid `check()` | 503,232 hz | 3,903,929 hz | 35,568,425 hz | 40,084,605 hz | 4,278,587 hz |
-| Invalid `is()` | 3,636,369 hz | 42,080,241 hz | 49,654,076 hz | 50,482,732 hz | 27,820,643 hz |
-| Invalid `check()` | 420,446 hz | 2,086,129 hz | 3,077,367 hz | 3,673,508 hz | 28,713,035 hz |
+| Valid `is()` | 478,576 hz | 5,109,602 hz | 36,777,097 hz | 42,620,570 hz | 4,238,036 hz |
+| Valid `check()` | 424,989 hz | 4,642,948 hz | 37,184,199 hz | 42,487,325 hz | 4,338,063 hz |
+| Invalid `is()` | 3,325,603 hz | 43,094,061 hz | 50,738,235 hz | 50,898,012 hz | 30,535,761 hz |
+| Invalid `check()` | 405,590 hz | 2,107,460 hz | 3,186,702 hz | 3,509,673 hz | 29,951,403 hz |
 
 Benchmark numbers are machine-local telemetry. They are useful for catching
 regressions, not for promising a fixed throughput floor. Unsafe and unchecked

package/docs/index.html

@@ -604,7 +604,7 @@
       <aside class="sidebar" aria-label="Documentation navigation">
         <div class="brand">
           <h1>TypeSea</h1>
-          <span class="version">v0.3.0</span>
+          <span class="version">v0.3.1</span>
         </div>
         <p class="brand-tagline">
           <span class="i18n-en">Complete docs from README.md, docs/api.md, and docs/engine-notes.md.</span>
@@ -966,14 +966,15 @@ const schema = toJsonSchema(User);</code></pre>
             </header>
             <div class="locale-en">
 <h2 id="readme-en-typesea">TypeSea</h2>
-<p><a href="https://github.com/Feralthedogg/TypeSea/actions/workflows/ci.yml/badge.svg">![CI</a>](https://github.com/Feralthedogg/TypeSea/actions/workflows/ci.yml) <span class="muted-link">![Socket Badge</span>](https://badge.socket.dev/npm/package/typesea/0.3.0) <span class="muted-link">![License</span>](./LICENSE) <span class="muted-link">TypeScript</span> <span class="muted-link">Dependencies</span> <span class="muted-link">Tree-shakeable</span> <span class="muted-link">Side-effect free</span> <span class="muted-link">No dependencies</span> <span class="muted-link">Module</span> <span class="muted-link">Node</span></p>
+<p><a href="https://github.com/Feralthedogg/TypeSea/actions/workflows/ci.yml/badge.svg">![CI</a>](https://github.com/Feralthedogg/TypeSea/actions/workflows/ci.yml) <span class="muted-link">![Socket Badge</span>](https://socket.dev/npm/package/typesea) <span class="muted-link">![License</span>](./LICENSE) <span class="muted-link">TypeScript</span> <span class="muted-link">Dependencies</span> <span class="muted-link">Tree-shakeable</span> <span class="muted-link">Side-effect free</span> <span class="muted-link">No dependencies</span> <span class="muted-link">Module</span> <span class="muted-link">Node</span></p>
 <p><strong>TypeSea</strong> is a <strong>zero-runtime-dependency TypeScript runtime narrowing library</strong> built around <strong>immutable guards</strong>, optimized <strong>Sea-of-Nodes validation plans</strong>, runtime compilation, and AOT source generation.</p>
 <h3 id="readme-en-benchmark-headline">Benchmark Headline</h3>
-<p>Last local benchmark on 2026-07-04 KST: <code>npm run bench -- bench/ecosystem.bench.ts --run</code>, strict-object contract, operations per second on one machine.</p>
+<p>Last local benchmark on 2026-07-05 KST: <code>npm run bench -- bench/ecosystem.bench.ts --run</code>, strict-object contract, operations per second on one machine.</p>
 <p><img class="benchmark-image" src="assets/benchmark-headline.svg" alt="TypeSea benchmark comparison"></p>
 <p>TypeSea safe compiled validators are already in Ajv's boolean hot-path class while keeping descriptor-based hostile-input semantics. Unsafe and unchecked FastMode are the bragging-rights path for trusted normalized data: direct field loads, allocation-light strict-key loops, and V8-friendly monomorphic codegen.</p>
 <blockquote><p>Goal: not &quot;probably valid&quot;, but <strong>provably parity-tested validation</strong> that never executes user code, never throws on expected failures, and never leaks mutable state across a public boundary.</p></blockquote>
 <aside class="admonition important"><strong class="admonition-title">IMPORTANT</strong><p>TypeSea is designed for <strong>hostile boundary data</strong>: property reads go through descriptors so <strong>user getters never execute</strong>, <code>__proto__</code>/<code>constructor</code> keys are handled with null-prototype lookups, user regexes are cloned and <code>lastIndex</code>-reset, and cyclic inputs validate finitely. Expected failures return frozen <code>Result</code> values — <code>any</code>, <code>try</code>, and <code>catch</code> are banned from the entire codebase and enforced by policy gates.</p></aside>
+<aside class="admonition warning"><strong class="admonition-title">WARNING</strong><p><code>unsafe</code> and <code>unchecked</code> are <strong>not public-boundary modes</strong>. They are for trusted, already-normalized data where the caller accepts getter execution, prototype-backed values, and weaker strict-extra-key guarantees. Use the default safe mode for external input.</p></aside>
 <hr>
 <h3 id="readme-en-why">Why</h3>
 <p>Many validation libraries fall short when you care about:</p>
@@ -1059,35 +1060,35 @@ failed check() -&gt; schema-aware diagnostic collector</code></pre>
 <aside class="admonition important"><strong class="admonition-title">IMPORTANT</strong><p>Generated validators keep <strong>user-controlled values out of source text</strong>: literals, regexps, object keys, keysets, and dynamic schema fallbacks live in <strong>side tables</strong> referenced by numeric index. Hostile property names cannot escape into generated code — this is pinned by dedicated injection-audit tests.</p></aside>
 <hr>
 <h3 id="readme-en-performance-snapshot">Performance Snapshot</h3>
-<p>Last local benchmark on 2026-07-04 KST, using <code>npm run bench -- bench/ecosystem.bench.ts --run</code> on the benchmark strict-object contract. These are operations per second on one machine, not release guarantees.</p>
-<div class="table-wrap"><table><thead><tr><th>Valid object path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>513,701</td></tr>
-<tr><td>TypeSea compiled safe <code>is()</code></td><td>4,297,306</td></tr>
-<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>36,297,653</td></tr>
-<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>42,581,174</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>1,343,756</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>1,406,528</td></tr>
-<tr><td>Ajv compiled</td><td>4,275,389</td></tr></tbody></table></div>
-<div class="table-wrap"><table><thead><tr><th>Valid diagnostic path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>503,232</td></tr>
-<tr><td>TypeSea compiled safe <code>check()</code></td><td>3,903,929</td></tr>
-<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>35,568,425</td></tr>
-<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>40,084,605</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>1,355,014</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>1,378,266</td></tr>
-<tr><td>Ajv compiled</td><td>4,278,587</td></tr></tbody></table></div>
-<div class="table-wrap"><table><thead><tr><th>Invalid object path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>3,636,369</td></tr>
-<tr><td>TypeSea compiled safe <code>is()</code></td><td>42,080,241</td></tr>
-<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>49,654,076</td></tr>
-<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>50,482,732</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>84,272</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>878,521</td></tr>
-<tr><td>Ajv compiled</td><td>27,820,643</td></tr></tbody></table></div>
-<div class="table-wrap"><table><thead><tr><th>Invalid diagnostic path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>420,446</td></tr>
-<tr><td>TypeSea compiled safe <code>check()</code></td><td>2,086,129</td></tr>
-<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>3,077,367</td></tr>
-<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>3,673,508</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>79,613</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>887,991</td></tr>
-<tr><td>Ajv compiled</td><td>28,713,035</td></tr></tbody></table></div>
+<p>Last local benchmark on 2026-07-05 KST, using <code>npm run bench -- bench/ecosystem.bench.ts --run</code> on the benchmark strict-object contract. These are operations per second on one machine, not release guarantees.</p>
+<div class="table-wrap"><table><thead><tr><th>Valid object path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>478,576</td></tr>
+<tr><td>TypeSea compiled safe <code>is()</code></td><td>5,109,602</td></tr>
+<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>36,777,097</td></tr>
+<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>42,620,570</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>1,400,045</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>1,400,599</td></tr>
+<tr><td>Ajv compiled</td><td>4,238,036</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>Valid diagnostic path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>424,989</td></tr>
+<tr><td>TypeSea compiled safe <code>check()</code></td><td>4,642,948</td></tr>
+<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>37,184,199</td></tr>
+<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>42,487,325</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>1,278,859</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>1,391,040</td></tr>
+<tr><td>Ajv compiled</td><td>4,338,063</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>Invalid object path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>3,325,603</td></tr>
+<tr><td>TypeSea compiled safe <code>is()</code></td><td>43,094,061</td></tr>
+<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>50,738,235</td></tr>
+<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>50,898,012</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>84,647</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>866,013</td></tr>
+<tr><td>Ajv compiled</td><td>30,535,761</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>Invalid diagnostic path</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>405,590</td></tr>
+<tr><td>TypeSea compiled safe <code>check()</code></td><td>2,107,460</td></tr>
+<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>3,186,702</td></tr>
+<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>3,509,673</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>85,355</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>788,870</td></tr>
+<tr><td>Ajv compiled</td><td>29,951,403</td></tr></tbody></table></div>
 <p>The safe compiled path stays close to Ajv while retaining TypeSea hostile-input semantics: descriptor-based property reads, symbol/non-enumerable strict-key rejection, presence semantics, immutable diagnostics, and TypeScript guard inference. Unsafe and unchecked compiled modes are faster because they deliberately give up parts of that hostile-input contract.</p>
 <hr>
 <h3 id="readme-en-api-reference">API Reference</h3>
@@ -1170,12 +1171,20 @@ const Node: Guard&lt;ListNode&gt; = t.lazy((): Guard&lt;ListNode&gt; =&gt;
 npm run check:consumer  # tarball install + runtime/type smoke in a temp project
 npm run bench -- --run  # benchmark smoke
 npm run pack:dry        # package contents dry run
-npm run release:check   # the full pre-publish gate (everything above)</code></pre>
+npm run release:check   # the full pre-publish gate (everything above)
+npm run release:publish # npm publish with provenance and ignored lifecycle scripts</code></pre>
 <p><code>npm run release:check</code> runs the same gate expected before publishing: typecheck, lint, tests, build, docs smoke, dist policy, public API snapshot, package contents, consumer install, benchmark smoke, and pack dry run. CI executes it on Node 20.19, 22, and 24; releases publish with npm provenance.</p>
+<p>Release path:</p>
+<ol><li>Push a <code>vX.Y.Z</code> tag or run the GitHub <code>Release</code> workflow with that tag.</li><li>The release workflow verifies that the tag matches <code>package.json</code>.</li><li>Publishing happens from the GitHub <code>Publish</code> workflow through <code>npm run release:publish</code>, which expands to <code>npm publish --provenance --access public --ignore-scripts</code>.</li></ol>
+<p>Local publishing with <code>NPM_TOKEN</code> is reserved for manual recovery releases. It must still run <code>npm run release:check</code> first, and it cannot attach GitHub OIDC provenance.</p>
 <aside class="admonition note"><strong class="admonition-title">NOTE</strong><p>Benchmark comparison packages (Zod, Valibot, Ajv) are dev dependencies only — package policy rejects them from every runtime dependency field. The benchmark suite reports both boolean-path and diagnostic-path (<code>check()</code> vs <code>safeParse</code>) comparisons, so numbers stay apples-to-apples.</p></aside>
 <hr>
 <h3 id="readme-en-documentation">Documentation</h3>
-<ul><li><a href="#overview">Documentation site</a></li><li><a href="#api-reference">API reference</a></li><li><a href="#engine-notes">Engine notes</a></li></ul>
+<ul><li><a href="#overview">Documentation site</a></li><li><a href="#api-reference">API reference</a></li><li><a href="#engine-notes">Engine notes</a></li><li><a href="https://github.com/Feralthedogg/TypeSea/blob/main/SECURITY.md">Security policy</a></li></ul>
+<hr>
+<h3 id="readme-en-migration-notes">Migration Notes</h3>
+<h4 id="readme-en-0-3-0-to-0-3-1">0.3.0 to 0.3.1</h4>
+<p>No application code changes are required. <code>0.3.1</code> is a release-hardening patch: it tightens manual release tag handling, documents npm provenance expectations, adds a security policy, and verifies that npm exposes the published version after the GitHub publish workflow completes.</p>
 <hr>
 <h3 id="readme-en-license">License</h3>
 <p>MIT License. See <a href="https://github.com/Feralthedogg/TypeSea/blob/main/LICENSE">LICENSE</a>.</p>
@@ -1184,11 +1193,12 @@ npm run release:check   # the full pre-publish gate (everything above)</code></p
 <h2 id="readme-ko-typesea">TypeSea</h2>
 <p><strong>TypeSea</strong>는 런타임 의존성 없이 TypeScript 값을 검증하고 타입을 좁히는 라이브러리입니다. 불변 스키마, Sea-of-Nodes에서 영향을 받은 검증 IR, 런타임 컴파일, AOT 소스 생성을 한 흐름으로 묶는 것을 목표로 합니다.</p>
 <h3 id="readme-ko-벤치마크-요약">벤치마크 요약</h3>
-<p>마지막 로컬 벤치마크는 2026-07-04 KST에 실행했습니다. 명령은 <code>npm run bench -- bench/ecosystem.bench.ts --run</code>이며, strict object 계약을 대상으로 한 단일 머신의 초당 실행 횟수입니다. 아래 수치는 회귀를 잡기 위한 로컬 측정값이지, 릴리스 성능 보증값은 아닙니다.</p>
+<p>마지막 로컬 벤치마크는 2026-07-05 KST에 실행했습니다. 명령은 <code>npm run bench -- bench/ecosystem.bench.ts --run</code>이며, strict object 계약을 대상으로 한 단일 머신의 초당 실행 횟수입니다. 아래 수치는 회귀를 잡기 위한 로컬 측정값이지, 릴리스 성능 보증값은 아닙니다.</p>
 <p><img class="benchmark-image" src="assets/benchmark-headline.svg" alt="TypeSea benchmark comparison"></p>
 <p>TypeSea의 안전 모드 컴파일 검증기는 getter 실행 방지와 strict extra key 검사 같은 적대적 입력 방어를 유지하면서도 Ajv의 boolean hot path에 가까운 성능을 냅니다. <code>unsafe</code>와 <code>unchecked</code> FastMode는 호출자가 이미 입력을 정규화했고 객체 그래프를 신뢰할 수 있을 때 쓰는 성능 우선 경로입니다. 이 모드에서는 직접 필드 로드, 할당을 줄인 strict-key loop, V8이 inline cache를 붙이기 쉬운 코드 형태를 사용합니다.</p>
 <blockquote><p>목표는 &quot;대충 유효해 보이면 통과&quot;가 아닙니다. TypeSea의 목표는 <strong>런타임 실행, 컴파일 실행, AOT 실행이 같은 판정을 내린다는 사실을 테스트로 고정하는 검증기</strong>입니다. 사용자 코드를 실행하지 않고, 예상 가능한 실패에서 예외를 던지지 않으며, 공개 API 경계 밖으로 변경 가능한 내부 상태를 내보내지 않는 것을 기본 원칙으로 둡니다.</p></blockquote>
 <aside class="admonition important"><strong class="admonition-title">IMPORTANT</strong><p>TypeSea는 <strong>적대적인 경계 입력</strong>을 전제로 설계했습니다. 속성 읽기는 descriptor를 통하므로 <strong>사용자 getter를 실행하지 않습니다</strong>. <code>__proto__</code>와 <code>constructor</code> key는 null-prototype lookup으로 처리하고, 사용자 regexp는 복제한 뒤 <code>lastIndex</code>를 reset하며, 순환 입력도 유한하게 검증합니다. 예상 가능한 실패는 동결된 <code>Result</code>로 반환합니다. 불명확한 타입 탈출과 암묵적 예외 흐름에 기대지 않도록 코드베이스 전체에 정책 게이트를 둡니다.</p></aside>
+<aside class="admonition warning"><strong class="admonition-title">WARNING</strong><p><code>unsafe</code>와 <code>unchecked</code>는 <strong>public boundary용 모드가 아닙니다</strong>. 이미 신뢰 가능한 plain data로 정규화된 입력에서만 사용하세요. 이 모드에서는 getter 실행, prototype-backed value 수용, 더 약한 strict extra-key 보장을 호출자가 받아들이는 것입니다. 외부 입력에는 기본 safe mode를 쓰는 것이 TypeSea의 보안 계약입니다.</p></aside>
 <hr>
 <h3 id="readme-ko-왜-만들었나">왜 만들었나</h3>
 <p>검증 라이브러리를 실제 경계 입력에 쓰다 보면 다음 조건을 동시에 만족시키기 어렵습니다.</p>
@@ -1263,35 +1273,35 @@ failed check() -&gt; schema-aware diagnostic collector</code></pre>
 <aside class="admonition important"><strong class="admonition-title">IMPORTANT</strong><p>generated validator는 <strong>사용자가 제어하는 값을 소스 문자열에 넣지 않습니다</strong>. literal, regexp, object key, keyset, dynamic schema fallback은 numeric index로 참조되는 <strong>side table</strong>에 둡니다. 적대적인 property name이 generated code 밖으로 탈출할 수 없으며, dedicated injection-audit test가 이 속성을 고정합니다.</p></aside>
 <hr>
 <h3 id="readme-ko-성능-스냅샷">성능 스냅샷</h3>
-<p>마지막 로컬 벤치마크는 2026-07-04 KST에 실행했습니다. <code>npm run bench -- bench/ecosystem.bench.ts --run</code>을 사용했고, benchmark strict-object 계약을 대상으로 했습니다. 아래 값은 단일 머신의 초당 실행 횟수이며 릴리스 성능 보증값은 아닙니다.</p>
-<div class="table-wrap"><table><thead><tr><th>유효한 객체: boolean 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>513,701</td></tr>
-<tr><td>TypeSea compiled safe <code>is()</code></td><td>4,297,306</td></tr>
-<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>36,297,653</td></tr>
-<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>42,581,174</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>1,343,756</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>1,406,528</td></tr>
-<tr><td>Ajv compiled</td><td>4,275,389</td></tr></tbody></table></div>
-<div class="table-wrap"><table><thead><tr><th>유효한 객체: 진단 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>503,232</td></tr>
-<tr><td>TypeSea compiled safe <code>check()</code></td><td>3,903,929</td></tr>
-<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>35,568,425</td></tr>
-<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>40,084,605</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>1,355,014</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>1,378,266</td></tr>
-<tr><td>Ajv compiled</td><td>4,278,587</td></tr></tbody></table></div>
-<div class="table-wrap"><table><thead><tr><th>잘못된 객체: boolean 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>3,636,369</td></tr>
-<tr><td>TypeSea compiled safe <code>is()</code></td><td>42,080,241</td></tr>
-<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>49,654,076</td></tr>
-<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>50,482,732</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>84,272</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>878,521</td></tr>
-<tr><td>Ajv compiled</td><td>27,820,643</td></tr></tbody></table></div>
-<div class="table-wrap"><table><thead><tr><th>잘못된 객체: 진단 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>420,446</td></tr>
-<tr><td>TypeSea compiled safe <code>check()</code></td><td>2,086,129</td></tr>
-<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>3,077,367</td></tr>
-<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>3,673,508</td></tr>
-<tr><td>Zod <code>safeParse</code></td><td>79,613</td></tr>
-<tr><td>Valibot <code>safeParse</code></td><td>887,991</td></tr>
-<tr><td>Ajv compiled</td><td>28,713,035</td></tr></tbody></table></div>
+<p>마지막 로컬 벤치마크는 2026-07-05 KST에 실행했습니다. <code>npm run bench -- bench/ecosystem.bench.ts --run</code>을 사용했고, benchmark strict-object 계약을 대상으로 했습니다. 아래 값은 단일 머신의 초당 실행 횟수이며 릴리스 성능 보증값은 아닙니다.</p>
+<div class="table-wrap"><table><thead><tr><th>유효한 객체: boolean 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>478,576</td></tr>
+<tr><td>TypeSea compiled safe <code>is()</code></td><td>5,109,602</td></tr>
+<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>36,777,097</td></tr>
+<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>42,620,570</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>1,400,045</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>1,400,599</td></tr>
+<tr><td>Ajv compiled</td><td>4,238,036</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>유효한 객체: 진단 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>424,989</td></tr>
+<tr><td>TypeSea compiled safe <code>check()</code></td><td>4,642,948</td></tr>
+<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>37,184,199</td></tr>
+<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>42,487,325</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>1,278,859</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>1,391,040</td></tr>
+<tr><td>Ajv compiled</td><td>4,338,063</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>잘못된 객체: boolean 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>is()</code></td><td>3,325,603</td></tr>
+<tr><td>TypeSea compiled safe <code>is()</code></td><td>43,094,061</td></tr>
+<tr><td>TypeSea compiled unsafe <code>is()</code></td><td>50,738,235</td></tr>
+<tr><td>TypeSea compiled unchecked <code>is()</code></td><td>50,898,012</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>84,647</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>866,013</td></tr>
+<tr><td>Ajv compiled</td><td>30,535,761</td></tr></tbody></table></div>
+<div class="table-wrap"><table><thead><tr><th>잘못된 객체: 진단 경로</th><th>hz</th></tr></thead><tbody><tr><td>TypeSea interpreted <code>check()</code></td><td>405,590</td></tr>
+<tr><td>TypeSea compiled safe <code>check()</code></td><td>2,107,460</td></tr>
+<tr><td>TypeSea compiled unsafe <code>check()</code></td><td>3,186,702</td></tr>
+<tr><td>TypeSea compiled unchecked <code>check()</code></td><td>3,509,673</td></tr>
+<tr><td>Zod <code>safeParse</code></td><td>85,355</td></tr>
+<tr><td>Valibot <code>safeParse</code></td><td>788,870</td></tr>
+<tr><td>Ajv compiled</td><td>29,951,403</td></tr></tbody></table></div>
 <p>safe compiled path는 TypeSea의 적대적 입력 방어를 유지하면서 Ajv에 가깝게 동작합니다. descriptor 기반 property read, symbol/non-enumerable strict-key rejection, key presence semantics, immutable diagnostics, TypeScript guard inference를 유지합니다. unsafe와 unchecked compiled mode는 그 방어 계약 일부를 의도적으로 포기하기 때문에 더 빠릅니다.</p>
 <hr>
 <h3 id="readme-ko-api-레퍼런스-요약">API 레퍼런스 요약</h3>
@@ -1366,12 +1376,20 @@ const Node: Guard&lt;ListNode&gt; = t.lazy((): Guard&lt;ListNode&gt; =&gt;
 npm run check:consumer  # tarball install + runtime/type smoke in a temp project
 npm run bench -- --run  # benchmark smoke
 npm run pack:dry        # package contents dry run
-npm run release:check   # the full pre-publish gate</code></pre>
+npm run release:check   # the full pre-publish gate
+npm run release:publish # provenance를 붙이고 lifecycle script를 무시하는 npm publish</code></pre>
 <p><code>npm run release:check</code>는 publish 전에 기대하는 동일한 gate를 실행합니다. typecheck, lint, tests, build, docs smoke, dist policy, public API snapshot, package contents, consumer install, benchmark smoke, pack dry run을 포함합니다. CI는 Node 20.19, 22, 24에서 실행하고, release는 npm provenance와 함께 publish합니다.</p>
+<p>릴리스 경로:</p>
+<ol><li><code>vX.Y.Z</code> 태그를 push하거나 GitHub <code>Release</code> workflow를 그 태그로 실행합니다.</li><li>release workflow는 tag가 <code>package.json</code>의 version과 일치하는지 확인합니다.</li><li>publish는 GitHub <code>Publish</code> workflow에서 <code>npm run release:publish</code>로 수행합니다. 이 스크립트는 <code>npm publish --provenance --access public --ignore-scripts</code>로 확장됩니다.</li></ol>
+<p>로컬 <code>NPM_TOKEN</code> publish는 수동 복구 릴리스용입니다. 이 경우에도 먼저 <code>npm run release:check</code>를 통과해야 하며, GitHub OIDC provenance는 붙지 않습니다.</p>
 <aside class="admonition note"><strong class="admonition-title">NOTE</strong><p>benchmark 비교 패키지인 Zod, Valibot, Ajv는 dev dependency일 뿐입니다. package policy는 이들이 runtime dependency field에 들어가는 것을 거부합니다. benchmark suite는 boolean path와 diagnostic path(<code>check()</code> vs <code>safeParse</code>)를 모두 보고하므로 비교 기준을 맞춥니다.</p></aside>
 <hr>
 <h3 id="readme-ko-문서">문서</h3>
-<ul><li><a href="#overview">문서 사이트</a></li><li><a href="#api-reference">API 레퍼런스</a></li><li><a href="#engine-notes">엔진 노트</a></li></ul>
+<ul><li><a href="#overview">문서 사이트</a></li><li><a href="#api-reference">API 레퍼런스</a></li><li><a href="#engine-notes">엔진 노트</a></li><li><a href="https://github.com/Feralthedogg/TypeSea/blob/main/SECURITY.md">보안 정책</a></li></ul>
+<hr>
+<h3 id="readme-ko-마이그레이션-노트">마이그레이션 노트</h3>
+<h4 id="readme-ko-0-3-0에서-0-3-1">0.3.0에서 0.3.1</h4>
+<p>애플리케이션 코드 변경은 필요하지 않습니다. <code>0.3.1</code>은 release hardening patch입니다. manual release tag 처리를 더 엄격하게 만들고, npm provenance 기대치를 문서화하며, security policy를 추가하고, GitHub publish workflow가 끝난 뒤 npm에 새 버전이 실제로 보이는지 확인합니다.</p>
 <hr>
 <h3 id="readme-ko-라이선스">라이선스</h3>
 <p>MIT License. 자세한 내용은 <a href="https://github.com/Feralthedogg/TypeSea/blob/main/LICENSE">LICENSE</a>를 보세요.</p>
@@ -1472,6 +1490,12 @@ const Node: Guard&lt;ListNode&gt; = t.lazy((): Guard&lt;ListNode&gt; =&gt;
 const result = Count.decode(&quot;42&quot;);
 
 const Name = t.default(t.string.min(1), &quot;anonymous&quot;);
+const NormalizedName = t.string
+  .trim()
+  .pipe(t.string.min(1))
+  .transform((value) =&gt; value.toLowerCase())
+  .default(&quot;anonymous&quot;)
+  .catch(&quot;anonymous&quot;);
 const NumberText = t.codec(
   t.string.regex(/^\d+$/u, &quot;digits&quot;),
   t.number.int().nonnegative(),
@@ -1481,11 +1505,7 @@ const NumberText = t.codec(
   }
 );</code></pre>
 <p>Decoders are for output-producing operations. They return <code>Result</code> from <code>decode()</code> and do not expose <code>is()</code> predicates, because the decoded output may not be the same runtime value as the input.</p>
-<ul><li><code>t.transform(source, mapper)</code> decodes <code>source</code>, then maps the decoded value.</li><li><code>t.pipe(source, next)</code> feeds a successful decoded value into the next guard or</li></ul>
-<p>decoder.</p>
-<ul><li><code>t.default(source, value)</code> returns a fallback output for <code>undefined</code> input.</li><li><code>t.prefault(source, value)</code> feeds a fallback input through the source.</li><li><code>t.codec(input, output, mapping)</code> validates both sides of a bidirectional</li></ul>
-<p>decode/encode pair.</p>
-<ul><li><code>t.coerce.string</code>, <code>t.coerce.number</code>, and <code>t.coerce.boolean</code> provide explicit</li></ul>
+<ul><li><code>t.transform(source, mapper)</code> decodes <code>source</code>, then maps the decoded value.</li><li><code>t.pipe(source, next)</code> feeds a successful decoded value into the next guard or decoder.</li><li><code>t.default(source, value)</code> returns a fallback output for <code>undefined</code> input.</li><li><code>t.prefault(source, value)</code> feeds a fallback input through the source.</li><li><code>t.catch(source, value)</code> returns a fallback output after a failed decode.</li><li><code>t.codec(input, output, mapping)</code> validates both sides of a bidirectional decode/encode pair.</li><li><code>t.coerce.string</code>, <code>t.coerce.number</code>, and <code>t.coerce.boolean</code> provide explicit</li></ul>
 <p>primitive coercion.</p>
 <ul><li><code>t.string.trim()</code>, <code>t.string.toLowerCase()</code>, and <code>t.string.toUpperCase()</code></li></ul>
 <p>are decoder helpers. They validate the string first, then return transformed output from <code>decode()</code>.</p>
@@ -1545,7 +1565,7 @@ const resolver = toReactHookFormResolver(User);</code></pre>
 <pre><code>const FastUser = compile(User);
 const fastParser = toTrpcParser(FastUser);
 const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);</code></pre>
-<p>Use the default compiled mode at public input boundaries. For trusted, already-normalized internal data, the faster modes can be wired through adapters the same way.</p>
+<p>Use the default compiled mode at public input boundaries. It keeps the safe descriptor-read contract even when an adapter hides the direct <code>is()</code> call. For trusted, already-normalized internal data, the faster modes can be wired through adapters the same way.</p>
 <pre><code>const UnsafeUser = compile(User, { mode: &quot;unsafe&quot; });
 const internalParser = toTrpcParser(UnsafeUser);
 
@@ -1663,6 +1683,12 @@ const Node: Guard&lt;ListNode&gt; = t.lazy((): Guard&lt;ListNode&gt; =&gt;
 const result = Count.decode(&quot;42&quot;);
 
 const Name = t.default(t.string.min(1), &quot;anonymous&quot;);
+const NormalizedName = t.string
+  .trim()
+  .pipe(t.string.min(1))
+  .transform((value) =&gt; value.toLowerCase())
+  .default(&quot;anonymous&quot;)
+  .catch(&quot;anonymous&quot;);
 const NumberText = t.codec(
   t.string.regex(/^\d+$/u, &quot;digits&quot;),
   t.number.int().nonnegative(),
@@ -1672,7 +1698,7 @@ const NumberText = t.codec(
   }
 );</code></pre>
 <p>decoder는 output을 생성하는 작업에 씁니다. <code>decode()</code>에서 <code>Result</code>를 반환하며 <code>is()</code> predicate를 노출하지 않습니다. decoded output이 input과 같은 runtime value가 아닐 수 있기 때문입니다.</p>
-<ul><li><code>t.transform(source, mapper)</code>는 <code>source</code>를 decode한 뒤 decoded value를 map합니다.</li><li><code>t.pipe(source, next)</code>는 성공한 decoded value를 다음 guard 또는 decoder에 넘깁니다.</li><li><code>t.default(source, value)</code>는 input이 <code>undefined</code>일 때 fallback output을 바로 반환합니다.</li><li><code>t.prefault(source, value)</code>는 input이 <code>undefined</code>일 때 fallback input을 source에 다시 통과시킵니다.</li><li><code>t.codec(input, output, mapping)</code>은 bidirectional decode/encode 양쪽을 모두 검증합니다.</li><li><code>t.coerce.string</code>, <code>t.coerce.number</code>, <code>t.coerce.boolean</code>은 명시적 primitive coercion을 제공합니다.</li><li><code>t.string.trim()</code>, <code>t.string.toLowerCase()</code>, <code>t.string.toUpperCase()</code>는 decoder helper입니다. 먼저 string을 검증한 뒤 <code>decode()</code> 결과로 변환된 값을 반환합니다.</li><li><code>t.asyncRefine</code>, <code>t.asyncTransform</code>, <code>t.asyncPipe</code>는 <code>decodeAsync()</code>에서 <code>Promise&lt;Result&lt;T, Issue[]&gt;&gt;</code>를 반환합니다.</li></ul>
+<ul><li><code>t.transform(source, mapper)</code>는 <code>source</code>를 decode한 뒤 decoded value를 map합니다.</li><li><code>t.pipe(source, next)</code>는 성공한 decoded value를 다음 guard 또는 decoder에 넘깁니다.</li><li><code>t.default(source, value)</code>는 input이 <code>undefined</code>일 때 fallback output을 바로 반환합니다.</li><li><code>t.prefault(source, value)</code>는 input이 <code>undefined</code>일 때 fallback input을 source에 다시 통과시킵니다.</li><li><code>t.catch(source, value)</code>는 decode 실패 시 fallback output을 반환합니다.</li><li><code>t.codec(input, output, mapping)</code>은 bidirectional decode/encode 양쪽을 모두 검증합니다.</li><li><code>t.coerce.string</code>, <code>t.coerce.number</code>, <code>t.coerce.boolean</code>은 명시적 primitive coercion을 제공합니다.</li><li><code>t.string.trim()</code>, <code>t.string.toLowerCase()</code>, <code>t.string.toUpperCase()</code>는 decoder helper입니다. 먼저 string을 검증한 뒤 <code>decode()</code> 결과로 변환된 값을 반환합니다.</li><li><code>t.asyncRefine</code>, <code>t.asyncTransform</code>, <code>t.asyncPipe</code>는 <code>decodeAsync()</code>에서 <code>Promise&lt;Result&lt;T, Issue[]&gt;&gt;</code>를 반환합니다.</li></ul>
 <p>예상 가능한 async validation 실패도 <code>Result</code>로 반환됩니다.</p>
 <h3 id="api-reference-ko-message">Message</h3>
 <pre><code>const checked = withMessages(User.check(input), {
@@ -1725,7 +1751,7 @@ const resolver = toReactHookFormResolver(User);</code></pre>
 <pre><code>const FastUser = compile(User);
 const fastParser = toTrpcParser(FastUser);
 const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);</code></pre>
-<p>public input boundary에서는 기본 compiled mode를 쓰세요. 신뢰된, 이미 정규화된 내부 데이터에서는 더 빠른 mode를 같은 방식으로 adapter에 연결할 수 있습니다.</p>
+<p>public input boundary에서는 기본 compiled mode를 쓰세요. adapter가 직접 <code>is()</code> 호출을 숨기더라도 safe descriptor-read 계약은 유지됩니다. 신뢰된, 이미 정규화된 내부 데이터에서는 더 빠른 mode를 같은 방식으로 adapter에 연결할 수 있습니다.</p>
 <pre><code>const UnsafeUser = compile(User, { mode: &quot;unsafe&quot; });
 const internalParser = toTrpcParser(UnsafeUser);
 
@@ -1822,11 +1848,11 @@ const optimized = optimizeGraph(graph);</code></pre>
 <ul><li><code>ecosystem.bench.ts</code> compares TypeSea runtime-plan, TypeSea compiled, Zod,</li></ul>
 <p>Valibot, and Ajv over one JSON-compatible strict-object contract.</p>
 <p>Zod, Valibot, and Ajv are dev dependencies for measurement only. They are not imported by <code>src</code>, and package policy rejects runtime, peer, optional, or bundled dependency fields before release.</p>
-<p>Last local benchmark on 2026-07-04 KST reported these ecosystem paths over the JSON-compatible strict-object benchmark:</p>
-<div class="table-wrap"><table><thead><tr><th>Case</th><th>TypeSea runtime plan</th><th>TypeSea compiled safe</th><th>TypeSea compiled unsafe</th><th>TypeSea compiled unchecked</th><th>Ajv compiled</th></tr></thead><tbody><tr><td>Valid <code>is()</code></td><td>513,701 hz</td><td>4,297,306 hz</td><td>36,297,653 hz</td><td>42,581,174 hz</td><td>4,275,389 hz</td></tr>
-<tr><td>Valid <code>check()</code></td><td>503,232 hz</td><td>3,903,929 hz</td><td>35,568,425 hz</td><td>40,084,605 hz</td><td>4,278,587 hz</td></tr>
-<tr><td>Invalid <code>is()</code></td><td>3,636,369 hz</td><td>42,080,241 hz</td><td>49,654,076 hz</td><td>50,482,732 hz</td><td>27,820,643 hz</td></tr>
-<tr><td>Invalid <code>check()</code></td><td>420,446 hz</td><td>2,086,129 hz</td><td>3,077,367 hz</td><td>3,673,508 hz</td><td>28,713,035 hz</td></tr></tbody></table></div>
+<p>Last local benchmark on 2026-07-05 KST reported these ecosystem paths over the JSON-compatible strict-object benchmark:</p>
+<div class="table-wrap"><table><thead><tr><th>Case</th><th>TypeSea runtime plan</th><th>TypeSea compiled safe</th><th>TypeSea compiled unsafe</th><th>TypeSea compiled unchecked</th><th>Ajv compiled</th></tr></thead><tbody><tr><td>Valid <code>is()</code></td><td>478,576 hz</td><td>5,109,602 hz</td><td>36,777,097 hz</td><td>42,620,570 hz</td><td>4,238,036 hz</td></tr>
+<tr><td>Valid <code>check()</code></td><td>424,989 hz</td><td>4,642,948 hz</td><td>37,184,199 hz</td><td>42,487,325 hz</td><td>4,338,063 hz</td></tr>
+<tr><td>Invalid <code>is()</code></td><td>3,325,603 hz</td><td>43,094,061 hz</td><td>50,738,235 hz</td><td>50,898,012 hz</td><td>30,535,761 hz</td></tr>
+<tr><td>Invalid <code>check()</code></td><td>405,590 hz</td><td>2,107,460 hz</td><td>3,186,702 hz</td><td>3,509,673 hz</td><td>29,951,403 hz</td></tr></tbody></table></div>
 <p>Benchmark numbers are machine-local telemetry. They are useful for catching regressions, not for promising a fixed throughput floor. Unsafe and unchecked numbers are not hostile-input equivalent to safe mode.</p>
             </div>
             <div class="locale-ko" lang="ko">
@@ -1865,11 +1891,11 @@ const optimized = optimizeGraph(graph);</code></pre>
 <p>benchmark suite는 두 질문을 분리합니다.</p>
 <ul><li><code>compile.bench.ts</code>는 같은 TypeSea schema를 대상으로 TypeSea runtime-plan validator와 compiled validator를 비교합니다.</li><li><code>ecosystem.bench.ts</code>는 하나의 JSON-compatible strict-object contract를 대상으로 TypeSea runtime-plan, TypeSea compiled, Zod, Valibot, Ajv를 비교합니다.</li></ul>
 <p>Zod, Valibot, Ajv는 측정용 dev dependency입니다. <code>src</code>에서 import하지 않으며, package policy는 release 전에 runtime, peer, optional, bundled dependency field를 거부합니다.</p>
-<p>2026-07-04 KST의 마지막 로컬 벤치마크는 JSON-compatible strict-object benchmark에서 아래 ecosystem path를 보고했습니다.</p>
-<div class="table-wrap"><table><thead><tr><th>Case</th><th>TypeSea runtime plan</th><th>TypeSea compiled safe</th><th>TypeSea compiled unsafe</th><th>TypeSea compiled unchecked</th><th>Ajv compiled</th></tr></thead><tbody><tr><td>Valid <code>is()</code></td><td>513,701 hz</td><td>4,297,306 hz</td><td>36,297,653 hz</td><td>42,581,174 hz</td><td>4,275,389 hz</td></tr>
-<tr><td>Valid <code>check()</code></td><td>503,232 hz</td><td>3,903,929 hz</td><td>35,568,425 hz</td><td>40,084,605 hz</td><td>4,278,587 hz</td></tr>
-<tr><td>Invalid <code>is()</code></td><td>3,636,369 hz</td><td>42,080,241 hz</td><td>49,654,076 hz</td><td>50,482,732 hz</td><td>27,820,643 hz</td></tr>
-<tr><td>Invalid <code>check()</code></td><td>420,446 hz</td><td>2,086,129 hz</td><td>3,077,367 hz</td><td>3,673,508 hz</td><td>28,713,035 hz</td></tr></tbody></table></div>
+<p>2026-07-05 KST의 마지막 로컬 벤치마크는 JSON-compatible strict-object benchmark에서 아래 ecosystem path를 보고했습니다.</p>
+<div class="table-wrap"><table><thead><tr><th>Case</th><th>TypeSea runtime plan</th><th>TypeSea compiled safe</th><th>TypeSea compiled unsafe</th><th>TypeSea compiled unchecked</th><th>Ajv compiled</th></tr></thead><tbody><tr><td>Valid <code>is()</code></td><td>478,576 hz</td><td>5,109,602 hz</td><td>36,777,097 hz</td><td>42,620,570 hz</td><td>4,238,036 hz</td></tr>
+<tr><td>Valid <code>check()</code></td><td>424,989 hz</td><td>4,642,948 hz</td><td>37,184,199 hz</td><td>42,487,325 hz</td><td>4,338,063 hz</td></tr>
+<tr><td>Invalid <code>is()</code></td><td>3,325,603 hz</td><td>43,094,061 hz</td><td>50,738,235 hz</td><td>50,898,012 hz</td><td>30,535,761 hz</td></tr>
+<tr><td>Invalid <code>check()</code></td><td>405,590 hz</td><td>2,107,460 hz</td><td>3,186,702 hz</td><td>3,509,673 hz</td><td>29,951,403 hz</td></tr></tbody></table></div>
 <p>benchmark number는 machine-local telemetry입니다. regression을 잡는 데 유용하지만 고정된 throughput floor를 약속하지 않습니다. unsafe와 unchecked number는 safe mode와 hostile-input equivalent가 아닙니다.</p>
             </div>
           </article>

package/docs/ko/api.md

@@ -135,6 +135,12 @@ const Count = t.pipe(t.coerce.number(), t.number.int().gte(0));
 const result = Count.decode("42");
 
 const Name = t.default(t.string.min(1), "anonymous");
+const NormalizedName = t.string
+  .trim()
+  .pipe(t.string.min(1))
+  .transform((value) => value.toLowerCase())
+  .default("anonymous")
+  .catch("anonymous");
 const NumberText = t.codec(
   t.string.regex(/^\d+$/u, "digits"),
   t.number.int().nonnegative(),
@@ -153,6 +159,7 @@ decoded output이 input과 같은 runtime value가 아닐 수 있기 때문입
 - `t.pipe(source, next)`는 성공한 decoded value를 다음 guard 또는 decoder에 넘깁니다.
 - `t.default(source, value)`는 input이 `undefined`일 때 fallback output을 바로 반환합니다.
 - `t.prefault(source, value)`는 input이 `undefined`일 때 fallback input을 source에 다시 통과시킵니다.
+- `t.catch(source, value)`는 decode 실패 시 fallback output을 반환합니다.
 - `t.codec(input, output, mapping)`은 bidirectional decode/encode 양쪽을 모두 검증합니다.
 - `t.coerce.string`, `t.coerce.number`, `t.coerce.boolean`은 명시적 primitive coercion을 제공합니다.
 - `t.string.trim()`, `t.string.toLowerCase()`, `t.string.toUpperCase()`는 decoder helper입니다. 먼저 string을 검증한 뒤 `decode()` 결과로 변환된 값을 반환합니다.
@@ -287,6 +294,7 @@ const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);
 ```
 
 public input boundary에서는 기본 compiled mode를 쓰세요.
+adapter가 직접 `is()` 호출을 숨기더라도 safe descriptor-read 계약은 유지됩니다.
 신뢰된, 이미 정규화된 내부 데이터에서는 더 빠른 mode를 같은 방식으로 adapter에 연결할 수 있습니다.
 
 ```ts

package/docs/ko/engine-notes.md

@@ -142,14 +142,14 @@ benchmark suite는 두 질문을 분리합니다.
 Zod, Valibot, Ajv는 측정용 dev dependency입니다.
 `src`에서 import하지 않으며, package policy는 release 전에 runtime, peer, optional, bundled dependency field를 거부합니다.
 
-2026-07-04 KST의 마지막 로컬 벤치마크는 JSON-compatible strict-object benchmark에서 아래 ecosystem path를 보고했습니다.
+2026-07-05 KST의 마지막 로컬 벤치마크는 JSON-compatible strict-object benchmark에서 아래 ecosystem path를 보고했습니다.
 
 | Case | TypeSea runtime plan | TypeSea compiled safe | TypeSea compiled unsafe | TypeSea compiled unchecked | Ajv compiled |
 | --- | ---: | ---: | ---: | ---: | ---: |
-| Valid `is()` | 513,701 hz | 4,297,306 hz | 36,297,653 hz | 42,581,174 hz | 4,275,389 hz |
-| Valid `check()` | 503,232 hz | 3,903,929 hz | 35,568,425 hz | 40,084,605 hz | 4,278,587 hz |
-| Invalid `is()` | 3,636,369 hz | 42,080,241 hz | 49,654,076 hz | 50,482,732 hz | 27,820,643 hz |
-| Invalid `check()` | 420,446 hz | 2,086,129 hz | 3,077,367 hz | 3,673,508 hz | 28,713,035 hz |
+| Valid `is()` | 478,576 hz | 5,109,602 hz | 36,777,097 hz | 42,620,570 hz | 4,238,036 hz |
+| Valid `check()` | 424,989 hz | 4,642,948 hz | 37,184,199 hz | 42,487,325 hz | 4,338,063 hz |
+| Invalid `is()` | 3,325,603 hz | 43,094,061 hz | 50,738,235 hz | 50,898,012 hz | 30,535,761 hz |
+| Invalid `check()` | 405,590 hz | 2,107,460 hz | 3,186,702 hz | 3,509,673 hz | 29,951,403 hz |
 
 benchmark number는 machine-local telemetry입니다.
 regression을 잡는 데 유용하지만 고정된 throughput floor를 약속하지 않습니다.

package/docs/ko/readme.md

@@ -5,7 +5,7 @@
 
 ## 벤치마크 요약
 
-마지막 로컬 벤치마크는 2026-07-04 KST에 실행했습니다.
+마지막 로컬 벤치마크는 2026-07-05 KST에 실행했습니다.
 명령은 `npm run bench -- bench/ecosystem.bench.ts --run`이며, strict object 계약을 대상으로 한 단일 머신의 초당 실행 횟수입니다.
 아래 수치는 회귀를 잡기 위한 로컬 측정값이지, 릴리스 성능 보증값은 아닙니다.
 
@@ -26,6 +26,12 @@ TypeSea의 안전 모드 컴파일 검증기는 getter 실행 방지와 strict e
 > 예상 가능한 실패는 동결된 `Result`로 반환합니다.
 > 불명확한 타입 탈출과 암묵적 예외 흐름에 기대지 않도록 코드베이스 전체에 정책 게이트를 둡니다.
 
+> [!WARNING]
+> `unsafe`와 `unchecked`는 **public boundary용 모드가 아닙니다**.
+> 이미 신뢰 가능한 plain data로 정규화된 입력에서만 사용하세요.
+> 이 모드에서는 getter 실행, prototype-backed value 수용, 더 약한 strict extra-key 보장을 호출자가 받아들이는 것입니다.
+> 외부 입력에는 기본 safe mode를 쓰는 것이 TypeSea의 보안 계약입니다.
+
 ---
 
 ## 왜 만들었나
@@ -178,49 +184,49 @@ failed check() -> schema-aware diagnostic collector
 
 ## 성능 스냅샷
 
-마지막 로컬 벤치마크는 2026-07-04 KST에 실행했습니다.
+마지막 로컬 벤치마크는 2026-07-05 KST에 실행했습니다.
 `npm run bench -- bench/ecosystem.bench.ts --run`을 사용했고, benchmark strict-object 계약을 대상으로 했습니다.
 아래 값은 단일 머신의 초당 실행 횟수이며 릴리스 성능 보증값은 아닙니다.
 
 | 유효한 객체: boolean 경로 | hz |
 | --- | ---: |
-| TypeSea interpreted `is()` | 513,701 |
-| TypeSea compiled safe `is()` | 4,297,306 |
-| TypeSea compiled unsafe `is()` | 36,297,653 |
-| TypeSea compiled unchecked `is()` | 42,581,174 |
-| Zod `safeParse` | 1,343,756 |
-| Valibot `safeParse` | 1,406,528 |
-| Ajv compiled | 4,275,389 |
+| TypeSea interpreted `is()` | 478,576 |
+| TypeSea compiled safe `is()` | 5,109,602 |
+| TypeSea compiled unsafe `is()` | 36,777,097 |
+| TypeSea compiled unchecked `is()` | 42,620,570 |
+| Zod `safeParse` | 1,400,045 |
+| Valibot `safeParse` | 1,400,599 |
+| Ajv compiled | 4,238,036 |
 
 | 유효한 객체: 진단 경로 | hz |
 | --- | ---: |
-| TypeSea interpreted `check()` | 503,232 |
-| TypeSea compiled safe `check()` | 3,903,929 |
-| TypeSea compiled unsafe `check()` | 35,568,425 |
-| TypeSea compiled unchecked `check()` | 40,084,605 |
-| Zod `safeParse` | 1,355,014 |
-| Valibot `safeParse` | 1,378,266 |
-| Ajv compiled | 4,278,587 |
+| TypeSea interpreted `check()` | 424,989 |
+| TypeSea compiled safe `check()` | 4,642,948 |
+| TypeSea compiled unsafe `check()` | 37,184,199 |
+| TypeSea compiled unchecked `check()` | 42,487,325 |
+| Zod `safeParse` | 1,278,859 |
+| Valibot `safeParse` | 1,391,040 |
+| Ajv compiled | 4,338,063 |
 
 | 잘못된 객체: boolean 경로 | hz |
 | --- | ---: |
-| TypeSea interpreted `is()` | 3,636,369 |
-| TypeSea compiled safe `is()` | 42,080,241 |
-| TypeSea compiled unsafe `is()` | 49,654,076 |
-| TypeSea compiled unchecked `is()` | 50,482,732 |
-| Zod `safeParse` | 84,272 |
-| Valibot `safeParse` | 878,521 |
-| Ajv compiled | 27,820,643 |
+| TypeSea interpreted `is()` | 3,325,603 |
+| TypeSea compiled safe `is()` | 43,094,061 |
+| TypeSea compiled unsafe `is()` | 50,738,235 |
+| TypeSea compiled unchecked `is()` | 50,898,012 |
+| Zod `safeParse` | 84,647 |
+| Valibot `safeParse` | 866,013 |
+| Ajv compiled | 30,535,761 |
 
 | 잘못된 객체: 진단 경로 | hz |
 | --- | ---: |
-| TypeSea interpreted `check()` | 420,446 |
-| TypeSea compiled safe `check()` | 2,086,129 |
-| TypeSea compiled unsafe `check()` | 3,077,367 |
-| TypeSea compiled unchecked `check()` | 3,673,508 |
-| Zod `safeParse` | 79,613 |
-| Valibot `safeParse` | 887,991 |
-| Ajv compiled | 28,713,035 |
+| TypeSea interpreted `check()` | 405,590 |
+| TypeSea compiled safe `check()` | 2,107,460 |
+| TypeSea compiled unsafe `check()` | 3,186,702 |
+| TypeSea compiled unchecked `check()` | 3,509,673 |
+| Zod `safeParse` | 85,355 |
+| Valibot `safeParse` | 788,870 |
+| Ajv compiled | 29,951,403 |
 
 safe compiled path는 TypeSea의 적대적 입력 방어를 유지하면서 Ajv에 가깝게 동작합니다.
 descriptor 기반 property read, symbol/non-enumerable strict-key rejection, key presence semantics, immutable diagnostics, TypeScript guard inference를 유지합니다.
@@ -352,12 +358,21 @@ npm run check:consumer  # tarball install + runtime/type smoke in a temp project
 npm run bench -- --run  # benchmark smoke
 npm run pack:dry        # package contents dry run
 npm run release:check   # the full pre-publish gate
+npm run release:publish # provenance를 붙이고 lifecycle script를 무시하는 npm publish
 ```
 
 `npm run release:check`는 publish 전에 기대하는 동일한 gate를 실행합니다.
 typecheck, lint, tests, build, docs smoke, dist policy, public API snapshot, package contents, consumer install, benchmark smoke, pack dry run을 포함합니다.
 CI는 Node 20.19, 22, 24에서 실행하고, release는 npm provenance와 함께 publish합니다.
 
+릴리스 경로:
+
+1. `vX.Y.Z` 태그를 push하거나 GitHub `Release` workflow를 그 태그로 실행합니다.
+2. release workflow는 tag가 `package.json`의 version과 일치하는지 확인합니다.
+3. publish는 GitHub `Publish` workflow에서 `npm run release:publish`로 수행합니다. 이 스크립트는 `npm publish --provenance --access public --ignore-scripts`로 확장됩니다.
+
+로컬 `NPM_TOKEN` publish는 수동 복구 릴리스용입니다. 이 경우에도 먼저 `npm run release:check`를 통과해야 하며, GitHub OIDC provenance는 붙지 않습니다.
+
 > [!NOTE]
 > benchmark 비교 패키지인 Zod, Valibot, Ajv는 dev dependency일 뿐입니다.
 > package policy는 이들이 runtime dependency field에 들어가는 것을 거부합니다.
@@ -370,6 +385,17 @@ CI는 Node 20.19, 22, 24에서 실행하고, release는 npm provenance와 함께
 - [문서 사이트](https://feralthedogg.github.io/TypeSea/)
 - [API 레퍼런스](../api.md)
 - [엔진 노트](../engine-notes.md)
+- [보안 정책](https://github.com/Feralthedogg/TypeSea/blob/main/SECURITY.md)
+
+---
+
+## 마이그레이션 노트
+
+### 0.3.0에서 0.3.1
+
+애플리케이션 코드 변경은 필요하지 않습니다.
+`0.3.1`은 release hardening patch입니다.
+manual release tag 처리를 더 엄격하게 만들고, npm provenance 기대치를 문서화하며, security policy를 추가하고, GitHub publish workflow가 끝난 뒤 npm에 새 버전이 실제로 보이는지 확인합니다.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "typesea",
-    "version": "0.3.0",
+    "version": "0.3.1",
     "description": "V8-friendly runtime narrowing for TypeScript with Sea-of-Nodes graph introspection.",
     "type": "module",
     "author": "feral",
@@ -30,6 +30,7 @@
     "files": [
         "dist",
         "README.md",
+        "SECURITY.md",
         "CHANGELOG.md",
         "docs"
     ],
@@ -48,6 +49,8 @@
         "policy": "node scripts/source-policy.mjs",
         "prepack": "npm run check",
         "release:check": "node scripts/release-gate.mjs",
+        "release:publish": "npm publish --provenance --access public --ignore-scripts",
+        "release:verify-published": "node scripts/verify-published-version.mjs",
         "test": "vitest run",
         "typecheck": "tsc -p tsconfig.json --noEmit"
     },