@jini-ai/core 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# @jini-ai/core
+
+## 0.4.1 — 2026-10-05
+
+- New `readToolLimit({ input, max, fallback }, { key })`: an absent limit is `fallback`, one above `max` is capped at `max`, and a non-integer or one below 1 throws `ToolInputError` ("'limit' must be an integer between 1 and <max>").
+- New `optionalOneOf({ input, key, values })`: a value outside `values` throws `ToolInputError` ("'<key>' must be one of: ..."). Both are additive.
+
+## 0.4.0 — 2026-10-02
+
+### BREAKING
+
+- Canonical primitive ports, JSON/time/HTTP types and tool contracts now live in core; use ./composition instead of ./internal and ./text for untrusted-text handling.
+- Distribution includes runtime output, release documentation and required assets only. Process records and per-job neutrality checks are no longer part of the package surface.
+
+## Unreleased
+
+- Add browser-safe `pathContains` to `./primitives` for absolute lexical paths, with host-selected case sensitivity and complete directory-segment boundaries.
+
+### Shared registration wiring
+
+- Move the domain-independent catalog/input/schema/risk/confirmation registration kit into the root entry, with its behavior contracts. Domain-specific authorization and denial errors remain outside the kernel.
+- Use the existing named argument surface directly; primitive, Result and tool catalog types remain canonical in core.
+
+
+### Shared kernel
+
+- Add `./primitives` with canonical time, ID, JSON, HTTP, logger and result contracts,
+  system/crypto/console default adapters, and UTC time helpers. No runtime dependencies.
+- Add root agent-tool catalog types, preserving delete as a distinct risk classification.
+- Add `./text` with the unchanged bounded terminal sanitizer and its behavior tests.
+- Expand telemetry redaction to the union of core, CLI and provider rules, with literal
+  exact-secret masking and named extra patterns. Export the eleven diagnostics credential
+  regexes unchanged. Broader opaque/short bearer/header/query rules can mask more input;
+  union vectors and existing category tests document the behavior.
+- Add UTF-8 `timingSafeTokenMatch` with a required injected native comparison port so the
+  kernel stays universal. Both original native comparators have identical results.
+
+### BREAKING — shared kernel
+
+- Rename `./internal` to `./composition` without an alias. Authorized tool invocation and
+  pack binding derivation keep their implementation and security boundary.
+- Gated mutations now require `Clock.nowMs()` and `IdGenerator.newId()` from primitives,
+  replacing the local `ClockPort.nowIso({})` and `IdGeneratorPort.newId({})`. Format clock
+  samples with `nowIso({ clock })`; approval order, TTL and wire timestamps are unchanged.
+- Origin diagnostics use `Pick<Logger, 'warn'>` rather than a duplicate logger interface.
+  The alias name `OriginValidationLoggerPort` remains available with the shared shape.
+
+
+- Add transport-neutral gated mutations with required token generation/TTL and async
+  authorization, identity and token-store ports; preserve verified-plan handoff and
+  single-use redemption, with atomic explicit expiry and duplicate-issuance rejection.
+- Add domain-owned model-facing error allowlists, an instance-owned contribution
+  registry, and bounded naming with required collision, suffix and message policies.
+- Add generalized approval, disclosure, registry and naming contract tests plus a
+  package-wide source-neutrality guard. Verification is deferred by owner directive;
+  the four subpath manifest exports are listed in `extraction-w4a.md` for coordination.
+
+### Extraction integration
+
+- Publish `./gated-mutations`, `./model-facing-tool-errors`, `./contribution-registry`
+  and `./naming`, with universal runtime metadata and matching root barrel exports.
+  These entries implement the earlier manifest follow-ups in `extraction-w4a.md`;
+  no runtime dependency or version change is required.
+- BREAKING: Existing core APIs now accept a required-args object and a separate
+  optional-args object. Tokens, bindings, registry lookups, pack callbacks/lifecycle,
+  redaction, auth/origin helpers, ToolInputError and internal authorization changed
+  shape with no compatibility adapters. Environment snapshots are explicit, origin
+  logging uses a supplied port, and optional handler emitSurface moved to the second
+  argument. Update consumers before adopting this release. Version unchanged.
+- BREAKING: New extraction APIs follow the same convention: contribution
+  `list({})`/`clear({})`, `new InMemoryTokenStore({})`/`count({})`, approval
+  `computePlan({})`, `nowIso({})`, `newId({})` and `generateToken({})`, and marker-error
+  constructors `new ErrorClass({ message }, { cause? })`. `ForbiddenError` additionally
+  requires `reasonCode`; naming exhaustion callbacks receive `{ base, maxAttempts }`.
+  `AuthorizeFn` moves optional `entityType`/`entityId` selectors to its second object.
+- Add package-entry identity, manifest/runtime, approval-port, error-cause and
+  convention contract tests. Extend the source-neutrality guard to the manifest.
+  All verification remains not run (owner directive).
+
+## 0.1.2
+
+### Patch Changes
+
+- Add top-level `main`/`types` fields alongside the existing `exports` map. A consumer on
+  TypeScript's classic `moduleResolution: "node"` (node10) — which ignores `package.json#exports`
+  entirely — could not resolve this package's types at all (`TS2307: Cannot find module`) even
+  after the previous exports-map fix restored `require()` at runtime; type resolution and runtime
+  resolution are separate algorithms. Verified against a real external consumer (whose
+  tsconfig uses this legacy resolution mode): adding these two fields, with its tsconfig completely
+  unchanged, made the error disappear. Also fixes absolute-path `require()` (distinct from a bare
+  specifier, which already worked) for the same reason — `main` was previously absent.
+
+  Purely additive: every modern resolver (Node's own runtime `exports` resolution, TypeScript's
+  `bundler`/`node16`/`nodenext`) prefers `exports` over `main`/`types` when both are present, so
+  this changes nothing for a consumer already on a modern resolver.
+
+## 0.1.1
+
+### Patch Changes
+
+- Add a `"default"` export condition to every published package's `exports` map — every one of
+  them lacked it, which meant `require()` failed with `ERR_PACKAGE_PATH_NOT_EXPORTED` for any
+  CommonJS consumer (found via a real external integration attempt; Node needs `require(esm)`
+  support, i.e. Node >=22.12, for this to resolve).
+
+  `@jini-ai/agent-runtime`:
+
+  - **New**: `RuntimeBuildOptions.permissionMode` (`'bypass' | 'restricted'`) lets a caller opt a
+    run OUT of the auto-approve-every-permission-prompt flag every def with one
+    (`bypassPermissions` / `--yolo` / `--dangerously-skip-permissions`) previously pushed
+    unconditionally, with no way to turn it off. Omitting it keeps today's default (bypass)
+    behavior unchanged.
+  - **New**: `ClaudeStreamEvent`, `CopilotStreamEvent`, and `QoderEvent` are now real exported
+    discriminated unions instead of `Record<string, unknown>` — a real external consumer guessed a
+    nonexistent field name (`event.text` instead of the actual `event.delta`) against the old
+    untyped sink and silently lost every streamed token with no compile or runtime error.
+  - Fixed a doc/implementation mismatch in `claude-stream.ts`: the module doc claimed `tool_result`
+    events carry `{ tool_use_id, content, is_error }`; the actual emitted shape is
+    `{ toolUseId, content, isError }`.
+
+  `@jini-ai/daemon`: `AgentExecutorRunInput.permissionMode` forwards the new
+  `RuntimeBuildOptions.permissionMode` through to `buildArgs`, so a host can actually reach the new
+  opt-out from the daemon's real run-input surface, not just from `@jini-ai/agent-runtime` in
+  isolation.
+
+  `@jini-ai/agentic`: `setAtPointer` no longer throws on a malformed (e.g. missing leading `/`)
+  `updateDataModel` path — degrades to a no-op like its sibling `getAtPointer`, matching this
+  package's own "a bad binding must not crash the renderer" contract. That path is agent-authored
+  wire data with no error boundary above it in any host, so the uncaught throw could unmount an
+  entire chat UI from ~40 bytes of malformed input.
+
+  `@jini-ai/chat-react`: a local (client-resolved) A2UI button action is no longer a silent no-op —
+  `A2uiSurfaceCard` now surfaces the resolved value. New `ExtEventErrorBoundary` confines a
+  `kind: 'ext'` event group's renderer to its own card instead of letting a render/effect-phase
+  throw from agent-controlled content unmount the whole chat root (there was no error boundary
+  anywhere in this package or its hosts before this).

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Open Design contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -19,17 +19,17 @@ No peer dependencies — this package is pure TypeScript with no runtime depende
 
 ## What you get
 
-- **DI tokens** — `token<T>(id)` / `manyToken<T>(id)`, nominal and versioned, plus `bindings()`
+- **DI tokens** — `token<T>({ id }, { version? })` / `manyToken<T>({ id }, { version? })`, nominal and versioned, plus `bindings({})`
   building a typed `Bindings<BoundIds>` set (`.bind`, `.bindMany`) that tracks which ids are bound
   in its own type parameter.
-- **Pack composition** — `definePack({ name, deps, services, tools?, http?, cli?, dispose? })`,
-  the `Pack`/`PackContainer` types, and `createDaemon({ packs, bindings, transports? })`, which
+- **Pack composition** — `definePack({ name, deps, services }, { tools?, http?, cli?, dispose? })`,
+  the `Pack`/`PackContainer` types, and `createDaemon({ packs, bindings }, { transports? })`, which
   composes packs against bound tokens and resolves each pack's `services` against a container
   scoped to only that pack's declared `deps`.
 - **Pack lifecycle helpers** — `registerPackTools` (walks composed packs' `tools()` into a shared
   `ToolRegistry`) and `disposePacks` (best-effort reverse-order teardown; one pack's `dispose`
   failure never blocks another's, recorded as `PackDisposalFailure`).
-- **Tool registry** — `createToolRegistry()` and the `ToolRegistry`/`ToolDescriptor`/`ToolPolicy`/
+- **Tool registry** — `createToolRegistry({})` and the `ToolRegistry`/`ToolDescriptor`/`ToolPolicy`/
   `ToolHandler`/`ToolRegistration`/`ToolAuthorizationContext`/`AuthorizationDecision` types. The
   registry's public surface (`register`/`has`/`list`) exposes descriptors only — handlers and
   policies are never publicly retrievable, so holding a `ToolRegistry` reference lets you enumerate
@@ -47,45 +47,59 @@ No peer dependencies — this package is pure TypeScript with no runtime depende
 import { bindings, definePack, createDaemon, token, createToolRegistry, registerPackTools } from '@jini-ai/core';
 
 interface Logger {
-  log(msg: string): void;
+  log(required: { message: string }): void;
 }
 
-const LoggerToken = token<Logger>('app.logger');
+const LoggerToken = token<Logger>({ id: 'app.logger' });
 
 const loggerPack = definePack({
   name: 'logger',
   deps: [],
-  services: () => ({ logger: { log: (m: string) => console.log(m) } }),
+  services: () => ({ logger: { log: ({ message }: { message: string }) => console.log(message) } }),
 });
 
 const consumerPack = definePack({
   name: 'consumer',
   deps: [LoggerToken],
-  services: (c) => ({ logger: c.get(LoggerToken) }),
+  services: (c) => ({ logger: c.get({ token: LoggerToken }) }),
 });
 
-const bound = bindings().bind(LoggerToken, { log: (m: string) => console.log(m) });
+const bound = bindings({}).bind({ token: LoggerToken, impl: { log: ({ message }: { message: string }) => console.log(message) } });
 
 const daemon = createDaemon({
   packs: [loggerPack, consumerPack] as const,
   bindings: bound,
 });
 
-const registry = createToolRegistry();
-registerPackTools([loggerPack, consumerPack], daemon.services, registry);
+const registry = createToolRegistry({});
+registerPackTools({ registry, packs: [loggerPack, consumerPack], daemon });
 ```
 
+Every callable takes a required object and, when needed, a separate optional object. Factories
+with no required values take `{}`. Registry lookups use `registry.has({ toolId })` and
+`registry.list({})`; registration already takes the required `{ descriptor, handler, policy }`.
+Pack tools/disposal callbacks receive `{ services }`; HTTP and CLI callbacks receive
+`{ app, services }` and `{ reg, services }`. A pack's services factory still receives its scoped
+`PackContainer` port object directly.
+
+Auth and origin helpers require `{ config, env }`, with `env` supplied by the host. For example,
+`apiTokenFromEnv({ config, env: environmentSnapshot })`. `isLocalSameOrigin` additionally requires
+`req` and `port`. Malformed-origin diagnostics go through the optional `{ logger }` port, whose
+`warn({ message })` method the host supplies. No process environment or console logger is read.
+Redaction takes `{ input }` and optional `{ exactSecrets, extraPatterns }`, and `ToolInputError` takes `{ message }` plus optional `{ cause }`.
+Tool handlers receive required execution context first and optional `{ emitSurface }` second.
+
 ## Entry points
 
 | subpath | what's behind it |
 |---|---|
 | `.` | The public surface above: tokens, packs, daemon composition, tool registry (descriptors only), principal, redact, auth primitives. |
-| `./internal` | **Not part of the public contract.** Exposes `authorizeToolInvocation` (resolves a registry's tool and runs its authorization gate — a security-sensitive value export, but one that only ever hands back a handler alongside an `'allow'` decision) plus type-only `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` re-derivation helpers. Its sole intended consumers are `@jini-ai/daemon`'s `ToolExecutor` and `@jini-ai/server`'s `createLocalNodeDaemon`. Node's resolver will happily let any consumer import it — the boundary is enforced by `scripts/check-engine-boundaries.ts`, not by the exports map — so external adopters should treat it as off-limits regardless. |
+| `./composition` | **Not part of the public contract.** Exposes `authorizeToolInvocation` (resolves a registry's tool and runs its authorization gate — a security-sensitive value export, but one that only ever hands back a handler alongside an `'allow'` decision) plus type-only `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` re-derivation helpers. Its sole intended consumers are `@jini-ai/daemon`'s `ToolExecutor` and `@jini-ai/server`'s `createLocalNodeDaemon`. Node's resolver will happily let any consumer import it — the boundary is enforced by `scripts/check-engine-boundaries.ts`, not by the exports map — so external adopters should treat it as off-limits regardless. |
 
 ## What's swappable
 
 Everything a pack declares as a `deps` token is a swap point by construction: bind any
-implementation that satisfies the token's type via `bindings().bind(...)`, and `createDaemon`
+implementation that satisfies the token's type via `bindings({}).bind(...)`, and `createDaemon`
 resolves it into that pack's `PackContainer` with no other change. `ToolPolicy.authorize` is
 likewise a seam you supply per tool registration. The kernel logic itself (composition ordering,
 the missing-binding compile-time gate, the tool registry's append-only enforcement) is fixed and
@@ -98,4 +112,130 @@ ESM only — ships `"type": "module"` with no CommonJS `require` build.
 
 ## Provenance
 
-See [source-map.md](./source-map.md) for per-file provenance and scope decisions. Apache-2.0.
+See the archived provenance ledger for per-file provenance and scope decisions. Apache-2.0.
+
+## Additional entry points
+
+The four entries below also have named exports from the package root. Each is universal
+and has no runtime dependency. Importing the root and a subpath shares the same
+class and factory identities.
+
+| Subpath | API and required ports |
+|---|---|
+| `./gated-mutations` | `plan`, `confirm`, `execute`, `authorizeForHooks`; authorization, clock, ID generation, complete opaque token generation, TTL, token store and mutation hooks. Includes token lifecycle and composite actor-reference helpers. |
+| `./model-facing-tool-errors` | `forbiddenRule`, `reclassifyToolError`, `withModelFacingErrors`, `withModelFacingRegistrationErrors`, `callerSafeErrorMessage`; callers own ordered error allowlists and fallback wording. |
+| `./contribution-registry` | `createContributionRegistry({ keyOf })`; instance-owned replacement by key, with detached array snapshots. |
+| `./naming` | `deriveAvailableName`, `deriveDuplicateName`, `MAX_SUFFIX_ATTEMPTS`; required collision predicate, suffix formatter and exhaustion message policy. |
+
+Contribution registries use `register({ contribution })`, `list({})` and `clear({})`.
+Approval clock/ID ports use the shared zero-argument `Clock.nowMs()` and
+`IdGenerator.newId()` getters. Token generation and `hooks.computePlan` still receive
+an empty required object. `AuthorizeFn` takes `{ principalId, permission, workspaceId }` with optional
+`{ entityType, entityId }` in the second object. The memory token adapter uses
+`new InMemoryTokenStore({})` and `count({})`;
+its persistence methods already accept named objects. Marker errors use
+`new TokenExpiredError({ message }, { cause })` (and the same shape for the other
+approval/actor marker errors). `ForbiddenError` also requires a `reasonCode`.
+Error class identity, existing messages and authorization/redemption ordering are
+preserved. The host supplies transaction/locking policy and hashes the full intent.
+
+```ts
+import { createContributionRegistry } from '@jini-ai/core/contribution-registry';
+import { deriveDuplicateName } from '@jini-ai/core/naming';
+
+const registry = createContributionRegistry({
+  keyOf: ({ contribution }: { contribution: { domain: string } }) => contribution.domain,
+});
+registry.register({ contribution: { domain: 'example' } });
+const snapshot = registry.list({});
+registry.clear({});
+
+const existing = new Set(['Example', 'Example 2']);
+const duplicateName = await deriveDuplicateName({
+  sourceName: 'Example',
+  isTaken: async ({ candidate }) => existing.has(candidate),
+  withSuffix: ({ base, suffix }) => `${base} ${suffix}`,
+  exhaustionMessage: ({ base, maxAttempts }) => `No name available for ${base} after ${maxAttempts} attempts`,
+}, { maxAttempts: 1000 }); // 'Example 3'
+```
+
+Naming's optional `onExhausted({ base, maxAttempts })` port must throw. Approval token
+stores must insert without overwriting issuance and atomically redeem/expire tokens;
+`InMemoryTokenStore` provides that contract for tests and requires host retention policy
+for long-lived use. There is no application layout, environment name or storage default.
+
+The existing kernel APIs have also changed to object arguments. Update token/binding
+calls, pack contributions, handler emitters and explicit environment snapshots before
+using this unreleased version; see [CHANGELOG.md](./CHANGELOG.md) for BREAKING notes.
+
+## Design decisions
+
+- [Confirmation checks have a fixed order and atomic redemption](docs/decisions/DR-001-gated-mutation-check-order.md).
+
+## Shared kernel contracts
+
+Import `Clock`, `IdGenerator`, `UUID`, `ISODateTime`, `JsonPrimitive`, `JsonValue`,
+`JsonObject`, `JsonArray`, `HttpRequest`, `HttpResponse`, `RequestRedirect`, `HttpClientPort`,
+`Logger` and `Result` from `@jini-ai/core/primitives`. They are canonical structural types;
+UUIDs and timestamps remain unbranded strings. The HTTP contract includes binary response
+bytes, redirect provenance, socket idle budgets and an optional total deadline. Platform
+supplies the guarded HTTP implementation; core defines the port only.
+
+Default adapters are `createSystemClock()`, `createRandomUuidGenerator()` and
+`createConsoleLogger({ prefix })`. Clock/ID getters take no arguments. Time helpers are
+`toIsoDateTime({ epochMs })` and `nowIso({ clock })`. The UUID adapter requires a host
+cryptographic UUID implementation and fails if unavailable. The console adapter routes
+info/warn/error with optional `{ meta, error }` to the same console severity.
+
+Agent-tool catalogs import `AgentToolSideEffect`, `AgentToolActorClassRule` and
+`AgentToolDefinition` from the core root. Delete is a separate side-effect classification;
+domains may tighten the shared interface, including making `inputSchema` required.
+
+`@jini-ai/core/text` exports `sanitizeUntrustedText({ text }, { maxLength? })` and
+`SanitizeTextOptions`. This terminal-boundary policy strips C0/C1 and ANSI control
+sequences, masks labeled/opaque credentials and caps the complete output at 500 characters
+by default. Correlation IDs and the delegated-tool route remain visible. This sanitizer
+keeps its existing policy; the telemetry redactor additionally masks PII.
+
+`redactSecrets` and `redactSecretsWithCounts` cover the core, CLI and provider rule union.
+Exact secrets are literal strings (including regex metacharacters), applied longest first;
+null/undefined/empty entries are ignored. Extra patterns are `{ name, regex }` entries, cloned
+and made global so caller `lastIndex` state is unchanged. `SECRET_SHAPE_PATTERNS` exports
+the eleven unchanged diagnostics vendor regexes; diagnostics retains its secret-only policy.
+Core's full redactor is conservative and can mask long ordinary identifiers as opaque tokens.
+
+`timingSafeTokenMatch({ presented, expected, timingSafeEqual })` encodes UTF-8, rejects unequal
+byte lengths, and calls the required native byte comparator with `{ left, right }`.
+Node hosts inject `({ left, right }) => crypto.timingSafeEqual(left, right)`; this keeps the
+universal root free of Node imports while preserving native timing guarantees. No JavaScript
+equality fallback is provided. The root does not expose `authorizeToolInvocation`; that gate
+and the pack binding derivation types live at `@jini-ai/core/composition`.
+
+Origin classifiers implement the dev-browser LAN allow-list. They allow private addresses
+for local development; use `@jini-ai/platform/net` for SSRF classification. Origin validation
+uses only an injected environment snapshot and optional `Pick<Logger, 'warn'>` diagnostics.
+
+## Agent tool registration
+
+The root exports `AgentToolDefinition`, `AgentToolSideEffect`, `AgentToolActorClassRule` and
+the shared registration kit: catalog indexing, named input readers, schema-bearing refusals,
+independent risk gates, registration assembly, risk-map merging and human-confirmed handlers.
+This wiring is domain-independent. A domain may require `inputSchema` through an intersection
+with `AgentToolDefinition`; it must still independently classify the effects its handlers perform.
+
+Use `indexCatalogById({ catalog })`, `requireInputRecord({ input })`,
+`requireString({ input, key })`, `optionalString({ input, key })`, and
+`withSchemaOnRejection({ toolId, catalog, isShapeRejection: ({ error }) => predicate(error), fn })`.
+`buildDomainRegistrations(required, { unwiredToolIds })` refuses metadata/schema drift and
+unclassified or accidentally unwired tools. Domain-specific authorization decisions and denial
+classes remain in the domain or host; registration policy is pass-through after those gates.
+
+## Pure path containment
+
+`@jini-ai/core/primitives` exports `pathContains({ root, target }, { caseSensitive?, separator? })`.
+Both paths must already be absolute; the host resolves cwd-relative paths and
+symlinks. The helper performs lexical segment normalization without importing
+Node or reading a working directory. Equality counts as contained. Directory
+prefix siblings and traversal escapes are rejected; a legal `..name` segment is
+allowed. Windows hosts pass `{ caseSensitive: false, separator: "\\\\" }`; POSIX hosts
+retain the default slash separator so backslashes in directory names remain literal.

package/dist/agent-tools.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared vocabulary for independently classified agent-tool catalogs.
+ *
+ * `deletes-durable-state` is a distinct member rather than a flavor of `mutates-durable-state`, and
+ * the distinction is load-bearing rather than cosmetic. Wiring gates compare the two
+ * classifications for EQUALITY, so the strength of the check is exactly the resolution of the
+ * vocabulary: folding a delete into `mutates-durable-state` would let a tool that removes content
+ * from every read path carry the same declared risk as one that edits a title, and
+ * the wiring gate would have nothing to object to. A separate member means a delete tool
+ * whose declaration drifts toward the milder classification fails the build.
+ *
+ * Narrower domain-owned unions remain assignable to this shared vocabulary. Domains may tighten
+ * their own catalogs without loosening the classification required by the wiring gate.
+ */
+export type AgentToolSideEffect = "none" | "mutates-durable-state" | "deletes-durable-state" | "mints-token";
+export type AgentToolActorClassRule = "confirmer-must-equal-own-delegatedBy" | "user-only" | "none";
+/** Structural catalog contract. Domains may require inputSchema or tighten their own metadata. */
+export interface AgentToolDefinition {
+    name: string;
+    description: string;
+    sideEffects: AgentToolSideEffect;
+    authorization: {
+        permission: string;
+        orPermission?: string;
+    };
+    actorClassRule?: AgentToolActorClassRule;
+    inputSchema?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=agent-tools.d.ts.map

package/dist/agent-tools.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-tools.js.map

package/dist/api-token-auth.d.ts

@@ -4,7 +4,7 @@
  * Whether a bearer-style API token gate should be enforced, and what the
  * expected token value is. Generalized from an upstream flat daemon module:
  * the origin hardcoded its host product's env-var names, now fields on
- * {@link ApiTokenAuthEnvConfig} — see `source-map.md` for the exact mapping.
+ * {@link ApiTokenAuthEnvConfig} — see `archived provenance ledger` for the exact mapping.
  */
 /** Names the env vars this port reads. */
 export interface ApiTokenAuthEnvConfig {
@@ -18,11 +18,18 @@ export interface ApiTokenAuthEnvConfig {
  * (case-insensitive, trimmed). Anything else, including `undefined`, is
  * falsy.
  */
-export declare function isTruthyEnvFlag(value: unknown): boolean;
+export declare function isTruthyEnvFlag({ value }: {
+    value: unknown;
+}): boolean;
+/** Explicit environment snapshot; no process-global reads. */
+export interface ApiTokenAuthArgs {
+    config: ApiTokenAuthEnvConfig;
+    env: Readonly<Record<string, string | undefined>>;
+}
 /** Whether the API auth gate has been explicitly force-disabled. */
-export declare function isApiAuthDisabled(config: ApiTokenAuthEnvConfig, env?: NodeJS.ProcessEnv): boolean;
+export declare function isApiAuthDisabled({ config, env }: ApiTokenAuthArgs): boolean;
 /** The configured expected token value, trimmed; `''` when unset. */
-export declare function apiTokenFromEnv(config: ApiTokenAuthEnvConfig, env?: NodeJS.ProcessEnv): string;
+export declare function apiTokenFromEnv({ config, env }: ApiTokenAuthArgs): string;
 /** Whether the token gate should actually run: a token is configured and it hasn't been disabled. */
-export declare function isApiTokenMiddlewareEnabled(config: ApiTokenAuthEnvConfig, env?: NodeJS.ProcessEnv): boolean;
+export declare function isApiTokenMiddlewareEnabled({ config, env }: ApiTokenAuthArgs): boolean;
 //# sourceMappingURL=api-token-auth.d.ts.map