@jini-ai/core 0.3.1 → 0.4.0

package/dist/origin-validation.js

@@ -9,12 +9,14 @@
  *
  * Generalized from an upstream flat daemon module: the origin hardcoded its
  * host product's env-var names, now fields on
- * {@link OriginValidationEnvConfig} — see `source-map.md` for the exact
+ * {@link OriginValidationEnvConfig} — see `archived provenance ledger` for the exact
  * mapping. One function, a bypass for a specific product's own
  * browser-extension-driven ingest route, was deliberately **not** ported —
  * it names a specific product route and product feature with no generic
- * equivalent; see `source-map.md`.
+ * equivalent; see `archived provenance ledger`.
  */
+/** Splits and trims the configured allow-list into entries. Both lenient request parsing and
+ * strict boot validation share this splitter so their definition of one entry cannot drift. */
 function splitAllowedOriginsEnv(config, env) {
     const raw = env[config.allowedOriginsEnvVar] || '';
     if (!raw.trim())
@@ -24,6 +26,7 @@ function splitAllowedOriginsEnv(config, env) {
         .map((origin) => origin.trim())
         .filter(Boolean);
 }
+/** Normalizes one entry to a protocol://host origin; invalid or non-HTTP(S) entries are rejected. */
 function parseAllowedOrigin(entry) {
     let parsed;
     try {
@@ -41,18 +44,21 @@ function parseAllowedOrigin(entry) {
  *
  * Deliberately never throws — this is on the hot path of {@link isLocalSameOrigin}, called fresh
  * on every same-origin decision a host makes. A malformed entry is dropped and logged instead of
- * aborting the whole parse (see the twin `@jini-ai/http-kit` copy of this module for the fuller
- * incident history this mirrors: a request-time throw here used to turn one config typo into
+ * aborting the whole parse. A request-time throw used to turn one config typo into
  * either a 500 on every request, or — on a route with no enclosing catch — an unhandled
- * rejection). Call {@link assertValidAllowedOrigins} once at host startup instead, to fail loudly
+ * rejection: hand-mounted attachment routes and provider catch-all routes had no common
+ * enclosing catch. Dropping the malformed entry degrades to one fewer trusted origin,
+ * never every request breaking. Call {@link assertValidAllowedOrigins} once at host startup instead, to fail loudly
  * before any request-serving traffic exists.
  */
-export function configuredAllowedOrigins(config, env = process.env) {
+export function configuredAllowedOrigins({ config, env }, { logger } = {}) {
     const origins = [];
     for (const entry of splitAllowedOriginsEnv(config, env)) {
         const origin = parseAllowedOrigin(entry);
         if (origin === undefined) {
-            console.warn(`[@jini-ai/core] ignoring malformed ${config.allowedOriginsEnvVar} entry (must be an http:// or https:// origin): ${entry}`);
+            logger?.warn({
+                message: `[@jini-ai/core] ignoring malformed ${config.allowedOriginsEnvVar} entry (must be an http:// or https:// origin): ${entry}`,
+            });
             continue;
         }
         origins.push(origin);
@@ -62,9 +68,10 @@ export function configuredAllowedOrigins(config, env = process.env) {
 /**
  * Boot-time companion to {@link configuredAllowedOrigins}: throws, naming every malformed entry,
  * instead of silently dropping them. Call once, early in host startup, before the HTTP server
- * accepts connections.
+ * accepts connections. A misconfiguration must fail boot loudly rather than quietly serving with
+ * a smaller-than-intended allow-list, or throwing on whichever request first reaches the guard.
  */
-export function assertValidAllowedOrigins(config, env = process.env) {
+export function assertValidAllowedOrigins({ config, env }) {
     const invalid = splitAllowedOriginsEnv(config, env).filter((entry) => parseAllowedOrigin(entry) === undefined);
     if (invalid.length === 0)
         return;
@@ -72,11 +79,11 @@ export function assertValidAllowedOrigins(config, env = process.env) {
         `(must be http:// or https:// origins): ${invalid.join(', ')}`);
 }
 /** The `host` (hostname:port) component of each configured allowed origin. */
-export function configuredAllowedHosts(origins) {
+export function configuredAllowedHosts({ origins }) {
     return origins.map((origin) => new URL(origin).host);
 }
 /** The set of browser-facing ports considered "local": the daemon's own port plus an optional configured web port. */
-export function allowedBrowserPorts(config, port, env = process.env) {
+export function allowedBrowserPorts({ config, port, env }) {
     const ports = [];
     const primary = Number(port);
     if (primary)
@@ -94,7 +101,7 @@ function headerValue(value) {
     return value == null ? undefined : String(value);
 }
 /** Parses a raw `Host` header value into hostname/host/port, or `null` when unparseable. */
-export function parseHostHeader(value) {
+export function parseHostHeader({ value }) {
     const raw = String(headerValue(value) || '').trim();
     if (!raw)
         return null;
@@ -106,8 +113,10 @@ export function parseHostHeader(value) {
         return null;
     }
 }
-/** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16). */
-export function isPrivateIpv4(hostname) {
+/** Whether `hostname` is an RFC 1918 private IPv4 address (10/8, 172.16/12, 192.168/16) or link-local (169.254/16).
+ * Implements the dev-browser LAN allow-list, not SSRF blocking. Use @jini-ai/platform/net
+ * for SSRF address classification; private addresses are allowed here for local development. */
+export function isPrivateIpv4({ hostname }) {
     const parts = String(hostname || '').split('.');
     if (parts.length !== 4)
         return false;
@@ -120,7 +129,7 @@ export function isPrivateIpv4(hostname) {
     return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254);
 }
 /** Whether `hostname` is a literal IPv4 address or bracketed IPv6 literal (as opposed to a DNS name). */
-export function isIpLiteralHostname(hostname) {
+export function isIpLiteralHostname({ hostname }) {
     const host = String(hostname || '').trim();
     if (!host)
         return false;
@@ -133,8 +142,9 @@ export function isIpLiteralHostname(hostname) {
         return false;
     return parts.map(Number).every((n) => Number.isInteger(n) && n >= 0 && n <= 255);
 }
-/** Whether `hostname` is loopback, unspecified, or a private-LAN address. */
-export function isLoopbackOrPrivateLanHost(hostname) {
+/** Whether `hostname` is loopback, unspecified, or a private-LAN address.
+ * Implements the dev-browser LAN allow-list, not SSRF blocking (@jini-ai/platform/net). */
+export function isLoopbackOrPrivateLanHost({ hostname }) {
     const host = String(hostname || '').toLowerCase();
     return (host === 'localhost' ||
         host === '127.0.0.1' ||
@@ -142,26 +152,26 @@ export function isLoopbackOrPrivateLanHost(hostname) {
         host === '[::1]' ||
         host === '0.0.0.0' ||
         host === '::' ||
-        isPrivateIpv4(host));
+        isPrivateIpv4({ hostname: host }));
 }
 /** Whether a request's `Host` header names a locally-served or explicitly allow-listed host. */
-export function isAllowedBrowserHost(config, hostHeader, ports, bindHost, extraAllowedOrigins) {
-    const requestHost = parseHostHeader(hostHeader);
+export function isAllowedBrowserHost({ hostHeader, ports, bindHost, extraAllowedOrigins }) {
+    const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
     const loopbackHosts = ['127.0.0.1', 'localhost', '[::1]'];
     const explicitHosts = new Set([
         ...ports.flatMap((p) => [...loopbackHosts.map((h) => `${h}:${p}`), `${bindHost}:${p}`]),
-        ...configuredAllowedHosts(extraAllowedOrigins),
+        ...configuredAllowedHosts({ origins: extraAllowedOrigins }),
     ]);
     if (explicitHosts.has(requestHost.host))
         return true;
     if (!ports.map(String).includes(requestHost.port))
         return false;
-    return isLoopbackOrPrivateLanHost(requestHost.hostname);
+    return isLoopbackOrPrivateLanHost({ hostname: requestHost.hostname });
 }
 /** Whether an `Origin` header value names a locally-served or explicitly allow-listed origin. */
-export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHost, extraAllowedOrigins) {
+export function isAllowedBrowserOrigin({ origin, hostHeader, ports, bindHost, extraAllowedOrigins }) {
     if (extraAllowedOrigins.includes(String(origin)))
         return true;
     let parsedOrigin;
@@ -173,7 +183,7 @@ export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHo
     }
     if (parsedOrigin.protocol !== 'http:' && parsedOrigin.protocol !== 'https:')
         return false;
-    const requestHost = parseHostHeader(hostHeader);
+    const requestHost = parseHostHeader({ value: hostHeader });
     if (!requestHost)
         return false;
     const schemes = ['http', 'https'];
@@ -189,21 +199,21 @@ export function isAllowedBrowserOrigin(config, origin, hostHeader, ports, bindHo
         return false;
     if (parsedOrigin.hostname !== requestHost.hostname)
         return false;
-    return isLoopbackOrPrivateLanHost(parsedOrigin.hostname);
+    return isLoopbackOrPrivateLanHost({ hostname: parsedOrigin.hostname });
 }
 /**
  * The top-level same-origin gate: is `req` a request the daemon should treat
  * as coming from one of its own locally-served (or explicitly allow-listed)
  * pages.
  */
-export function isLocalSameOrigin(config, req, port, env = process.env) {
+export function isLocalSameOrigin({ config, req, port, env }, { logger } = {}) {
     const host = String(headerValue(req.headers?.host) || '');
     const origin = headerValue(req.headers?.origin);
-    const ports = allowedBrowserPorts(config, port, env);
+    const ports = allowedBrowserPorts({ config, port, env });
     const bindHost = env[config.bindHostEnvVar] || '127.0.0.1';
-    const extraAllowedOrigins = configuredAllowedOrigins(config, env);
-    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname(new URL(o).hostname));
-    const localHostAllowed = isAllowedBrowserHost(config, host, ports, bindHost, ipOnlyExtraOrigins);
+    const extraAllowedOrigins = configuredAllowedOrigins({ config, env }, { logger });
+    const ipOnlyExtraOrigins = extraAllowedOrigins.filter((o) => isIpLiteralHostname({ hostname: new URL(o).hostname }));
+    const localHostAllowed = isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins: ipOnlyExtraOrigins });
     if (origin == null || origin === '') {
         if (localHostAllowed)
             return true;
@@ -217,7 +227,7 @@ export function isLocalSameOrigin(config, req, port, env = process.env) {
         // consult the broader allow-list once that signal is present.
         const fetchSite = headerValue(req.headers?.['sec-fetch-site']);
         if (fetchSite === 'same-origin') {
-            return isAllowedBrowserHost(config, host, ports, bindHost, extraAllowedOrigins);
+            return isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins });
         }
         return false;
     }
@@ -230,8 +240,8 @@ export function isLocalSameOrigin(config, req, port, env = process.env) {
     // allow-listed entry is the documented escape hatch for these deployments.
     if (extraAllowedOrigins.includes(origin))
         return true;
-    if (!isAllowedBrowserHost(config, host, ports, bindHost, extraAllowedOrigins))
+    if (!isAllowedBrowserHost({ config, hostHeader: host, ports, bindHost, extraAllowedOrigins }))
         return false;
-    return isAllowedBrowserOrigin(config, origin, host, ports, bindHost, extraAllowedOrigins);
+    return isAllowedBrowserOrigin({ config, origin, hostHeader: host, ports, bindHost, extraAllowedOrigins });
 }
 //# sourceMappingURL=origin-validation.js.map

package/dist/pack-lifecycle.d.ts

@@ -15,17 +15,17 @@ import type { Pack } from './pack.js';
 import type { ToolRegistration, ToolRegistry } from './tool-registry.js';
 type AnyPack = Pack<any, any, string>;
 /**
- * Registers `pack.tools(services)` for every pack in `packs` that declares one, in pack order,
+ * Registers `pack.tools({ services })` for every pack in `packs` that declares one, in pack order,
  * into the single shared `registry`.
  *
  * Order matters and is deliberately the caller's to choose: `ToolRegistry.register` throws on a
- * duplicate descriptor id, so whichever pack registers second is the one named in the error. A
- * composition root that wants a host's own tools to win that message registers the host's packs
- * last.
+ * duplicate descriptor id, so whichever pack registers second triggers the error. The registry
+ * message names only the tool ID, not either pack. A composition root that wants a host's own
+ * contribution to trigger the duplicate failure registers the host's packs last.
  *
- * @param registry - The shared registry every composed pack contributes into.
- * @param packs - The composed packs, in composition order.
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.registry - The shared registry every composed pack contributes into.
+ * @param required.packs - The composed packs, in composition order.
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns Every registration that was added, in the order it was added — so a caller can seed a
  * catalog, log an inventory, or assert on the composition without re-deriving it.
  * @throws Whatever `ToolRegistry.register` throws (notably a duplicate descriptor id), at the
@@ -33,14 +33,18 @@ type AnyPack = Pack<any, any, string>;
  * registered tool set is not a state anything downstream can reason about.
  * @complexity O(t) in total contributed tools.
  */
-export declare function registerPackTools<const Packs extends readonly AnyPack[]>(registry: ToolRegistry, packs: Packs, daemon: Daemon<Packs>): readonly ToolRegistration[];
+export declare function registerPackTools<const Packs extends readonly AnyPack[]>({ registry, packs, daemon }: {
+    registry: ToolRegistry;
+    packs: Packs;
+    daemon: Daemon<Packs>;
+}): readonly ToolRegistration[];
 /** One pack's teardown failure, kept with the pack's name so a caller can report which one failed. */
 export interface PackDisposalFailure {
     readonly pack: string;
     readonly error: unknown;
 }
 /**
- * Runs `pack.dispose(services)` for every pack that declares one, in **reverse** composition order
+ * Runs `pack.dispose({ services })` for every pack that declares one, in **reverse** composition order
  * (a pack composed later may depend on an earlier pack's resources, so it must release first).
  *
  * Best-effort by design: one pack throwing must never prevent the rest from disposing, or a single
@@ -48,11 +52,14 @@ export interface PackDisposalFailure {
  * and returned rather than thrown, leaving the composition root free to decide whether a teardown
  * failure is worth surfacing to its own caller.
  *
- * @param packs - The composed packs, in composition order (this function reverses them itself).
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.packs - The composed packs, in composition order (this function reverses them itself).
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns The failures, in the order they occurred. Empty when every pack disposed cleanly.
  * @complexity O(p) in pack count, plus each pack's own teardown cost.
  */
-export declare function disposePacks<const Packs extends readonly AnyPack[]>(packs: Packs, daemon: Daemon<Packs>): Promise<readonly PackDisposalFailure[]>;
+export declare function disposePacks<const Packs extends readonly AnyPack[]>({ packs, daemon }: {
+    packs: Packs;
+    daemon: Daemon<Packs>;
+}): Promise<readonly PackDisposalFailure[]>;
 export {};
 //# sourceMappingURL=pack-lifecycle.d.ts.map

package/dist/pack-lifecycle.js

@@ -1,15 +1,15 @@
 /**
- * Registers `pack.tools(services)` for every pack in `packs` that declares one, in pack order,
+ * Registers `pack.tools({ services })` for every pack in `packs` that declares one, in pack order,
  * into the single shared `registry`.
  *
  * Order matters and is deliberately the caller's to choose: `ToolRegistry.register` throws on a
- * duplicate descriptor id, so whichever pack registers second is the one named in the error. A
- * composition root that wants a host's own tools to win that message registers the host's packs
- * last.
+ * duplicate descriptor id, so whichever pack registers second triggers the error. The registry
+ * message names only the tool ID, not either pack. A composition root that wants a host's own
+ * contribution to trigger the duplicate failure registers the host's packs last.
  *
- * @param registry - The shared registry every composed pack contributes into.
- * @param packs - The composed packs, in composition order.
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.registry - The shared registry every composed pack contributes into.
+ * @param required.packs - The composed packs, in composition order.
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns Every registration that was added, in the order it was added — so a caller can seed a
  * catalog, log an inventory, or assert on the composition without re-deriving it.
  * @throws Whatever `ToolRegistry.register` throws (notably a duplicate descriptor id), at the
@@ -17,11 +17,11 @@
  * registered tool set is not a state anything downstream can reason about.
  * @complexity O(t) in total contributed tools.
  */
-export function registerPackTools(registry, packs, daemon) {
+export function registerPackTools({ registry, packs, daemon }) {
     const services = daemon.services;
     const registered = [];
     for (const pack of packs) {
-        for (const registration of pack.tools?.(services[pack.name]) ?? []) {
+        for (const registration of pack.tools?.({ services: services[pack.name] }) ?? []) {
             registry.register(registration);
             registered.push(registration);
         }
@@ -29,7 +29,7 @@ export function registerPackTools(registry, packs, daemon) {
     return registered;
 }
 /**
- * Runs `pack.dispose(services)` for every pack that declares one, in **reverse** composition order
+ * Runs `pack.dispose({ services })` for every pack that declares one, in **reverse** composition order
  * (a pack composed later may depend on an earlier pack's resources, so it must release first).
  *
  * Best-effort by design: one pack throwing must never prevent the rest from disposing, or a single
@@ -37,12 +37,12 @@ export function registerPackTools(registry, packs, daemon) {
  * and returned rather than thrown, leaving the composition root free to decide whether a teardown
  * failure is worth surfacing to its own caller.
  *
- * @param packs - The composed packs, in composition order (this function reverses them itself).
- * @param daemon - The `createDaemon` result holding each pack's already-built services.
+ * @param required.packs - The composed packs, in composition order (this function reverses them itself).
+ * @param required.daemon - The `createDaemon` result holding each pack's already-built services.
  * @returns The failures, in the order they occurred. Empty when every pack disposed cleanly.
  * @complexity O(p) in pack count, plus each pack's own teardown cost.
  */
-export async function disposePacks(packs, daemon) {
+export async function disposePacks({ packs, daemon }) {
     const services = daemon.services;
     const failures = [];
     for (let index = packs.length - 1; index >= 0; index -= 1) {
@@ -50,7 +50,7 @@ export async function disposePacks(packs, daemon) {
         if (!pack.dispose)
             continue;
         try {
-            await pack.dispose(services[pack.name]);
+            await pack.dispose({ services: services[pack.name] });
         }
         catch (error) {
             failures.push({ pack: pack.name, error });

package/dist/pack.d.ts

@@ -26,8 +26,12 @@ import type { AnyToken, ManyToken, Token } from './token.js';
  * silently falling through to a global container.
  */
 export interface PackContainer {
-    get<T>(t: Token<T, string>): T;
-    getMany<T>(t: ManyToken<T, string>): T[];
+    get<T>(required: {
+        token: Token<T, string>;
+    }): T;
+    getMany<T>(required: {
+        token: ManyToken<T, string>;
+    }): T[];
 }
 export interface Pack<Deps extends readonly AnyToken<unknown, string>[] = readonly AnyToken<unknown, string>[], Services = unknown, Name extends string = string> {
     readonly name: Name;
@@ -35,30 +39,54 @@ export interface Pack<Deps extends readonly AnyToken<unknown, string>[] = readon
     readonly services: (c: PackContainer) => Services;
     /**
      * `{descriptor, handler, policy}` triples this pack contributes to the composition's shared
-     * `ToolRegistry`. Called exactly once per composed pack, before any transport is mounted, so a
-     * pack's routes can assume its own tools are already registered.
+     * `ToolRegistry`. Composition roots must call `registerPackTools` exactly once per composed pack,
+     * before mounting any transport, so a pack's routes can assume its tools are already registered.
+     * This interface and `createDaemon` do not enforce that orchestration; repeated registration
+     * invokes the contribution again and duplicate tool IDs are rejected by the registry.
      *
      * Atomic with `http`/`cli` by construction: a pack that is not composed contributes neither its
      * tools nor its routes. See this module's own doc for the failure mode that makes this
      * load-bearing rather than a convenience.
      */
-    readonly tools?: (services: Services) => readonly ToolRegistration[];
-    readonly http?: (app: unknown, services: Services) => void;
-    readonly cli?: (reg: unknown, services: Services) => void;
+    readonly tools?: (required: {
+        services: Services;
+    }) => readonly ToolRegistration[];
+    readonly http?: (required: {
+        app: unknown;
+        services: Services;
+    }) => void;
+    readonly cli?: (required: {
+        reg: unknown;
+        services: Services;
+    }) => void;
     /**
      * Releases whatever this pack's `services` acquired (a pty manager, a database handle, an OAuth
      * callback listener). Composition roots call these in reverse composition order, best-effort:
      * one pack's failure to dispose must never prevent another's from running.
      */
-    readonly dispose?: (services: Services) => Promise<void> | void;
+    readonly dispose?: (required: {
+        services: Services;
+    }) => Promise<void> | void;
+}
+export interface PackContributions<Services> {
+    tools?: (required: {
+        services: Services;
+    }) => readonly ToolRegistration[];
+    http?: (required: {
+        app: unknown;
+        services: Services;
+    }) => void;
+    cli?: (required: {
+        reg: unknown;
+        services: Services;
+    }) => void;
+    dispose?: (required: {
+        services: Services;
+    }) => Promise<void> | void;
 }
 export declare function definePack<const Name extends string, const Deps extends readonly AnyToken<unknown, string>[], Services>(def: {
     name: Name;
     deps: Deps;
     services: (c: PackContainer) => Services;
-    tools?: (services: Services) => readonly ToolRegistration[];
-    http?: (app: unknown, services: Services) => void;
-    cli?: (reg: unknown, services: Services) => void;
-    dispose?: (services: Services) => Promise<void> | void;
-}): Pack<Deps, Services, Name>;
+}, optional?: PackContributions<Services>): Pack<Deps, Services, Name>;
 //# sourceMappingURL=pack.d.ts.map

package/dist/pack.js

@@ -1,4 +1,4 @@
-export function definePack(def) {
-    return def;
+export function definePack(def, optional = {}) {
+    return { ...def, ...optional };
 }
 //# sourceMappingURL=pack.js.map

package/dist/primitives/http.d.ts

@@ -0,0 +1,57 @@
+/** One shared contract keeps binary, mail and webhook consumers behind the same egress guard.
+ * A guarded request requires a socket idle budget; total elapsed time is opt-in. */
+export type HttpRequest = {
+    /** HEAD supports certificate/header diagnostics without downloading the page body. */
+    method: "POST" | "GET" | "HEAD" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headers: Readonly<Record<string, string>>;
+    /** Preserve the signed bytes: re-serialization between signing and sending changes the signature. */
+    body?: string;
+    /** Whole-operation deadline, including DNS, redirects and body reads. Off by default.
+     * Retry/backoff belongs to the caller; its deadline can cover the whole retry operation. */
+    totalDeadlineMs?: number;
+    /** Bound the whole operation, including DNS and body reads, beyond the per-attempt timeout. */
+    signal?: AbortSignal;
+    /** Caller byte ceilings are bounded by the client policy, never a way to widen its cap. */
+    maxResponseBytes?: number;
+} & ({
+    idleTimeoutMs: number; /** Legacy alias for the socket idle budget. */
+    timeoutMs?: number;
+} | {
+    timeoutMs: number;
+    idleTimeoutMs?: number;
+});
+export interface HttpResponse {
+    status: number;
+    headers: Readonly<Record<string, string>>;
+    /** Bounded by the egress cap: a producer must not expose an unlimited text body through this port. */
+    bodyText: string;
+    /** Keep individual lines: Expires contains commas, so comma-splitting loses cookie boundaries. */
+    setCookies?: readonly string[];
+    /** UTF-8 decoding replaces invalid sequences and corrupts binary payloads. Expose the decompressed
+     * transport bytes here so binary consumers need not bypass DNS checks, peer pinning or redirects.
+     * Optional for older adapters/doubles; absence does not imply an empty payload. */
+    bodyBytes?: Uint8Array;
+    /** Coarse OR of text/byte clipping. A clipped image is corrupt, not merely smaller. Lossy UTF-8
+     * can expand invalid bytes into three-byte replacement characters and clip text even when all
+     * bytes fit, so binary consumers must use bodyBytesTruncated. Absence is an unknown verdict. */
+    bodyTruncated?: boolean;
+    /** Byte-specific completeness. A producer's unshaped truncation must count against both shapes
+     * rather than silently declaring bytes complete. Absent when no byte payload was supplied. */
+    bodyBytesTruncated?: boolean;
+    /** Provenance must name the guarded hop that supplied these bytes, not the requested URL or an
+     * unfollowed Location. Every followed hop is re-vetted. Older producers may omit this field,
+     * in which case consumers fall back to the request URL rather than inventing a blank source. */
+    finalUrl?: string;
+}
+export type RequestRedirect = "follow" | "error" | "manual";
+/** Consumers receive the policy-enforcing client; the raw transport is a composition seam.
+ * Keeping construction at the host boundary prevents consumers from bypassing egress checks. */
+export interface HttpClientPort {
+    send(required: {
+        request: HttpRequest;
+    }, optional?: {
+        redirect?: RequestRedirect;
+    }): Promise<HttpResponse>;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/primitives/http.js

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

package/dist/primitives/ids.d.ts

@@ -0,0 +1,8 @@
+/** Unbranded identifier; UUID-producing adapters and opaque host IDs share this port. */
+export type UUID = string;
+export interface IdGenerator {
+    newId(): string;
+}
+/** Uses the host's cryptographic UUID generator; no insecure random fallback. */
+export declare function createRandomUuidGenerator(): IdGenerator;
+//# sourceMappingURL=ids.d.ts.map

package/dist/primitives/ids.js

@@ -0,0 +1,5 @@
+/** Uses the host's cryptographic UUID generator; no insecure random fallback. */
+export function createRandomUuidGenerator() {
+    return { newId: () => globalThis.crypto.randomUUID() };
+}
+//# sourceMappingURL=ids.js.map

package/dist/primitives/index.d.ts

@@ -0,0 +1,8 @@
+export * from './time.js';
+export * from './ids.js';
+export * from './json.js';
+export * from './http.js';
+export * from './logger.js';
+export * from './result.js';
+export * from './paths.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/primitives/index.js

@@ -0,0 +1,8 @@
+export * from './time.js';
+export * from './ids.js';
+export * from './json.js';
+export * from './http.js';
+export * from './logger.js';
+export * from './result.js';
+export * from './paths.js';
+//# sourceMappingURL=index.js.map

package/dist/primitives/json.d.ts

@@ -0,0 +1,10 @@
+/** JSON wire values shared by contracts and domain packages. */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type JsonArray = JsonValue[];
+//# sourceMappingURL=json.d.ts.map

package/dist/primitives/json.js

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

package/dist/primitives/logger.d.ts

@@ -0,0 +1,26 @@
+/** Host-independent logging contract: diagnostics travel as optional structured data. */
+export interface Logger {
+    info(required: {
+        message: string;
+    }, optional?: {
+        meta?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+    warn(required: {
+        message: string;
+    }, optional?: {
+        meta?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+    error(required: {
+        message: string;
+    }, optional?: {
+        meta?: Record<string, unknown>;
+        error?: unknown;
+    }): void;
+}
+/** Minimal console adapter with a required host-owned prefix and structured metadata. */
+export declare function createConsoleLogger({ prefix }: {
+    prefix: string;
+}): Logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/primitives/logger.js

@@ -0,0 +1,17 @@
+/** Minimal console adapter with a required host-owned prefix and structured metadata. */
+export function createConsoleLogger({ prefix }) {
+    const write = (level, message, optional) => {
+        const args = [prefix ? `${prefix} ${message}` : message];
+        if (optional.meta !== undefined)
+            args.push(optional.meta);
+        if (optional.error !== undefined)
+            args.push(optional.error);
+        console[level](...args);
+    };
+    return {
+        info: ({ message }, optional = {}) => write('info', message, optional),
+        warn: ({ message }, optional = {}) => write('warn', message, optional),
+        error: ({ message }, optional = {}) => write('error', message, optional),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/primitives/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Check lexical containment using whole directory segments, including equality.
+ * Hosts resolve cwd-relative paths and symlinks before calling: checking a textual
+ * prefix alone can permit traversal or a symlink escape. Keeping that effect outside
+ * this helper makes the kernel browser-safe. Windows hosts select case-insensitive
+ * comparison and backslash separators; drive roots and UNC share roots remain distinct.
+ * POSIX backslashes remain literal characters, so distinct directories cannot alias.
+ */
+export declare function pathContains({ root, target }: {
+    root: string;
+    target: string;
+}, { caseSensitive, separator }?: {
+    caseSensitive?: boolean;
+    separator?: '/' | '\\';
+}): boolean;
+//# sourceMappingURL=paths.d.ts.map