@jini-ai/core 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,131 @@
+# @jini-ai/core
+
+## 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/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

package/dist/api-token-auth.js

@@ -4,27 +4,27 @@
  * 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.
  */
 /**
  * Interprets `value` as a truthy flag: `'1'`, `'true'`, `'yes'`, or `'on'`
  * (case-insensitive, trimmed). Anything else, including `undefined`, is
  * falsy.
  */
-export function isTruthyEnvFlag(value) {
+export function isTruthyEnvFlag({ value }) {
     const normalized = String(value || '').trim().toLowerCase();
     return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
 }
 /** Whether the API auth gate has been explicitly force-disabled. */
-export function isApiAuthDisabled(config, env = process.env) {
-    return isTruthyEnvFlag(env[config.disableEnvVar]);
+export function isApiAuthDisabled({ config, env }) {
+    return isTruthyEnvFlag({ value: env[config.disableEnvVar] });
 }
 /** The configured expected token value, trimmed; `''` when unset. */
-export function apiTokenFromEnv(config, env = process.env) {
+export function apiTokenFromEnv({ config, env }) {
     return (env[config.tokenEnvVar] ?? '').trim();
 }
 /** Whether the token gate should actually run: a token is configured and it hasn't been disabled. */
-export function isApiTokenMiddlewareEnabled(config, env = process.env) {
-    return apiTokenFromEnv(config, env).length > 0 && !isApiAuthDisabled(config, env);
+export function isApiTokenMiddlewareEnabled({ config, env }) {
+    return apiTokenFromEnv({ config, env }).length > 0 && !isApiAuthDisabled({ config, env });
 }
 //# sourceMappingURL=api-token-auth.js.map

package/dist/bindings.d.ts

@@ -5,14 +5,25 @@ import type { ManyToken, Token } from './token.js';
  * `Exclude<RequiredTokenIds<Packs>, BoundIds>` at compile time (see daemon.ts).
  */
 export declare class Bindings<BoundIds extends string = never> {
+    constructor(_required: Record<string, never>);
     private readonly one;
     private readonly many;
-    bind<T, Id extends string>(t: Token<T, Id>, impl: T): Bindings<BoundIds | Id>;
-    bindMany<T, Id extends string>(t: ManyToken<T, Id>, impl: T): Bindings<BoundIds | Id>;
+    bind<T, Id extends string>({ token: t, impl }: {
+        token: Token<T, Id>;
+        impl: T;
+    }): Bindings<BoundIds | Id>;
+    bindMany<T, Id extends string>({ token: t, impl }: {
+        token: ManyToken<T, Id>;
+        impl: T;
+    }): Bindings<BoundIds | Id>;
     /** @internal */
-    resolveOne<T>(t: Token<T, string>): T;
+    resolveOne<T>({ token: t }: {
+        token: Token<T, string>;
+    }): T;
     /** @internal */
-    resolveMany<T>(t: ManyToken<T, string>): T[];
+    resolveMany<T>({ token: t }: {
+        token: ManyToken<T, string>;
+    }): T[];
 }
-export declare function bindings(): Bindings<never>;
+export declare function bindings(required: Record<string, never>): Bindings<never>;
 //# sourceMappingURL=bindings.d.ts.map

package/dist/bindings.js

@@ -4,23 +4,24 @@
  * `Exclude<RequiredTokenIds<Packs>, BoundIds>` at compile time (see daemon.ts).
  */
 export class Bindings {
+    constructor(_required) { }
     one = new Map();
     many = new Map();
-    bind(t, impl) {
+    bind({ token: t, impl }) {
         if (this.one.has(t.id)) {
             throw new Error(`duplicate binding: ${t.id} is already bound (a singleton token accepts exactly one binding)`);
         }
         this.one.set(t.id, { value: impl, version: t.version });
         return this;
     }
-    bindMany(t, impl) {
+    bindMany({ token: t, impl }) {
         const list = this.many.get(t.id) ?? [];
         list.push(impl);
         this.many.set(t.id, list);
         return this;
     }
     /** @internal */
-    resolveOne(t) {
+    resolveOne({ token: t }) {
         const entry = this.one.get(t.id);
         if (!entry) {
             throw new Error(`missing binding: ${t.id}`);
@@ -31,11 +32,11 @@ export class Bindings {
         return entry.value;
     }
     /** @internal */
-    resolveMany(t) {
+    resolveMany({ token: t }) {
         return (this.many.get(t.id) ?? []);
     }
 }
-export function bindings() {
-    return new Bindings();
+export function bindings(required) {
+    return new Bindings(required);
 }
 //# sourceMappingURL=bindings.js.map

package/dist/composition.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module @jini-ai/core/composition
+ *
+ * Composition boundary for daemon assembly and authorized tool invocation.
+ * These capabilities stay off the root entry point; each has its own
+ * intended consumer:
+ *
+ * - {@link authorizeToolInvocation} so `@jini-ai/daemon`'s `ToolExecutor` can
+ *   resolve a registered tool and run its authorization gate — the tool's
+ *   own `ToolPolicy`, then an optional transport-level veto — before ever
+ *   receiving the handler. This is the security-sensitive one: it is a
+ *   runtime *value* export, but unlike the `getToolRegistration` it
+ *   replaced (2026-07-29 hardening pass), it only ever returns a handler
+ *   closure alongside a `decision: 'allow'` — a denied or unauthorized call
+ *   gets no handler at all, so the authorization gate cannot be bypassed by
+ *   calling this export directly instead of going through `ToolExecutor`.
+ * - `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` so `@jini-ai/server`'s
+ *   `createLocalNodeDaemon` can re-derive `createDaemon`'s exact
+ *   compile-time "missing binding" gate on its own wrapper config type,
+ *   instead of either duplicating the type-level logic or losing the
+ *   compile-time check through the wrapper. These are `import type`-only —
+ *   erased at build time, carry no runtime capability, and are not a
+ *   security boundary the way {@link authorizeToolInvocation} is.
+ *
+ * **Correction (2026-07-19 hardening pass):** a package.json `exports` map
+ * subpath is NOT a language-level or per-consumer access modifier — Node's
+ * module resolution will happily resolve `@jini-ai/core/composition` for *any*
+ * package that depends on `@jini-ai/core`, not just the intended consumer.
+ * Earlier revisions of this doc comment claimed this boundary was
+ * "enforced" by the exports map; that was inaccurate and left the leak
+ * undetected. The actual enforcement is `scripts/check-engine-boundaries.ts`'s
+ * R6-internal-leak rule forbidding any *value* import from `@jini-ai/core/composition` outside
+ * `packages/daemon/**` (type-only imports of the DI-token-derivation types
+ * remain unrestricted, since they carry no runtime capability). R6 checks this
+ * exact composition specifier as a second, independent layer on top of the 2026-07-29
+ * structural fix above, not a substitute for it.
+ */
+export { authorizeToolInvocation } from './tool-registry.js';
+export type { ToolAuthorizationDelegate, ToolInvocationAuthorization } from './tool-registry.js';
+export type { AnyPack, MissingTokenIds, RequiredTokenIds } from './daemon.js';
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.js

@@ -0,0 +1,39 @@
+/**
+ * @module @jini-ai/core/composition
+ *
+ * Composition boundary for daemon assembly and authorized tool invocation.
+ * These capabilities stay off the root entry point; each has its own
+ * intended consumer:
+ *
+ * - {@link authorizeToolInvocation} so `@jini-ai/daemon`'s `ToolExecutor` can
+ *   resolve a registered tool and run its authorization gate — the tool's
+ *   own `ToolPolicy`, then an optional transport-level veto — before ever
+ *   receiving the handler. This is the security-sensitive one: it is a
+ *   runtime *value* export, but unlike the `getToolRegistration` it
+ *   replaced (2026-07-29 hardening pass), it only ever returns a handler
+ *   closure alongside a `decision: 'allow'` — a denied or unauthorized call
+ *   gets no handler at all, so the authorization gate cannot be bypassed by
+ *   calling this export directly instead of going through `ToolExecutor`.
+ * - `AnyPack`/`RequiredTokenIds`/`MissingTokenIds` so `@jini-ai/server`'s
+ *   `createLocalNodeDaemon` can re-derive `createDaemon`'s exact
+ *   compile-time "missing binding" gate on its own wrapper config type,
+ *   instead of either duplicating the type-level logic or losing the
+ *   compile-time check through the wrapper. These are `import type`-only —
+ *   erased at build time, carry no runtime capability, and are not a
+ *   security boundary the way {@link authorizeToolInvocation} is.
+ *
+ * **Correction (2026-07-19 hardening pass):** a package.json `exports` map
+ * subpath is NOT a language-level or per-consumer access modifier — Node's
+ * module resolution will happily resolve `@jini-ai/core/composition` for *any*
+ * package that depends on `@jini-ai/core`, not just the intended consumer.
+ * Earlier revisions of this doc comment claimed this boundary was
+ * "enforced" by the exports map; that was inaccurate and left the leak
+ * undetected. The actual enforcement is `scripts/check-engine-boundaries.ts`'s
+ * R6-internal-leak rule forbidding any *value* import from `@jini-ai/core/composition` outside
+ * `packages/daemon/**` (type-only imports of the DI-token-derivation types
+ * remain unrestricted, since they carry no runtime capability). R6 checks this
+ * exact composition specifier as a second, independent layer on top of the 2026-07-29
+ * structural fix above, not a substitute for it.
+ */
+export { authorizeToolInvocation } from './tool-registry.js';
+//# sourceMappingURL=composition.js.map

package/dist/contribution-registry.d.ts

@@ -0,0 +1,16 @@
+/** Replace-by-key registry for host-owned contributions; no singleton or execution surface. */
+export interface ContributionRegistry<TContribution> {
+    register(required: {
+        contribution: TContribution;
+    }): void;
+    /** Detached array snapshot; contribution values retain their identity. */
+    list(_required: Record<string, never>): readonly TContribution[];
+    clear(_required: Record<string, never>): void;
+}
+/** O(1) register/clear, O(n) list and O(n) retained entries. Replacement preserves position. */
+export declare function createContributionRegistry<TContribution, TKey>(required: {
+    keyOf: (required: {
+        contribution: TContribution;
+    }) => TKey;
+}): ContributionRegistry<TContribution>;
+//# sourceMappingURL=contribution-registry.d.ts.map

package/dist/contribution-registry.js

@@ -0,0 +1,12 @@
+/** O(1) register/clear, O(n) list and O(n) retained entries. Replacement preserves position. */
+export function createContributionRegistry(required) {
+    const contributions = new Map();
+    return {
+        register({ contribution }) {
+            contributions.set(required.keyOf({ contribution }), contribution);
+        },
+        list(_required) { return [...contributions.values()]; },
+        clear(_required) { contributions.clear(); },
+    };
+}
+//# sourceMappingURL=contribution-registry.js.map