@rotifer/playground 0.31.0 → 0.33.0

package/dist/memory/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * AgentMemory SDK (spec §38, v0.9.4) — what a gene author uses: the types,
+ * the GeneMemoryAccess interface a gene gets as ctx.memory, MemoryError and
+ * its codes, and the SDK layer over a store. Published as
+ * `@rotifer/playground/memory`; nothing here needs Node's types.
+ *
+ * The CLI's side — opening the agent's store in the project, the WASM
+ * path's binding, the throwaway memory of `rotifer test` — is in ./host.ts,
+ * which is not part of that surface.
+ */
+import type { GeneMemoryAccess } from "./access.js";
+import { type MemoryTelemetrySink } from "./telemetry.js";
+export * from "./types.js";
+export * from "./codec.js";
+export * from "./access.js";
+export * from "./data-policy.js";
+export * from "./telemetry.js";
+export * from "./audit.js";
+export { NapiMemoryBackend, asMemoryError, hasNativeMemory, type AgentMemoryConfig, type MemoryBackend, type MemoryCaller, type MemoryWriteRequest, type NativeMemoryApi, } from "./backend.js";
+/**
+ * The memory a gene gets when it runs with no agent around it (`rotifer run`
+ * of a single gene): every call is MEMORY_ACCESS_DENIED with a message that
+ * starts "no agent context". `ctx.memory` is never undefined,
+ * so a gene meets a clear error, not a TypeError on `undefined`.
+ *
+ * With a `telemetry` sink each refusal is also a §17 MEMORY_ACCESS_DENIED
+ * event — agentId null, no entry, `geneId` when the gene has a v2 id — and
+ * nothing else: there is no agent's memory to audit it in (as
+ * rotifer-core records a WASM gene's).
+ */
+export declare function noAgentMemory(options?: {
+    telemetry?: MemoryTelemetrySink;
+    geneId?: string | null;
+}): GeneMemoryAccess;
+/** Every call is MEMORY_STORAGE_ERROR "native binding unavailable". */
+export declare function memoryUnavailable(): GeneMemoryAccess;
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAA2C,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGnG,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAG3B,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAYtB;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAAG,gBAAgB,CAQzH;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,IAAI,gBAAgB,CAEpD"}

package/dist/memory/index.js

@@ -0,0 +1,64 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasNativeMemory = exports.asMemoryError = exports.NapiMemoryBackend = void 0;
+exports.noAgentMemory = noAgentMemory;
+exports.memoryUnavailable = memoryUnavailable;
+const telemetry_js_1 = require("./telemetry.js");
+const types_js_1 = require("./types.js");
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./codec.js"), exports);
+__exportStar(require("./access.js"), exports);
+__exportStar(require("./data-policy.js"), exports);
+__exportStar(require("./telemetry.js"), exports);
+__exportStar(require("./audit.js"), exports);
+// The store interface and the napi adapter; the JSON test double stays in
+// ./backend.ts for tests and is not part of this module's surface.
+var backend_js_1 = require("./backend.js");
+Object.defineProperty(exports, "NapiMemoryBackend", { enumerable: true, get: function () { return backend_js_1.NapiMemoryBackend; } });
+Object.defineProperty(exports, "asMemoryError", { enumerable: true, get: function () { return backend_js_1.asMemoryError; } });
+Object.defineProperty(exports, "hasNativeMemory", { enumerable: true, get: function () { return backend_js_1.hasNativeMemory; } });
+/** A GeneMemoryAccess whose every call throws `code` with `message`. */
+function refusingMemory(code, message) {
+    const refuse = () => {
+        throw new types_js_1.MemoryError(code, message);
+    };
+    return { readMemory: refuse, writeMemory: refuse, queryMemory: refuse, deleteMemory: refuse };
+}
+const NO_AGENT_CONTEXT = "no agent context: this gene is not running inside an agent, so it has no agent memory";
+/**
+ * The memory a gene gets when it runs with no agent around it (`rotifer run`
+ * of a single gene): every call is MEMORY_ACCESS_DENIED with a message that
+ * starts "no agent context". `ctx.memory` is never undefined,
+ * so a gene meets a clear error, not a TypeError on `undefined`.
+ *
+ * With a `telemetry` sink each refusal is also a §17 MEMORY_ACCESS_DENIED
+ * event — agentId null, no entry, `geneId` when the gene has a v2 id — and
+ * nothing else: there is no agent's memory to audit it in (as
+ * rotifer-core records a WASM gene's).
+ */
+function noAgentMemory(options = {}) {
+    const refuse = (operation) => () => {
+        options.telemetry?.((0, telemetry_js_1.accessDeniedEvent)({ agentId: null, geneId: options.geneId ?? null, entryId: null, operation, message: NO_AGENT_CONTEXT }));
+        throw new types_js_1.MemoryError("MEMORY_ACCESS_DENIED", NO_AGENT_CONTEXT);
+    };
+    return { readMemory: refuse("read"), writeMemory: refuse("write"), queryMemory: refuse("query"), deleteMemory: refuse("delete") };
+}
+/** Every call is MEMORY_STORAGE_ERROR "native binding unavailable". */
+function memoryUnavailable() {
+    return refusingMemory("MEMORY_STORAGE_ERROR", "native binding unavailable: agent memory needs the rotifer native addon on this platform");
+}
+//# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAsDA,sCAQC;AAGD,8CAEC;AAxDD,iDAAmG;AACnG,yCAAyC;AAEzC,6CAA2B;AAC3B,6CAA2B;AAC3B,8CAA4B;AAC5B,mDAAiC;AACjC,iDAA+B;AAC/B,6CAA2B;AAC3B,0EAA0E;AAC1E,mEAAmE;AACnE,2CASsB;AARpB,+GAAA,iBAAiB,OAAA;AACjB,2GAAA,aAAa,OAAA;AACb,6GAAA,eAAe,OAAA;AAQjB,wEAAwE;AACxE,SAAS,cAAc,CAAC,IAAqD,EAAE,OAAe;IAC5F,MAAM,MAAM,GAAG,GAAU,EAAE;QACzB,MAAM,IAAI,sBAAW,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC,CAAC;IACF,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;AAChG,CAAC;AAED,MAAM,gBAAgB,GAAG,uFAAuF,CAAC;AAEjH;;;;;;;;;;GAUG;AACH,SAAgB,aAAa,CAAC,UAAuE,EAAE;IACrG,MAAM,MAAM,GACV,CAAC,SAA0B,EAAE,EAAE,CAC/B,GAAU,EAAE;QACV,OAAO,CAAC,SAAS,EAAE,CAAC,IAAA,gCAAiB,EAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC,CAAC;QAC/I,MAAM,IAAI,sBAAW,CAAC,sBAAsB,EAAE,gBAAgB,CAAC,CAAC;IAClE,CAAC,CAAC;IACJ,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;AACpI,CAAC;AAED,uEAAuE;AACvE,SAAgB,iBAAiB;IAC/B,OAAO,cAAc,CAAC,sBAAsB,EAAE,0FAA0F,CAAC,CAAC;AAC5I,CAAC"}

package/dist/memory/telemetry.d.ts

@@ -0,0 +1,35 @@
+/** The operation names rotifer-core writes in metadata.operation. */
+export type MemoryOperation = "read" | "write" | "query" | "delete";
+export interface MemoryTelemetryEvent {
+    eventType: "MEMORY_ACCESS_DENIED";
+    bindingExtension: true;
+    traceContext: null;
+    /** null when the calling gene has no usable v2 id. */
+    geneId: string | null;
+    timestamp: string;
+    duration: null;
+    resourceUsage: null;
+    result: {
+        FAILURE: {
+            errorCode: "MEMORY_ACCESS_DENIED";
+            message: string;
+        };
+    };
+    /** agentId null outside any agent; entryId null when the call named no key. */
+    metadata: {
+        agentId: string | null;
+        entryId: string | null;
+        operation: MemoryOperation;
+    };
+}
+export type MemoryTelemetrySink = (event: MemoryTelemetryEvent) => void;
+export declare function fileTelemetrySink(root: string, env?: Record<string, string | undefined>): MemoryTelemetrySink;
+export declare function accessDeniedEvent(args: {
+    agentId: string | null;
+    geneId: string | null;
+    entryId: string | null;
+    operation: MemoryOperation;
+    message: string;
+    timestamp?: string;
+}): MemoryTelemetryEvent;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/memory/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/memory/telemetry.ts"],"names":[],"mappings":"AAkBA,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,sBAAsB,CAAC;IAClC,gBAAgB,EAAE,IAAI,CAAC;IACvB,YAAY,EAAE,IAAI,CAAC;IACnB,sDAAsD;IACtD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,IAAI,CAAC;IACf,aAAa,EAAE,IAAI,CAAC;IACpB,MAAM,EAAE;QAAE,OAAO,EAAE;YAAE,SAAS,EAAE,sBAAsB,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC5E,+EAA+E;IAC/E,QAAQ,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,eAAe,CAAA;KAAE,CAAC;CAC1F;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;AAExE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,mBAAmB,CAa1H;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,eAAe,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,oBAAoB,CAYvB"}

package/dist/memory/telemetry.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileTelemetrySink = fileTelemetrySink;
+exports.accessDeniedEvent = accessDeniedEvent;
+/**
+ * §17 telemetry for AgentMemory access denials (spec §38.2: "权限违规记录到
+ * §17 遥测系统").
+ *
+ * One §17.3 TelemetryEvent per line in `<root>/.rotifer/telemetry.jsonl`, in
+ * the shape rotifer-core writes (memory/events.rs MemoryTelemetryEvent), so a
+ * reader sees one format whichever binding denied the call. §17.3 has no
+ * memory event type, so `MEMORY_ACCESS_DENIED` carries `bindingExtension`.
+ * Local only, and it honours the same opt-out as the rest of the CLI's
+ * telemetry: ROTIFER_TELEMETRY=0 (or DO_NOT_TRACK) writes nothing here
+ *. The audit line for the same denial is written
+ * regardless (audit.ts). No key and no value: the entryId identifies the
+ * entry.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const consent_js_1 = require("../telemetry/consent.js");
+function fileTelemetrySink(root, env = process.env) {
+    const path = (0, node_path_1.join)(root, ".rotifer", "telemetry.jsonl");
+    return (event) => {
+        if ((0, consent_js_1.telemetryOptedOutByEnv)(env))
+            return;
+        // Telemetry is best-effort: the denial it reports stands, and the audit
+        // line (which is not best-effort) already recorded it.
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true, mode: 0o700 });
+            (0, node_fs_1.appendFileSync)(path, JSON.stringify(event) + "\n", { mode: 0o600 });
+        }
+        catch {
+            /* not a reason to fail the call */
+        }
+    };
+}
+function accessDeniedEvent(args) {
+    return {
+        eventType: "MEMORY_ACCESS_DENIED",
+        bindingExtension: true,
+        traceContext: null,
+        geneId: args.geneId,
+        timestamp: args.timestamp ?? new Date().toISOString(),
+        duration: null,
+        resourceUsage: null,
+        result: { FAILURE: { errorCode: "MEMORY_ACCESS_DENIED", message: args.message } },
+        metadata: { agentId: args.agentId, entryId: args.entryId, operation: args.operation },
+    };
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/memory/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/memory/telemetry.ts"],"names":[],"mappings":";;AAqCA,8CAaC;AAED,8CAmBC;AAvED;;;;;;;;;;;;;GAaG;AACH,qCAAoD;AACpD,yCAA0C;AAC1C,wDAAiE;AAqBjE,SAAgB,iBAAiB,CAAC,IAAY,EAAE,MAA0C,OAAO,CAAC,GAAG;IACnG,MAAM,IAAI,GAAG,IAAA,gBAAI,EAAC,IAAI,EAAE,UAAU,EAAE,iBAAiB,CAAC,CAAC;IACvD,OAAO,CAAC,KAAK,EAAE,EAAE;QACf,IAAI,IAAA,mCAAsB,EAAC,GAAG,CAAC;YAAE,OAAO;QACxC,wEAAwE;QACxE,uDAAuD;QACvD,IAAI,CAAC;YACH,IAAA,mBAAS,EAAC,IAAA,mBAAO,EAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAC3D,IAAA,wBAAc,EAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACtE,CAAC;QAAC,MAAM,CAAC;YACP,mCAAmC;QACrC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,SAAgB,iBAAiB,CAAC,IAOjC;IACC,OAAO;QACL,SAAS,EAAE,sBAAsB;QACjC,gBAAgB,EAAE,IAAI;QACtB,YAAY,EAAE,IAAI;QAClB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,IAAI,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACrD,QAAQ,EAAE,IAAI;QACd,aAAa,EAAE,IAAI;QACnB,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,sBAAsB,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE;QACjF,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;KACtF,CAAC;AACJ,CAAC"}

package/dist/memory/types.d.ts

@@ -0,0 +1,110 @@
+/**
+ * AgentMemory types — spec §38.1, shared by every binding.
+ *
+ * Field names are the spec's camelCase and enum values the spec's UPPERCASE
+ * strings, with no case folding anywhere: Rust, WASM host calls and the cloud
+ * table carry the same strings, and one lowercased copy is how the bindings
+ * drift apart.
+ *
+ * Two shapes of an entry:
+ *   - MemoryEntry      what a gene sees: `value` is bytes (Uint8Array);
+ *   - MemoryEntryJson  what crosses JSON (napi, host calls, cloud): `value`
+ *                      is standard base64, padded.
+ * toEntryJson / fromEntryJson are the only conversion between them.
+ */
+export declare const MEMORY_CATEGORIES: readonly ["PREFERENCE", "PATTERN", "CONTEXT", "CACHE"];
+export type MemoryCategory = (typeof MEMORY_CATEGORIES)[number];
+export declare const ACCESS_SCOPES: readonly ["CREATOR_GENE_ONLY", "SAME_DOMAIN", "ALL_GENES", "DEPLOYER_CONFIGURED"];
+export type AccessScope = (typeof ACCESS_SCOPES)[number];
+export declare const SHARE_POLICIES: readonly ["PRIVATE", "ANONYMIZED_SHARE", "KNOWLEDGE_GENE"];
+export type SharePolicy = (typeof SHARE_POLICIES)[number];
+export interface MemoryAccessPolicy {
+    readScope: AccessScope;
+    writeScope: AccessScope;
+    sharePolicy: SharePolicy;
+}
+/** What `writeMemory` uses when the caller gives no policy. */
+export declare const DEFAULT_ACCESS_POLICY: Readonly<MemoryAccessPolicy>;
+/** Spec §30.2 RetentionPolicy. */
+export interface RetentionPolicy {
+    /** null = no limit. */
+    maxRetentionDays: number | null;
+    autoDeleteOnTermination: boolean;
+    anonymizationSupported: boolean;
+}
+export interface MemoryEntry {
+    /** Lowercase hex SHA-256 of `agentId + "\0" + key` (entryIdFor). */
+    entryId: string;
+    category: MemoryCategory;
+    key: string;
+    value: Uint8Array;
+    /** Content-derived gene id of the gene that created the entry. */
+    createdBy: string;
+    lastAccessedBy: string | null;
+    /** RFC 3339 UTC. */
+    createdAt: string;
+    /** RFC 3339 UTC. */
+    updatedAt: string;
+    accessPolicy: MemoryAccessPolicy;
+    /** null = inherit the agent's DataPolicy retention. */
+    retentionPolicy: RetentionPolicy | null;
+}
+export type MemoryEntryJson = Omit<MemoryEntry, "value"> & {
+    value: string;
+};
+export interface AgentMemory {
+    agentId: string;
+    entries: MemoryEntry[];
+    /** Bytes of key + value over all entries (the quota's unit). */
+    totalSize: number;
+    /** Bytes. */
+    quota: number;
+    createdAt: string;
+}
+/**
+ * queryMemory's filter (final). Every field is optional
+ * and they combine with AND:
+ *   - category   one MemoryCategory;
+ *   - keyPrefix  a plain prefix of the key, not a pattern;
+ *   - since      RFC 3339, inclusive, compared with `updatedAt`;
+ *   - until      RFC 3339, exclusive, compared with `updatedAt`;
+ *   - limit      default 100, capped at 1000.
+ * Results come newest first (`updatedAt` descending, ties by `entryId`).
+ * Unknown fields are MEMORY_INVALID_INPUT; no alias names are accepted.
+ */
+export interface MemoryFilter {
+    category?: MemoryCategory;
+    keyPrefix?: string;
+    since?: string;
+    until?: string;
+    limit?: number;
+}
+export declare const MEMORY_FILTER_FIELDS: readonly ["category", "keyPrefix", "since", "until", "limit"];
+export declare const MEMORY_QUERY_DEFAULT_LIMIT = 100;
+export declare const MEMORY_QUERY_MAX_LIMIT = 1000;
+/**
+ * Shared across bindings. MEMORY_STORAGE_ERROR is a
+ * storage / IO failure, a missing native binding, or a database error; it is
+ * never folded into MEMORY_INVALID_INPUT.
+ */
+export declare const MEMORY_ERROR_CODES: readonly ["MEMORY_NOT_FOUND", "MEMORY_ACCESS_DENIED", "MEMORY_QUOTA_EXCEEDED", "MEMORY_INVALID_INPUT", "MEMORY_STORAGE_ERROR"];
+export type MemoryErrorCode = (typeof MEMORY_ERROR_CODES)[number];
+/**
+ * A memory error. `code` is one of the five; `message` is the explanation
+ * alone, without the code in front (a no-agent-context message
+ * starts with "no agent context").
+ */
+export declare class MemoryError extends Error {
+    readonly code: MemoryErrorCode;
+    constructor(code: MemoryErrorCode, message: string);
+}
+/** A single value, after base64 decoding. */
+export declare const MEMORY_MAX_VALUE_BYTES: number;
+/** One queryMemory response, serialized. */
+export declare const MEMORY_MAX_QUERY_RESPONSE_BYTES: number;
+/** 10 MB of key + value. */
+export declare const DEFAULT_MEMORY_QUOTA_BYTES: number;
+export declare function isMemoryCategory(value: unknown): value is MemoryCategory;
+export declare function isAccessScope(value: unknown): value is AccessScope;
+export declare function isSharePolicy(value: unknown): value is SharePolicy;
+//# sourceMappingURL=types.d.ts.map

package/dist/memory/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":"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"}

package/dist/memory/types.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * AgentMemory types — spec §38.1, shared by every binding.
+ *
+ * Field names are the spec's camelCase and enum values the spec's UPPERCASE
+ * strings, with no case folding anywhere: Rust, WASM host calls and the cloud
+ * table carry the same strings, and one lowercased copy is how the bindings
+ * drift apart.
+ *
+ * Two shapes of an entry:
+ *   - MemoryEntry      what a gene sees: `value` is bytes (Uint8Array);
+ *   - MemoryEntryJson  what crosses JSON (napi, host calls, cloud): `value`
+ *                      is standard base64, padded.
+ * toEntryJson / fromEntryJson are the only conversion between them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MEMORY_QUOTA_BYTES = exports.MEMORY_MAX_QUERY_RESPONSE_BYTES = exports.MEMORY_MAX_VALUE_BYTES = exports.MemoryError = exports.MEMORY_ERROR_CODES = exports.MEMORY_QUERY_MAX_LIMIT = exports.MEMORY_QUERY_DEFAULT_LIMIT = exports.MEMORY_FILTER_FIELDS = exports.DEFAULT_ACCESS_POLICY = exports.SHARE_POLICIES = exports.ACCESS_SCOPES = exports.MEMORY_CATEGORIES = void 0;
+exports.isMemoryCategory = isMemoryCategory;
+exports.isAccessScope = isAccessScope;
+exports.isSharePolicy = isSharePolicy;
+exports.MEMORY_CATEGORIES = ["PREFERENCE", "PATTERN", "CONTEXT", "CACHE"];
+exports.ACCESS_SCOPES = ["CREATOR_GENE_ONLY", "SAME_DOMAIN", "ALL_GENES", "DEPLOYER_CONFIGURED"];
+exports.SHARE_POLICIES = ["PRIVATE", "ANONYMIZED_SHARE", "KNOWLEDGE_GENE"];
+/** What `writeMemory` uses when the caller gives no policy. */
+exports.DEFAULT_ACCESS_POLICY = Object.freeze({
+    readScope: "SAME_DOMAIN",
+    writeScope: "SAME_DOMAIN",
+    sharePolicy: "PRIVATE",
+});
+exports.MEMORY_FILTER_FIELDS = ["category", "keyPrefix", "since", "until", "limit"];
+exports.MEMORY_QUERY_DEFAULT_LIMIT = 100;
+exports.MEMORY_QUERY_MAX_LIMIT = 1000;
+/**
+ * Shared across bindings. MEMORY_STORAGE_ERROR is a
+ * storage / IO failure, a missing native binding, or a database error; it is
+ * never folded into MEMORY_INVALID_INPUT.
+ */
+exports.MEMORY_ERROR_CODES = [
+    "MEMORY_NOT_FOUND",
+    "MEMORY_ACCESS_DENIED",
+    "MEMORY_QUOTA_EXCEEDED",
+    "MEMORY_INVALID_INPUT",
+    "MEMORY_STORAGE_ERROR",
+];
+/**
+ * A memory error. `code` is one of the five; `message` is the explanation
+ * alone, without the code in front (a no-agent-context message
+ * starts with "no agent context").
+ */
+class MemoryError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "MemoryError";
+        this.code = code;
+    }
+}
+exports.MemoryError = MemoryError;
+/** A single value, after base64 decoding. */
+exports.MEMORY_MAX_VALUE_BYTES = 1024 * 1024;
+/** One queryMemory response, serialized. */
+exports.MEMORY_MAX_QUERY_RESPONSE_BYTES = 4 * 1024 * 1024;
+/** 10 MB of key + value. */
+exports.DEFAULT_MEMORY_QUOTA_BYTES = 10 * 1024 * 1024;
+function isMemoryCategory(value) {
+    return typeof value === "string" && exports.MEMORY_CATEGORIES.includes(value);
+}
+function isAccessScope(value) {
+    return typeof value === "string" && exports.ACCESS_SCOPES.includes(value);
+}
+function isSharePolicy(value) {
+    return typeof value === "string" && exports.SHARE_POLICIES.includes(value);
+}
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAyHH,4CAEC;AAED,sCAEC;AAED,sCAEC;AAjIY,QAAA,iBAAiB,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAU,CAAC;AAG3E,QAAA,aAAa,GAAG,CAAC,mBAAmB,EAAE,aAAa,EAAE,WAAW,EAAE,qBAAqB,CAAU,CAAC;AAGlG,QAAA,cAAc,GAAG,CAAC,SAAS,EAAE,kBAAkB,EAAE,gBAAgB,CAAU,CAAC;AASzF,+DAA+D;AAClD,QAAA,qBAAqB,GAAiC,MAAM,CAAC,MAAM,CAAC;IAC/E,SAAS,EAAE,aAAa;IACxB,UAAU,EAAE,aAAa;IACzB,WAAW,EAAE,SAAS;CACvB,CAAC,CAAC;AA2DU,QAAA,oBAAoB,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAU,CAAC;AACrF,QAAA,0BAA0B,GAAG,GAAG,CAAC;AACjC,QAAA,sBAAsB,GAAG,IAAI,CAAC;AAE3C;;;;GAIG;AACU,QAAA,kBAAkB,GAAG;IAChC,kBAAkB;IAClB,sBAAsB;IACtB,uBAAuB;IACvB,sBAAsB;IACtB,sBAAsB;CACd,CAAC;AAGX;;;;GAIG;AACH,MAAa,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAkB;IAC/B,YAAY,IAAqB,EAAE,OAAe;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAPD,kCAOC;AAED,6CAA6C;AAChC,QAAA,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;AAClD,4CAA4C;AAC/B,QAAA,+BAA+B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE/D,4BAA4B;AACf,QAAA,0BAA0B,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3D,SAAgB,gBAAgB,CAAC,KAAc;IAC7C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,yBAAuC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC/F,CAAC;AAED,SAAgB,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,qBAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3F,CAAC;AAED,SAAgB,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,sBAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC"}

package/dist/publish/auto-publish.d.ts

@@ -90,7 +90,7 @@ export declare function needsNetworkConfigBeforePublish(geneDir: string, fidelit
  * independent cursor-agent pyramid test run, 2026-08-31, which is also why
  * this is a pure function rather than a PTY-driven E2E test: reproducing it
  * needs a real TTY, and this repo's CI matrix runs both ubuntu-latest and
- * macos-14, whose `script` binaries take incompatible arguments — a
+ * macOS, whose `script` binaries take incompatible arguments — a
  * behavioural test for a one-line data-selection bug was the wrong layer.
  *
  * The on-disk phenotype wins whenever one was actually loaded; the CLI flag

package/dist/publish/auto-publish.js

@@ -111,7 +111,7 @@ function needsNetworkConfigBeforePublish(geneDir, fidelity) {
  * independent cursor-agent pyramid test run, 2026-08-31, which is also why
  * this is a pure function rather than a PTY-driven E2E test: reproducing it
  * needs a real TTY, and this repo's CI matrix runs both ubuntu-latest and
- * macos-14, whose `script` binaries take incompatible arguments — a
+ * macOS, whose `script` binaries take incompatible arguments — a
  * behavioural test for a one-line data-selection bug was the wrong layer.
  *
  * The on-disk phenotype wins whenever one was actually loaded; the CLI flag

package/dist/runtime/network-gateway.d.ts

@@ -4,7 +4,14 @@
  * Enforces domain whitelist, per-request timeout, response size cap,
  * and per-minute rate limiting. Genes call `gatewayFetch()` instead
  * of raw `fetch()`.
+ *
+ * SSRF hardening, the same as the WASM path (rotifer-core hybrid.rs
+ * `check_url` / `perform_fetch`, Hybrid Binding API §2.1): https only, no IP
+ * literals, and redirects followed by hand, at most MAX_REDIRECT_HOPS, each
+ * hop checked against the whitelist before it is requested.
  */
+/** Same as rotifer-core `constants::MAX_REDIRECT_HOPS`. */
+export declare const MAX_REDIRECT_HOPS = 5;
 export interface NetworkConfig {
     allowedDomains: string[];
     maxTimeoutMs: number;
@@ -23,22 +30,35 @@ export interface GatewayResponse {
     isTruncated: boolean;
 }
 export declare class NetworkGatewayError extends Error {
-    readonly code: "DOMAIN_BLOCKED" | "RATE_LIMITED" | "TIMEOUT" | "RESPONSE_TOO_LARGE" | "NETWORK_ERROR";
-    constructor(code: "DOMAIN_BLOCKED" | "RATE_LIMITED" | "TIMEOUT" | "RESPONSE_TOO_LARGE" | "NETWORK_ERROR", message: string);
+    readonly code: "DOMAIN_BLOCKED" | "INVALID_REQUEST" | "RATE_LIMITED" | "TIMEOUT" | "RESPONSE_TOO_LARGE" | "NETWORK_ERROR";
+    constructor(code: "DOMAIN_BLOCKED" | "INVALID_REQUEST" | "RATE_LIMITED" | "TIMEOUT" | "RESPONSE_TOO_LARGE" | "NETWORK_ERROR", message: string);
+}
+/** Binding-internal options, never read from a phenotype. */
+export interface GatewayTestOptions {
+    /** Test hook, as rotifer-core's `allow_insecure_loopback`: permit plain
+     * http to loopback hosts and loopback IP literals. Off in every production
+     * path — `createGatewayFetch`, which the CLI uses, never sets it. */
+    allowInsecureLoopbackForTests?: boolean;
 }
 export declare class NetworkGateway {
     private config;
+    private allowInsecureLoopback;
     private requestTimestamps;
     private totalRequests;
     private totalBytes;
-    constructor(config?: Partial<NetworkConfig>);
+    constructor(config?: Partial<NetworkConfig>, testOptions?: GatewayTestOptions);
     get stats(): {
         totalRequests: number;
         totalBytes: number;
         windowRequests: number;
     };
     fetch(url: string, options?: GatewayFetchOptions): Promise<GatewayResponse>;
-    private validateDomain;
+    /** Whitelist first, then scheme and host shape. Runs for the first request
+     * and for every redirect hop. rotifer-core's `check_url` checks shape first;
+     * here a URL off the whitelist keeps the DOMAIN_BLOCKED callers have always
+     * had, and INVALID_REQUEST is what a whitelisted host gets over http or as
+     * an IP literal. Either way nothing is sent. */
+    private validateUrl;
     private enforceRateLimit;
     private readBodyCapped;
 }

package/dist/runtime/network-gateway.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-gateway.d.ts","sourceRoot":"","sources":["../../src/runtime/network-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAChB,gBAAgB,GAChB,cAAc,GACd,SAAS,GACT,oBAAoB,GACpB,eAAe;gBALH,IAAI,EAChB,gBAAgB,GAChB,cAAc,GACd,SAAS,GACT,oBAAoB,GACpB,eAAe,EACnB,OAAO,EAAE,MAAM;CAKlB;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;gBAEX,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC;IAI3C,IAAI,KAAK;;;;MAMR;IAEK,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkDjF,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,gBAAgB;YAiBV,cAAc;CAmC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAC7B;IACD,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACvF,OAAO,EAAE,cAAc,CAAC;CACzB,CAMA"}
+{"version":3,"file":"network-gateway.d.ts","sourceRoot":"","sources":["../../src/runtime/network-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,IAAI,EAChB,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,SAAS,GACT,oBAAoB,GACpB,eAAe;gBANH,IAAI,EAChB,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,SAAS,GACT,oBAAoB,GACpB,eAAe,EACnB,OAAO,EAAE,MAAM;CAKlB;AAkBD,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC;;yEAEqE;IACrE,6BAA6B,CAAC,EAAE,OAAO,CAAC;CACzC;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,qBAAqB,CAAU;IACvC,OAAO,CAAC,iBAAiB,CAAgB;IACzC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;gBAEX,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,EAAE,WAAW,GAAE,kBAAuB;IAKjF,IAAI,KAAK;;;;MAMR;IAEK,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IA0FjF;;;;oDAIgD;IAChD,OAAO,CAAC,WAAW;IA6CnB,OAAO,CAAC,gBAAgB;YAiBV,cAAc;CAmC7B;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAC7B;IACD,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;IACvF,OAAO,EAAE,cAAc,CAAC;CACzB,CAMA"}

package/dist/runtime/network-gateway.js

@@ -5,10 +5,17 @@
  * Enforces domain whitelist, per-request timeout, response size cap,
  * and per-minute rate limiting. Genes call `gatewayFetch()` instead
  * of raw `fetch()`.
+ *
+ * SSRF hardening, the same as the WASM path (rotifer-core hybrid.rs
+ * `check_url` / `perform_fetch`, Hybrid Binding API §2.1): https only, no IP
+ * literals, and redirects followed by hand, at most MAX_REDIRECT_HOPS, each
+ * hop checked against the whitelist before it is requested.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NetworkGateway = exports.NetworkGatewayError = void 0;
+exports.NetworkGateway = exports.NetworkGatewayError = exports.MAX_REDIRECT_HOPS = void 0;
 exports.createGatewayFetch = createGatewayFetch;
+/** Same as rotifer-core `constants::MAX_REDIRECT_HOPS`. */
+exports.MAX_REDIRECT_HOPS = 5;
 class NetworkGatewayError extends Error {
     code;
     constructor(code, message) {
@@ -24,13 +31,23 @@ const DEFAULT_CONFIG = {
     maxResponseBytes: 1_048_576, // 1 MiB
     maxRequestsPerMin: 10,
 };
+/** Headers that describe a request body (fetch's "request-body-header names"),
+ * dropped when a redirect turns the request into a body-less GET. */
+const BODY_HEADERS = new Set(["content-encoding", "content-language", "content-location", "content-type", "content-length"]);
+function withoutBodyHeaders(headers) {
+    if (!headers)
+        return headers;
+    return Object.fromEntries(Object.entries(headers).filter(([k]) => !BODY_HEADERS.has(k.toLowerCase())));
+}
 class NetworkGateway {
     config;
+    allowInsecureLoopback;
     requestTimestamps = [];
     totalRequests = 0;
     totalBytes = 0;
-    constructor(config) {
+    constructor(config, testOptions = {}) {
         this.config = { ...DEFAULT_CONFIG, ...config };
+        this.allowInsecureLoopback = testOptions.allowInsecureLoopbackForTests === true;
     }
     get stats() {
         return {
@@ -40,17 +57,57 @@ class NetworkGateway {
         };
     }
     async fetch(url, options) {
-        this.validateDomain(url);
+        this.validateUrl(url);
         this.enforceRateLimit();
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), this.config.maxTimeoutMs);
         try {
-            const response = await fetch(url, {
-                method: options?.method || "POST",
-                headers: options?.headers,
-                body: options?.body,
-                signal: controller.signal,
-            });
+            // Redirects are followed here, not by fetch: fetch would follow a
+            // whitelisted host's 302 to anywhere. Every hop is checked before it
+            // is requested; the timeout covers the whole chain.
+            //
+            // What a hop carries follows fetch's own redirect rules, made stricter:
+            // - 301/302/303 turn a request that is not GET/HEAD into a GET with no
+            //   body (and no body headers); 307/308 keep the method and body.
+            // - Moving to another origin (scheme, host or port) drops every header
+            //   the gene set, not only Authorization: a key travels just as well in
+            //   X-Api-Key or apikey, and the next host is someone else even when
+            //   it matches the same *.domain wildcard.
+            let current = url;
+            let method = options?.method || "POST";
+            let requestHeaders = options?.headers;
+            let body = options?.body;
+            let response;
+            for (let hop = 0; hop <= exports.MAX_REDIRECT_HOPS; hop++) {
+                if (hop > 0)
+                    this.validateUrl(current);
+                response = await fetch(current, {
+                    method,
+                    headers: requestHeaders,
+                    body,
+                    signal: controller.signal,
+                    redirect: "manual",
+                });
+                const location = response.headers.get("location");
+                if (response.status < 300 || response.status >= 400 || !location)
+                    break;
+                if (hop === exports.MAX_REDIRECT_HOPS) {
+                    await response.body?.cancel();
+                    throw new NetworkGatewayError("NETWORK_ERROR", `Request to ${url} failed: more than ${exports.MAX_REDIRECT_HOPS} redirects`);
+                }
+                await response.body?.cancel();
+                const next = new URL(location, current);
+                if ([301, 302, 303].includes(response.status) && method !== "GET" && method !== "HEAD") {
+                    method = "GET";
+                    body = undefined;
+                    requestHeaders = withoutBodyHeaders(requestHeaders);
+                }
+                if (next.origin !== new URL(current).origin)
+                    requestHeaders = undefined;
+                current = next.toString();
+            }
+            if (!response)
+                throw new Error("no response");
             const { text, isTruncated } = await this.readBodyCapped(response);
             this.totalRequests++;
             this.totalBytes += text.length;
@@ -66,6 +123,8 @@ class NetworkGateway {
             };
         }
         catch (err) {
+            if (err instanceof NetworkGatewayError)
+                throw err;
             if (err.name === "AbortError") {
                 throw new NetworkGatewayError("TIMEOUT", `Request to ${url} timed out after ${this.config.maxTimeoutMs}ms`);
             }
@@ -75,14 +134,20 @@ class NetworkGateway {
             clearTimeout(timeout);
         }
     }
-    validateDomain(url) {
-        let hostname;
+    /** Whitelist first, then scheme and host shape. Runs for the first request
+     * and for every redirect hop. rotifer-core's `check_url` checks shape first;
+     * here a URL off the whitelist keeps the DOMAIN_BLOCKED callers have always
+     * had, and INVALID_REQUEST is what a whitelisted host gets over http or as
+     * an IP literal. Either way nothing is sent. */
+    validateUrl(url) {
+        let parsed;
         try {
-            hostname = new URL(url).hostname;
+            parsed = new URL(url);
         }
         catch {
             throw new NetworkGatewayError("DOMAIN_BLOCKED", `Invalid URL: ${url}`);
         }
+        const hostname = parsed.hostname;
         const isAllowed = this.config.allowedDomains.some((d) => {
             if (d.startsWith("*.")) {
                 return hostname.endsWith(d.slice(1)) || hostname === d.slice(2);
@@ -92,6 +157,15 @@ class NetworkGateway {
         if (!isAllowed) {
             throw new NetworkGatewayError("DOMAIN_BLOCKED", `Domain "${hostname}" is not in the allowed list: [${this.config.allowedDomains.join(", ")}]`);
         }
+        const isIpLiteral = /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname) || hostname.startsWith("[");
+        const isLoopback = hostname === "localhost" || hostname === "[::1]" || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname);
+        const isLoopbackAdmitted = this.allowInsecureLoopback && isLoopback;
+        if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && isLoopbackAdmitted)) {
+            throw new NetworkGatewayError("INVALID_REQUEST", `Only https is allowed: ${parsed.protocol}//${hostname}`);
+        }
+        if (isIpLiteral && !isLoopbackAdmitted) {
+            throw new NetworkGatewayError("INVALID_REQUEST", `IP addresses are not allowed, use a host name: ${hostname}`);
+        }
     }
     enforceRateLimit() {
         const now = Date.now();