@fungi.computer/zookeeper 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# Zookeeper
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zookeeper governs one Durable Object's store. Storage and memory limits for
+Durable Objects belong here, never in Shiitake core.
+
+Zookeeper is an installable package candidate because Oyster's public Shiitake
+host uses its pressure check and patrol at runtime. Its stranger fixture checks
+the packed exports without workspace links. This packaging boundary does not
+authorize an external repository, registry publication, or deployment.
+
+`openStoragePressure({ usedBytes, budgetBytes })` returns the host's
+`StoragePressureCheck` for Shiitake's `storagePressure` option. It reports
+pressure at 80% of the budget and keeps reporting it until usage falls below
+75%, so admission does not flap at the threshold. Shiitake keeps the refusal
+door and the typed `storage_pressure` error; Zookeeper owns the numbers.
+
+An invalid budget throws a `contract`/`invalid` `ShiitakeError` when opened. An
+unreadable measurement throws a `store`/`unavailable` `ShiitakeError`, which
+refuses the new work.
+
+Zookeeper is Shiitake-only. Pi Durable hosts are out of scope.
+
+`openPatrol({ budget, readColdSessions, report })` returns host work for
+Shiitake's `hostWork`. Its synchronous `pending` reads only the platform's size
+of the store: `nextWakeAt` is `null` while the store is under the waterline
+(half the budget) and a time at least a second ahead (five minutes by default)
+while it is over. Its `run` is one bounded pass: when the store is over the
+waterline it reads one page of Sessions, skips a Session whose bytes are unknown
+or whose row cannot be read, and hands the host a typed `PatrolReport`. It
+evicts nothing.
+
+`zookeeperCompaction({ writer })` is the compaction handoff extension over a
+host-bound `ArchiveWriter`; the host appends it and `zookeeperCompactionGrant`
+to its roster. It archives what leaves the model context (the history and
+turn-prefix messages, not the summary), returns the writer's receipt as the
+opaque `accepted` receipt, and answers `discarded_by_policy` only when nothing
+leaves the context. A writer failure is a handoff failure, so compaction stops
+with the prior context intact; it is never a discard.

package/dist/archive-format.d.ts

@@ -0,0 +1,23 @@
+import type { BorrowedCompactionViewV0 } from "@fungi.computer/shiitake";
+import type { ArchiveWriteV1 } from "./archive-writer.js";
+/** Format name written in the first line of every archive. */
+export declare const ARCHIVE_FORMAT = "zookeeper.compaction-archive/1";
+/** Largest chunk a writer is handed. */
+export declare const ARCHIVE_CHUNK_BYTES: number;
+/** The part of a borrowed compaction view that leaves the model context. */
+export type ArchiveSource = Pick<BorrowedCompactionViewV0, "contextRevision" | "messagesToSummarize" | "turnPrefixMessages"> & Readonly<{
+    firstKeptEntryId: string;
+}>;
+/** Size and identity of an archive; carries no bytes. */
+export type ArchiveMeasure = Readonly<{
+    byteLength: number;
+    sha256: string;
+    materialKey: string;
+}>;
+/** Pass 1: hash and count the lines one at a time, retaining none. */
+export declare function measureArchive(lines: Iterable<Uint8Array>): ArchiveMeasure;
+/**
+ * Prepare one archive write: pass 1 measures, and `chunks()` is pass 2,
+ * re-encoding on demand so no full copy is ever held.
+ */
+export declare function prepareArchiveWrite(sessionId: string, source: ArchiveSource): ArchiveWriteV1;

package/dist/archive-format.js

@@ -0,0 +1,70 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+/** Format name written in the first line of every archive. */
+export const ARCHIVE_FORMAT = "zookeeper.compaction-archive/1";
+/** Largest chunk a writer is handed. */
+export const ARCHIVE_CHUNK_BYTES = 64 * 1024;
+const encoder = new TextEncoder();
+/**
+ * NDJSON lines: a header, then history messages, then turn-prefix messages.
+ * The summary and usage are model output kept in the compaction entry, so
+ * they are not archived.
+ */
+function* archiveLines(source) {
+    const line = (value) => encoder.encode(`${JSON.stringify(value)}\n`);
+    yield line({
+        format: ARCHIVE_FORMAT,
+        version: 1,
+        contextRevision: source.contextRevision,
+        firstKeptEntryId: source.firstKeptEntryId,
+        counts: {
+            history: source.messagesToSummarize.length,
+            turn_prefix: source.turnPrefixMessages.length,
+        },
+    });
+    for (const message of source.messagesToSummarize) {
+        yield line({ section: "history", message });
+    }
+    for (const message of source.turnPrefixMessages) {
+        yield line({ section: "turn_prefix", message });
+    }
+}
+/** Pass 1: hash and count the lines one at a time, retaining none. */
+export function measureArchive(lines) {
+    const hash = sha256.create();
+    let byteLength = 0;
+    for (const bytes of lines) {
+        hash.update(bytes);
+        byteLength += bytes.byteLength;
+    }
+    const digest = bytesToHex(hash.digest());
+    return { byteLength, sha256: digest, materialKey: digest.slice(0, 32) };
+}
+function* sliceChunks(source) {
+    for (const bytes of archiveLines(source)) {
+        for (let at = 0; at < bytes.byteLength; at += ARCHIVE_CHUNK_BYTES) {
+            yield bytes.subarray(at, at + ARCHIVE_CHUNK_BYTES);
+        }
+    }
+}
+function archiveChunks(source) {
+    return {
+        [Symbol.asyncIterator]: () => {
+            const chunks = sliceChunks(source);
+            return { next: () => Promise.resolve(chunks.next()) };
+        },
+    };
+}
+/**
+ * Prepare one archive write: pass 1 measures, and `chunks()` is pass 2,
+ * re-encoding on demand so no full copy is ever held.
+ */
+export function prepareArchiveWrite(sessionId, source) {
+    const measure = measureArchive(archiveLines(source));
+    return {
+        sessionId,
+        contextRevision: source.contextRevision,
+        ...measure,
+        chunks: () => archiveChunks(source),
+    };
+}

package/dist/archive-key.d.ts

@@ -0,0 +1,20 @@
+/** Longest path or key segment a writer is handed for a Session. */
+export declare const ARCHIVE_SEGMENT_MAX = 200;
+/**
+ * The one place a Session id becomes a path or key segment, shared by every
+ * host writer. Shiitake lets a client name its Session with any text up to 256
+ * characters, but a segment must be one safe path element.
+ *
+ * - A plain id (letters, digits, `_`, `-`, not starting with `-`) is kept.
+ * - Any other id is `e.` followed by its UTF-8 bytes, each byte outside the
+ *   plain alphabet written as `.xx` (lowercase hex). A plain id never contains
+ *   `.`, so an encoded segment can never equal a plain one, and `.` always
+ *   begins an escape, so two ids never share a segment and the id is
+ *   recoverable.
+ * - A segment that would pass {@link ARCHIVE_SEGMENT_MAX} is `h.` and the
+ *   SHA-256 of the id's UTF-8 bytes: bounded, collision-free in practice, and
+ *   not reversible.
+ *
+ * The empty id has no segment; it returns `""`, which writers refuse.
+ */
+export declare function archiveSessionSegment(sessionId: string): string;

package/dist/archive-key.js

@@ -0,0 +1,42 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex } from "@noble/hashes/utils.js";
+/** Longest path or key segment a writer is handed for a Session. */
+export const ARCHIVE_SEGMENT_MAX = 200;
+const plain = /^[A-Za-z0-9_][A-Za-z0-9_-]*$/;
+const literal = /^[A-Za-z0-9_-]$/;
+const encoder = new TextEncoder();
+/**
+ * The one place a Session id becomes a path or key segment, shared by every
+ * host writer. Shiitake lets a client name its Session with any text up to 256
+ * characters, but a segment must be one safe path element.
+ *
+ * - A plain id (letters, digits, `_`, `-`, not starting with `-`) is kept.
+ * - Any other id is `e.` followed by its UTF-8 bytes, each byte outside the
+ *   plain alphabet written as `.xx` (lowercase hex). A plain id never contains
+ *   `.`, so an encoded segment can never equal a plain one, and `.` always
+ *   begins an escape, so two ids never share a segment and the id is
+ *   recoverable.
+ * - A segment that would pass {@link ARCHIVE_SEGMENT_MAX} is `h.` and the
+ *   SHA-256 of the id's UTF-8 bytes: bounded, collision-free in practice, and
+ *   not reversible.
+ *
+ * The empty id has no segment; it returns `""`, which writers refuse.
+ */
+export function archiveSessionSegment(sessionId) {
+    if (sessionId === "")
+        return "";
+    if (plain.test(sessionId) && sessionId.length <= ARCHIVE_SEGMENT_MAX)
+        return sessionId;
+    const bytes = encoder.encode(sessionId);
+    let encoded = "e.";
+    for (const byte of bytes) {
+        const character = String.fromCharCode(byte);
+        encoded +=
+            byte < 0x80 && literal.test(character)
+                ? character
+                : `.${byte.toString(16).padStart(2, "0")}`;
+        if (encoded.length > ARCHIVE_SEGMENT_MAX)
+            return `h.${bytesToHex(sha256(bytes))}`;
+    }
+    return encoded;
+}

package/dist/archive-writer.d.ts

@@ -0,0 +1,35 @@
+import type { Effect } from "effect";
+/**
+ * One archive handed to a host's writer. `chunks` is re-iterable; each chunk
+ * is at most 64 KiB and the chunks total exactly `byteLength` bytes whose
+ * SHA-256 is `sha256`.
+ */
+export type ArchiveWriteV1 = Readonly<{
+    sessionId: string;
+    contextRevision: string;
+    /** First 32 hex characters of `sha256`: the content digest key. */
+    materialKey: string;
+    byteLength: number;
+    /** Lowercase hex SHA-256 of the archive bytes. */
+    sha256: string;
+    chunks: () => AsyncIterable<Uint8Array>;
+}>;
+/** What a writer proves it stored; encoded by the host as the opaque receipt. */
+export type ArchiveReceiptV1 = Readonly<{
+    key: string;
+    sha256: string;
+    byteLength: number;
+}>;
+/**
+ * Writer failure. `conflict` is different bytes under an existing key,
+ * `invalid` a chunk over the bound or a stream that disagrees with the
+ * declared length or digest, `unavailable` a store that could not be written.
+ */
+export type ArchiveWriteError = Readonly<{
+    _tag: "ArchiveWriteError";
+    reason: "unavailable" | "conflict" | "invalid";
+}>;
+/** Host-owned storage port; Zookeeper owns the bytes, the host owns the place. */
+export type ArchiveWriter = Readonly<{
+    write: (input: ArchiveWriteV1) => Effect.Effect<ArchiveReceiptV1, ArchiveWriteError>;
+}>;

package/dist/archive-writer.js

@@ -0,0 +1 @@
+export {};

package/dist/handoff.d.ts

@@ -0,0 +1,16 @@
+import { type CompactionHandoffV0, type ExtensionGrantV0, type RosteredExtensionV0 } from "@fungi.computer/shiitake/extensions";
+import type { ArchiveWriter } from "./archive-writer.js";
+/** The one grant Zookeeper's handoff needs; a host appends it beside the extension. */
+export declare const zookeeperCompactionGrant: ExtensionGrantV0;
+/**
+ * Archive exactly what leaves the model context. A write failure is a handoff
+ * failure, never a policy discard, so compaction stops with the context intact.
+ */
+export declare function archiveHandoff(writer: ArchiveWriter): CompactionHandoffV0;
+/**
+ * Zookeeper's compaction handoff over a host-bound writer. The host owns the
+ * Agent and the place; the view supplies the Session.
+ */
+export declare function zookeeperCompaction(options: Readonly<{
+    writer: ArchiveWriter;
+}>): RosteredExtensionV0;

package/dist/handoff.js

@@ -0,0 +1,49 @@
+import { defineExtension, ExtensionId, } from "@fungi.computer/shiitake/extensions";
+import * as Effect from "effect/Effect";
+import { prepareArchiveWrite } from "./archive-format.js";
+const id = ExtensionId.make("zookeeper-compaction");
+/** The one grant Zookeeper's handoff needs; a host appends it beside the extension. */
+export const zookeeperCompactionGrant = {
+    id,
+    capabilities: ["compaction_handoff"],
+};
+/** The opaque receipt Shiitake carries: the writer's receipt as JSON. */
+function encodeReceipt(receipt) {
+    return JSON.stringify(receipt);
+}
+/**
+ * Archive exactly what leaves the model context. A write failure is a handoff
+ * failure, never a policy discard, so compaction stops with the context intact.
+ */
+export function archiveHandoff(writer) {
+    return { consume: (view) => archive(writer, view) };
+}
+function archive(writer, view) {
+    if (view.messagesToSummarize.length === 0 &&
+        view.turnPrefixMessages.length === 0)
+        return Effect.succeed({ type: "discarded_by_policy" });
+    const write = prepareArchiveWrite(view.sessionId, {
+        contextRevision: view.contextRevision,
+        firstKeptEntryId: view.result.firstKeptEntryId,
+        messagesToSummarize: view.messagesToSummarize,
+        turnPrefixMessages: view.turnPrefixMessages,
+    });
+    return writer.write(write).pipe(Effect.map((receipt) => ({
+        type: "accepted",
+        receipt: encodeReceipt(receipt),
+    })), Effect.mapError((error) => ({
+        _tag: "CompactionHandoffError",
+        message: `Compaction archive write failed: ${error.reason}`,
+    })));
+}
+/**
+ * Zookeeper's compaction handoff over a host-bound writer. The host owns the
+ * Agent and the place; the view supplies the Session.
+ */
+export function zookeeperCompaction(options) {
+    return defineExtension({ id, version: "1.0.0" }).define({
+        compaction: () => ({
+            consume: archiveHandoff(options.writer).consume,
+        }),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./archive-format.js";
+export * from "./archive-key.js";
+export * from "./archive-writer.js";
+export * from "./handoff.js";
+export * from "./patrol.js";
+export * from "./pressure.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./archive-format.js";
+export * from "./archive-key.js";
+export * from "./archive-writer.js";
+export * from "./handoff.js";
+export * from "./patrol.js";
+export * from "./pressure.js";

package/dist/patrol.d.ts

@@ -0,0 +1,58 @@
+import type { ColdSessionPage, ColdSessionPageRequest } from "@fungi.computer/shiitake";
+import { type StorageBudget } from "./pressure.js";
+/** What one patrol pass measured. The patrol evicts nothing. */
+export type PatrolReport = Readonly<{
+    status: "quiet";
+    usedBytes: number;
+    waterlineBytes: number;
+}> | Readonly<{
+    status: "measured";
+    usedBytes: number;
+    waterlineBytes: number;
+    /** Sessions read in this page. */
+    sessions: number;
+    /** Bytes of the Sessions read. */
+    sessionBytes: number;
+    /** Bytes of the counted Sessions that are idle. */
+    idleBytes: number;
+    /** True when colder Sessions remain beyond this page. */
+    more: boolean;
+}> | Readonly<{
+    status: "unavailable";
+    /** What could not be read: the platform's size or the Session page. */
+    source: "store-size" | "cold-sessions";
+    /** The failure's name only; no stored data. */
+    failure: string;
+}>;
+/**
+ * The patrol as Shiitake host work: structurally Cloudflare's
+ * `CloudflareHostWork`, declared here so Zookeeper takes no Cloudflare types.
+ */
+export type PatrolWork = Readonly<{
+    /** Read synchronously inside the alarm transaction. */
+    pending: () => Readonly<{
+        due: boolean;
+        nextWakeAt: number | null;
+    }>;
+    /** One bounded pass, requested on every durable wake. */
+    run: () => Promise<void>;
+}>;
+/** What the patrol needs from its host. */
+export type PatrolOptions = Readonly<{
+    /** The platform's synchronous size of the store, and the host's budget. */
+    budget: StorageBudget;
+    /** The owner's bounded, read-only page of Sessions, coldest first. */
+    readColdSessions: (request: ColdSessionPageRequest) => Promise<ColdSessionPage>;
+    /** Receives what each pass measured; the host logs it. */
+    report: (report: PatrolReport) => void;
+    now?: () => number;
+    cadenceMs?: number;
+}>;
+/**
+ * Open the patrol as Shiitake host work. `pending` is read synchronously inside
+ * the alarm transaction, so it uses only the platform's synchronous size of the
+ * store: it reports a wake only while the store is over the waterline, and
+ * `null` when it is quiet. `run` is one bounded pass that measures and
+ * reports. It evicts nothing.
+ */
+export declare function openPatrol(options: PatrolOptions): PatrolWork;

package/dist/patrol.js

@@ -0,0 +1,107 @@
+import * as Schema from "effect/Schema";
+import { checkedBudgetBytes } from "./pressure.js";
+/**
+ * Provisional. The patrol has work once the store holds more than this
+ * fraction of the host's budget; it is below the refusal door's 80%, so the
+ * patrol sees a growing store before admission is refused.
+ */
+const patrolWaterlineFraction = 0.5;
+/** Provisional. How soon the patrol looks again while the store stays over. */
+const defaultCadenceMs = 5 * 60_000;
+/** A wake is never closer than this, whatever cadence the host asks for. */
+const minimumCadenceMs = 1_000;
+/** Sessions measured in one pass: one bounded page, never a walk of the store. */
+const patrolPageLimit = 50;
+const decodeBytes = Schema.decodeUnknownResult(Schema.Number.pipe(Schema.check(Schema.isFinite()), Schema.check(Schema.isGreaterThanOrEqualTo(0))));
+/**
+ * Open the patrol as Shiitake host work. `pending` is read synchronously inside
+ * the alarm transaction, so it uses only the platform's synchronous size of the
+ * store: it reports a wake only while the store is over the waterline, and
+ * `null` when it is quiet. `run` is one bounded pass that measures and
+ * reports. It evicts nothing.
+ */
+export function openPatrol(options) {
+    const now = options.now ?? Date.now;
+    const cadenceMs = Math.max(options.cadenceMs ?? defaultCadenceMs, minimumCadenceMs);
+    const waterlineBytes = checkedBudgetBytes(options.budget) * patrolWaterlineFraction;
+    const measureStore = () => {
+        try {
+            const used = decodeBytes(options.budget.usedBytes());
+            return used._tag === "Success"
+                ? { ok: true, usedBytes: used.success }
+                : { ok: false, failure: "InvalidStoreSize" };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                failure: error instanceof Error ? error.name : "NonErrorThrown",
+            };
+        }
+    };
+    const readPage = async () => {
+        try {
+            return {
+                ok: true,
+                page: await options.readColdSessions({ limit: patrolPageLimit }),
+            };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                failure: error instanceof Error ? error.name : "NonErrorThrown",
+            };
+        }
+    };
+    return Object.freeze({
+        pending: () => {
+            const store = measureStore();
+            // An unreadable size gives no wake, so the patrol idles until the next
+            // commit asks again; Zookeeper's pressure check refuses admission
+            // meanwhile. `run` reports the failure on any wake that does happen.
+            const over = store.ok && store.usedBytes > waterlineBytes;
+            return { due: false, nextWakeAt: over ? now() + cadenceMs : null };
+        },
+        run: async () => {
+            const store = measureStore();
+            if (!store.ok) {
+                options.report({
+                    status: "unavailable",
+                    source: "store-size",
+                    failure: store.failure,
+                });
+                return;
+            }
+            const { usedBytes } = store;
+            if (usedBytes <= waterlineBytes) {
+                options.report({ status: "quiet", usedBytes, waterlineBytes });
+                return;
+            }
+            const read = await readPage();
+            if (!read.ok) {
+                options.report({
+                    status: "unavailable",
+                    source: "cold-sessions",
+                    failure: read.failure,
+                });
+                return;
+            }
+            const { page } = read;
+            let sessionBytes = 0;
+            let idleBytes = 0;
+            for (const row of page.sessions) {
+                sessionBytes += row.bytes;
+                if (row.idle)
+                    idleBytes += row.bytes;
+            }
+            options.report({
+                status: "measured",
+                usedBytes,
+                waterlineBytes,
+                sessions: page.sessions.length,
+                sessionBytes,
+                idleBytes,
+                more: page.next !== undefined,
+            });
+        },
+    });
+}

package/dist/pressure.d.ts

@@ -0,0 +1,39 @@
+import { type StoragePressureCheck } from "@fungi.computer/shiitake";
+/** A Durable Object's disk budget, with the platform's own measure of it. */
+export type StorageBudget = Readonly<{
+    /**
+     * Bytes the owner database occupies now, read from the platform, such as
+     * Cloudflare's `ctx.storage.sql.databaseSize`.
+     */
+    usedBytes: () => number;
+    /** The host's budget for those bytes. */
+    budgetBytes: number;
+}>;
+/**
+ * A Durable Object's disk quota: 10 GB per object on Cloudflare Workers Paid.
+ * Every Shiitake host measures against it, so the number has one owner.
+ */
+export declare const durableObjectStorageBudgetBytes = 10000000000;
+/** The storage a Cloudflare Durable Object reports its own SQLite size on. */
+export type DurableObjectSizedStorage = Readonly<{
+    sql: Readonly<{
+        databaseSize: number;
+    }>;
+}>;
+/**
+ * The one budget a Durable Object's pressure check and patrol both measure:
+ * the platform's own `databaseSize` against the per-object quota.
+ */
+export declare function durableObjectStorageBudget(storage: DurableObjectSizedStorage): StorageBudget;
+/**
+ * The budget as a positive whole number of bytes. Pressure and the patrol both
+ * measure against it, so a bad budget fails when they open, never later as a
+ * NaN threshold.
+ */
+export declare function checkedBudgetBytes(budget: StorageBudget): number;
+/**
+ * Open the storage-pressure check for Shiitake's `storagePressure` option.
+ * It reports pressure at 80% of the budget and keeps reporting it until
+ * usage falls below 75%.
+ */
+export declare function openStoragePressure(budget: StorageBudget): StoragePressureCheck;

package/dist/pressure.js

@@ -0,0 +1,63 @@
+import { ShiitakeError, } from "@fungi.computer/shiitake";
+import * as Schema from "effect/Schema";
+/**
+ * Provisional disk thresholds, as fractions of the host's budget. At
+ * `refuseAt` new Sessions and new prompts are refused; once refusing, they
+ * are admitted again only below `readmitBelow`, so admission does not flap
+ * while usage hovers at the threshold. The gap is the room the work already
+ * admitted keeps for finishing: its writes never pass through Shiitake's
+ * refusal door.
+ */
+const storagePressureThresholds = Object.freeze({
+    refuseAt: 0.8,
+    readmitBelow: 0.75,
+});
+const decodeBudgetBytes = Schema.decodeUnknownResult(Schema.Int.pipe(Schema.check(Schema.isGreaterThan(0))));
+const decodeUsedBytes = Schema.decodeUnknownResult(Schema.Number.pipe(Schema.check(Schema.isFinite()), Schema.check(Schema.isGreaterThanOrEqualTo(0))));
+/**
+ * A Durable Object's disk quota: 10 GB per object on Cloudflare Workers Paid.
+ * Every Shiitake host measures against it, so the number has one owner.
+ */
+export const durableObjectStorageBudgetBytes = 10_000_000_000;
+/**
+ * The one budget a Durable Object's pressure check and patrol both measure:
+ * the platform's own `databaseSize` against the per-object quota.
+ */
+export function durableObjectStorageBudget(storage) {
+    return {
+        usedBytes: () => storage.sql.databaseSize,
+        budgetBytes: durableObjectStorageBudgetBytes,
+    };
+}
+/**
+ * The budget as a positive whole number of bytes. Pressure and the patrol both
+ * measure against it, so a bad budget fails when they open, never later as a
+ * NaN threshold.
+ */
+export function checkedBudgetBytes(budget) {
+    const budgetBytes = decodeBudgetBytes(budget.budgetBytes);
+    if (budgetBytes._tag === "Failure")
+        throw new ShiitakeError("contract", "invalid", "Storage budget must be a positive whole number of bytes");
+    return budgetBytes.success;
+}
+/**
+ * Open the storage-pressure check for Shiitake's `storagePressure` option.
+ * It reports pressure at 80% of the budget and keeps reporting it until
+ * usage falls below 75%.
+ */
+export function openStoragePressure(budget) {
+    const limit = checkedBudgetBytes(budget);
+    let refusing = false;
+    return Object.freeze({
+        underPressure: () => {
+            const used = decodeUsedBytes(budget.usedBytes());
+            if (used._tag === "Failure")
+                throw new ShiitakeError("store", "unavailable", "Owner storage size is unavailable");
+            const fraction = used.success / limit;
+            refusing = refusing
+                ? fraction >= storagePressureThresholds.readmitBelow
+                : fraction >= storagePressureThresholds.refuseAt;
+            return refusing;
+        },
+    });
+}

package/dist/testing.d.ts

@@ -0,0 +1,4 @@
+import type { ArchiveSource } from "./archive-format.js";
+/** One compaction view whose archive bytes are pinned by the golden test. */
+export declare const goldenSource: ArchiveSource;
+export declare const goldenArchiveText: string;

package/dist/testing.js

@@ -0,0 +1,17 @@
+/** One compaction view whose archive bytes are pinned by the golden test. */
+export const goldenSource = {
+    contextRevision: "row-42",
+    firstKeptEntryId: "entry-9",
+    messagesToSummarize: [
+        { role: "user", content: "héllo \u{1F344}", timestamp: 1 },
+        { role: "user", content: "second", timestamp: 2 },
+    ],
+    turnPrefixMessages: [{ role: "user", content: "prefix", timestamp: 3 }],
+};
+export const goldenArchiveText = [
+    '{"format":"zookeeper.compaction-archive/1","version":1,"contextRevision":"row-42","firstKeptEntryId":"entry-9","counts":{"history":2,"turn_prefix":1}}',
+    '{"section":"history","message":{"role":"user","content":"héllo \u{1F344}","timestamp":1}}',
+    '{"section":"history","message":{"role":"user","content":"second","timestamp":2}}',
+    '{"section":"turn_prefix","message":{"role":"user","content":"prefix","timestamp":3}}',
+    "",
+].join("\n");

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@fungi.computer/zookeeper",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Durable Object store governor: the storage budget and pressure policy behind Shiitake's refusal door",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@fungi.computer/shiitake": "0.3.0",
+    "@noble/hashes": "2.4.0",
+    "effect": "4.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/zookeeper.git"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": {
+        "status": "not-applicable",
+        "reason": "README owns this host-governor contract; no generated documentation site"
+      },
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "scripts": {
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "test": "vitest run --config vitest.config.mjs",
+    "pack": "mkdir -p ../../.botanical/zookeeper-pack && pnpm pack --pack-destination \"$PWD/../../.botanical/zookeeper-pack\"",
+    "smoke": "node test/stranger/runtime.mjs",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. .",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs"
+  }
 }