@tenphi/akno-protocol 0.1.0

package/dist/ops/mutate.js

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { ResultEnvelope } from "../common.js";
+import { ApprovalRequest, FolderRequired, WriteTarget } from "./write.js";
+/**
+ * Hand over a transcript or notes; Akno runs the retain mission with its
+ * own model and produces the writes itself. The answer for a host that does not
+ * want to build a curator. An agent that wants control uses `write`.
+ */
+export const RememberInput = z.object({
+    text: z.string().min(1),
+    /** Free-form provenance note, e.g. `telegram:2026-08-06`. */
+    source: z.string().optional(),
+    /**
+     * What to pay attention to in *this* text — attribution for a forwarded message, a channel whose
+     * content is mostly logistics, a subject the caller knows matters.
+     *
+     * **Emphasis, never replacement.** It is appended to the standing retain rules rather than
+     * substituted for them, which is the same guarantee the config missions give: every rule that keeps
+     * this from keeping the wrong things lives in the fixed part, and a caller-supplied prompt that
+     * replaced it would lose all of them at once. A caller that wants full control uses `write`.
+     *
+     * Falls back to `maintenance.retain.mission` when omitted, so an install-wide policy still applies.
+     */
+    mission: z.string().max(2000).optional(),
+    /** Report the candidate writes without touching disk. */
+    dry_run: z.boolean().optional(),
+});
+export const RememberOutput = ResultEnvelope.extend({
+    outcome: z.enum(['ok', 'requires_approval', 'requires_folder', 'no_writable_destination', 'noop']),
+    change_id: z.string().optional(),
+    wrote: z.array(WriteTarget).optional(),
+    facts: z.object({ retired: z.number().int(), added: z.number().int() }).optional(),
+    /** Candidates that cleared the retain mission but had nowhere to go and no name to give one. */
+    approvals: z.array(ApprovalRequest).optional(),
+    /**
+     * Folders a claim wanted and that nothing has described yet. **Not an approval** — declare
+     * each with `folder` and call `remember` again; no user is waiting on this.
+     */
+    requires_folder: z.array(FolderRequired).optional(),
+    /** Present only when a configured fallback was needed by at least one retained claim. */
+    fallback: z
+        .object({
+        slug: z.string(),
+        status: z.enum(['used', 'unavailable']),
+        reason: z
+            .enum(['reserved_path', 'existing_page_not_admitted', 'unindexed_page_exists', 'folder_not_admitted'])
+            .optional(),
+    })
+        .optional(),
+    /** What the retain mission decided was worth keeping, and what it dropped. */
+    considered: z
+        .array(z.object({
+        claim: z.string(),
+        kept: z.boolean(),
+        slug: z.string().nullable(),
+        score: z.number(),
+        /** The authorization class selected before conflict checking and placement. */
+        destination: z
+            .enum([
+            'existing_admitted_page',
+            'new_managed_page',
+            'configured_fallback',
+            'no_writable_destination',
+        ])
+            .optional(),
+        /** True only when this candidate's write actually reached disk. */
+        written: z.boolean(),
+    }))
+        .optional(),
+});
+/**
+ * All three forms operate on Markdown. Retracting a fact removes the
+ * sentence that produced it — expiring a row while the sentence stays in the
+ * file means the assistant "forgets" and reads it again tomorrow.
+ */
+export const ForgetInput = z
+    .object({
+    fact: z.string().optional(),
+    slug: z.string().optional(),
+    document: z.string().optional(),
+})
+    .refine((v) => [v.fact, v.slug, v.document].filter(Boolean).length === 1, {
+    message: 'forget takes exactly one of: fact, slug, document',
+});
+export const ForgetOutput = ResultEnvelope.extend({
+    change_id: z.string().optional(),
+    removed_from: z.string().optional(),
+    /** The exact bytes removed, so the caller can show the user what went. */
+    removed: z.string().optional(),
+    trashed: z.string().optional(),
+});
+export const UndoInput = z.object({ change_id: z.string().min(1) });
+export const UndoOutput = ResultEnvelope.extend({
+    reversed: z.string().optional(),
+    /** Files whose previous content was put back. */
+    restored: z.array(z.string()).optional(),
+    /**
+     * Files the change had created, and which reversing it therefore deleted.
+     *
+     * Separate from `restored` because they are opposite events. Reporting the removal of a
+     * page as "restored" tells the caller a file is there when it is not — and after an
+     * `undo` that is precisely the thing they are about to act on.
+     */
+    removed: z.array(z.string()).optional(),
+});
+/** Relocate a page with its documents, rewriting embeds and reporting inbound links. */
+export const MoveInput = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+});
+export const MoveOutput = ResultEnvelope.extend({
+    outcome: z.enum(['ok', 'requires_folder']),
+    change_id: z.string().optional(),
+    moved: z.array(z.string()).optional(),
+    /** Links that now point nowhere. Reported, never silently rewritten. */
+    broken_inbound: z.array(z.string()).optional(),
+    requires_folder: FolderRequired.optional(),
+});
+/**
+ * Pull documents into memory: extract, OCR, name, summarize, and route.
+ * Extraction happens on arrival, always — no caller ever runs an extraction tool.
+ */
+export const IngestInput = z
+    .object({
+    /** A file, or a folder to walk one level deep. */
+    path: z.string().optional(),
+    /** An http or https URL. Fetched, then treated as a file. */
+    url: z.string().url().optional(),
+    /** Destination folder. Omit to let routing decide. */
+    folder: z.string().optional(),
+    /**
+     * Move the file instead of copying it. The inbox is the only place Akno
+     * moves files, and it sets this by rule — a file dropped straight into
+     * `documents/` was put there on purpose.
+     */
+    route: z.boolean().optional(),
+    label: z.string().optional(),
+    /** Cap for a folder walk, so a wrong path cannot start a thousand model calls. */
+    limit: z.number().int().positive().max(500).optional(),
+})
+    .refine((v) => Boolean(v.path || v.url), { message: 'ingest requires a path or a url' });
+export const IngestOutput = ResultEnvelope.extend({
+    outcome: z.enum(['ok', 'requires_approval', 'requires_folder', 'duplicate', 'skipped']),
+    change_id: z.string().optional(),
+    document: z.string().optional(),
+    slug: z.string().optional(),
+    rel_path: z.string().optional(),
+    summary: z.string().optional(),
+    page_count: z.number().int().nonnegative().optional(),
+    ocr: z.boolean().optional(),
+    /**
+     * Where the text actually came from. `ocr` alone cannot say: a vision model's
+     * *description* of a photo is not a transcription of it, and reporting the two the
+     * same way is a false claim about provenance, which cite-or-stay-quiet exists to
+     * prevent.
+     */
+    text_from: z.enum(['text-layer', 'ocr', 'plain', 'textutil', 'vision', 'none']).optional(),
+    /** Set when a rename fired: the original name added nothing the content did
+     *  not already say. A good name is left alone. */
+    renamed_from: z.string().optional(),
+    related: z.array(z.string()).optional(),
+    /** A document that routed nowhere: a real question for the user about where it goes. */
+    approval: ApprovalRequest.optional(),
+    /** The destination folder has not been declared: a question for the *agent*, not the user. */
+    requires_folder: FolderRequired.optional(),
+    /**
+     * One entry per file when a folder was ingested. The outer `outcome` is `ok` if
+     * anything landed — a folder where three files filed themselves and two need a
+     * decision is not a failure, and collapsing it to one verdict would lose the two.
+     */
+    batch: z
+        .array(z.object({
+        source: z.string(),
+        outcome: z.enum(['ok', 'requires_approval', 'requires_folder', 'duplicate', 'skipped', 'error']),
+        slug: z.string().optional(),
+        note: z.string().optional(),
+    }))
+        .optional(),
+});
+/** Organize one already-indexed orphan document without making retrieval depend on filing. */
+export const AdoptInput = z.object({
+    /** Stable document id returned by recall or read. All parts in the same document group follow it. */
+    documentId: z.string().min(1),
+});
+export const AdoptOutput = ResultEnvelope.extend({
+    outcome: z.enum([
+        'planned',
+        'requires_review',
+        'created',
+        'verification_pending',
+        'noop',
+        'blocked',
+        'rejected',
+        'disabled',
+    ]),
+    document_id: z.string(),
+    /** Every part filed by this operation; a multi-part document is always adopted as one unit. */
+    document_ids: z.array(z.string()).optional(),
+    slug: z.string().optional(),
+    rel_path: z.string().optional(),
+    change_id: z.string().optional(),
+    reason: z.string().optional(),
+    /** Compact reference only; exact private operations remain behind the maintenance-plan interface. */
+    plan: z
+        .object({
+        id: z.string(),
+        mode: z.enum(['audit', 'review', 'auto']),
+        status: z.enum([
+            'ready',
+            'awaiting_review',
+            'deciding',
+            'approved',
+            'applying',
+            'completed',
+            'partially_completed',
+            'failed',
+            'superseded',
+        ]),
+        item_id: z.string(),
+        item_status: z.enum([
+            'proposed',
+            'approved',
+            'rejected',
+            'blocked',
+            'stale',
+            'applying',
+            'applied',
+            'verification_pending',
+            'verification_failed',
+        ]),
+    })
+        .optional(),
+});
+//# sourceMappingURL=mutate.js.map

package/dist/ops/mutate.js.map

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

package/dist/ops/read.d.ts

@@ -0,0 +1,242 @@
+import { z } from 'zod';
+/** One exact thing: a page by slug or id, or a document by id, path or filename. */
+export declare const ReadInput: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    id: z.ZodOptional<z.ZodString>;
+    document: z.ZodOptional<z.ZodString>;
+    from_line: z.ZodOptional<z.ZodNumber>;
+    to_line: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ReadInput = z.infer<typeof ReadInput>;
+export declare const PageBody: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    title: z.ZodString;
+    type: z.ZodNullable<z.ZodString>;
+    tags: z.ZodArray<z.ZodString>;
+    role: z.ZodEnum<{
+        knowledge: "knowledge";
+        source: "source";
+        inference: "inference";
+        ignored: "ignored";
+    }>;
+    management: z.ZodOptional<z.ZodObject<{
+        remember: z.ZodOptional<z.ZodEnum<{
+            deny: "deny";
+            integrate: "integrate";
+        }>>;
+        dream: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            hygiene: "hygiene";
+            synthesize: "synthesize";
+        }>>;
+    }, z.core.$strip>>;
+    about: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    summary: z.ZodNullable<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lines: z.ZodArray<z.ZodObject<{
+        n: z.ZodNumber;
+        text: z.ZodString;
+        confidence: z.ZodOptional<z.ZodNumber>;
+        fact: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    source_fence_line: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    links: z.ZodArray<z.ZodString>;
+    backlinks: z.ZodArray<z.ZodString>;
+    broken_links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    superseded: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        claim: z.ZodString;
+        valid_to: z.ZodString;
+    }, z.core.$strip>>>;
+    documents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        rel_path: z.ZodOptional<z.ZodString>;
+        mime: z.ZodOptional<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+        pages: z.ZodOptional<z.ZodNumber>;
+        parts: z.ZodOptional<z.ZodNumber>;
+        matched_page: z.ZodOptional<z.ZodNumber>;
+        summary: z.ZodOptional<z.ZodString>;
+        quote: z.ZodOptional<z.ZodString>;
+        availability: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                degraded: "degraded";
+                unavailable: "unavailable";
+                available: "available";
+            }>;
+            available_from: z.ZodArray<z.ZodEnum<{
+                original: "original";
+                indexed_text: "indexed_text";
+                rendition: "rendition";
+            }>>;
+            missing_originals: z.ZodArray<z.ZodString>;
+            available_renditions: z.ZodArray<z.ZodString>;
+            missing_since: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    updated: z.ZodOptional<z.ZodString>;
+    bytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PageBody = z.infer<typeof PageBody>;
+export declare const DocumentBody: z.ZodObject<{
+    id: z.ZodString;
+    page: z.ZodNullable<z.ZodString>;
+    rel_path: z.ZodString;
+    mime: z.ZodNullable<z.ZodString>;
+    sha256: z.ZodString;
+    label: z.ZodNullable<z.ZodString>;
+    page_count: z.ZodNullable<z.ZodNumber>;
+    ocr: z.ZodBoolean;
+    text: z.ZodNullable<z.ZodString>;
+    bytes: z.ZodOptional<z.ZodNumber>;
+    availability: z.ZodOptional<z.ZodObject<{
+        status: z.ZodEnum<{
+            degraded: "degraded";
+            unavailable: "unavailable";
+            available: "available";
+        }>;
+        available_from: z.ZodArray<z.ZodEnum<{
+            original: "original";
+            indexed_text: "indexed_text";
+            rendition: "rendition";
+        }>>;
+        missing_originals: z.ZodArray<z.ZodString>;
+        available_renditions: z.ZodArray<z.ZodString>;
+        missing_since: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type DocumentBody = z.infer<typeof DocumentBody>;
+export declare const ReadOutput: z.ZodObject<{
+    status: z.ZodEnum<{
+        ok: "ok";
+        empty: "empty";
+        degraded: "degraded";
+        unavailable: "unavailable";
+    }>;
+    degraded: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        no_embedding_model: "no_embedding_model";
+        no_reranker: "no_reranker";
+        no_derive_model: "no_derive_model";
+        no_expansion_model: "no_expansion_model";
+        embedding_failed: "embedding_failed";
+        rerank_failed: "rerank_failed";
+        derive_failed: "derive_failed";
+        expansion_failed: "expansion_failed";
+        no_vector_index: "no_vector_index";
+        partial_index: "partial_index";
+        no_document_text: "no_document_text";
+        document_source_missing: "document_source_missing";
+        no_graph_index: "no_graph_index";
+        no_entity_index: "no_entity_index";
+        entity_resolution_failed: "entity_resolution_failed";
+        partial_graph_index: "partial_graph_index";
+        graph_traversal_limited: "graph_traversal_limited";
+        no_answer_model: "no_answer_model";
+        answer_failed: "answer_failed";
+        answer_verification_failed: "answer_verification_failed";
+        answer_truncated: "answer_truncated";
+    }>>>;
+    note: z.ZodOptional<z.ZodString>;
+    page: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        title: z.ZodString;
+        type: z.ZodNullable<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        role: z.ZodEnum<{
+            knowledge: "knowledge";
+            source: "source";
+            inference: "inference";
+            ignored: "ignored";
+        }>;
+        management: z.ZodOptional<z.ZodObject<{
+            remember: z.ZodOptional<z.ZodEnum<{
+                deny: "deny";
+                integrate: "integrate";
+            }>>;
+            dream: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                hygiene: "hygiene";
+                synthesize: "synthesize";
+            }>>;
+        }, z.core.$strip>>;
+        about: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        summary: z.ZodNullable<z.ZodString>;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lines: z.ZodArray<z.ZodObject<{
+            n: z.ZodNumber;
+            text: z.ZodString;
+            confidence: z.ZodOptional<z.ZodNumber>;
+            fact: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        source_fence_line: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        links: z.ZodArray<z.ZodString>;
+        backlinks: z.ZodArray<z.ZodString>;
+        broken_links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        superseded: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            claim: z.ZodString;
+            valid_to: z.ZodString;
+        }, z.core.$strip>>>;
+        documents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            rel_path: z.ZodOptional<z.ZodString>;
+            mime: z.ZodOptional<z.ZodString>;
+            label: z.ZodOptional<z.ZodString>;
+            pages: z.ZodOptional<z.ZodNumber>;
+            parts: z.ZodOptional<z.ZodNumber>;
+            matched_page: z.ZodOptional<z.ZodNumber>;
+            summary: z.ZodOptional<z.ZodString>;
+            quote: z.ZodOptional<z.ZodString>;
+            availability: z.ZodOptional<z.ZodObject<{
+                status: z.ZodEnum<{
+                    degraded: "degraded";
+                    unavailable: "unavailable";
+                    available: "available";
+                }>;
+                available_from: z.ZodArray<z.ZodEnum<{
+                    original: "original";
+                    indexed_text: "indexed_text";
+                    rendition: "rendition";
+                }>>;
+                missing_originals: z.ZodArray<z.ZodString>;
+                available_renditions: z.ZodArray<z.ZodString>;
+                missing_since: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        updated: z.ZodOptional<z.ZodString>;
+        bytes: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    document: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        page: z.ZodNullable<z.ZodString>;
+        rel_path: z.ZodString;
+        mime: z.ZodNullable<z.ZodString>;
+        sha256: z.ZodString;
+        label: z.ZodNullable<z.ZodString>;
+        page_count: z.ZodNullable<z.ZodNumber>;
+        ocr: z.ZodBoolean;
+        text: z.ZodNullable<z.ZodString>;
+        bytes: z.ZodOptional<z.ZodNumber>;
+        availability: z.ZodOptional<z.ZodObject<{
+            status: z.ZodEnum<{
+                degraded: "degraded";
+                unavailable: "unavailable";
+                available: "available";
+            }>;
+            available_from: z.ZodArray<z.ZodEnum<{
+                original: "original";
+                indexed_text: "indexed_text";
+                rendition: "rendition";
+            }>>;
+            missing_originals: z.ZodArray<z.ZodString>;
+            available_renditions: z.ZodArray<z.ZodString>;
+            missing_since: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ReadOutput = z.infer<typeof ReadOutput>;
+//# sourceMappingURL=read.d.ts.map

package/dist/ops/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/ops/read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,oFAAoF;AACpF,eAAO,MAAM,SAAS;;;;;;iBAelB,CAAC;AACL,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAElD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;iBAavB,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAExD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAGrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC"}

package/dist/ops/read.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+import { DocumentAvailability, DocumentRef, Line, PageManagement, PageRole, ResultEnvelope, SupersededClaim, } from "../common.js";
+/** One exact thing: a page by slug or id, or a document by id, path or filename. */
+export const ReadInput = z
+    .object({
+    slug: z.string().optional(),
+    id: z.string().optional(),
+    /**
+     * A document id, its path in the knowledge base, or its bare filename — the three handles a
+     * page read hands you, all of which now work. A filename resolves only when it is unique.
+     */
+    document: z.string().optional(),
+    /** Lines to return around a matched region. Whole body when absent. */
+    from_line: z.number().int().positive().optional(),
+    to_line: z.number().int().positive().optional(),
+})
+    .refine((v) => Boolean(v.slug || v.id || v.document), {
+    message: 'read requires one of: slug, id, document',
+});
+export const PageBody = z.object({
+    id: z.string(),
+    slug: z.string(),
+    title: z.string(),
+    type: z.string().nullable(),
+    tags: z.array(z.string()),
+    role: PageRole,
+    management: PageManagement.optional(),
+    about: z.array(z.string()).optional(),
+    aliases: z.array(z.string()).optional(),
+    /** Every frontmatter key Akno found, preserved as read. Your own fields are
+     *  passed through untouched. */
+    frontmatter: z.record(z.string(), z.unknown()),
+    summary: z.string().nullable(),
+    keywords: z.array(z.string()).optional(),
+    /** Numbered so a citation survives being quoted out of context. */
+    lines: z.array(Line),
+    /** Line at which `<!-- source -->` switches a knowledge page to source material. */
+    source_fence_line: z.number().int().positive().nullable().optional(),
+    links: z.array(z.string()),
+    backlinks: z.array(z.string()),
+    broken_links: z.array(z.string()).optional(),
+    superseded: z.array(SupersededClaim).optional(),
+    documents: z.array(DocumentRef).optional(),
+    updated: z.string().optional(),
+    bytes: z.number().int().nonnegative().optional(),
+});
+export const DocumentBody = z.object({
+    id: z.string(),
+    page: z.string().nullable(),
+    rel_path: z.string(),
+    mime: z.string().nullable(),
+    sha256: z.string(),
+    label: z.string().nullable(),
+    page_count: z.number().int().nonnegative().nullable(),
+    ocr: z.boolean(),
+    /** Extracted text. Present because extraction happens on arrival, always. */
+    text: z.string().nullable(),
+    bytes: z.number().int().nonnegative().optional(),
+    availability: DocumentAvailability.optional(),
+});
+export const ReadOutput = ResultEnvelope.extend({
+    page: PageBody.optional(),
+    document: DocumentBody.optional(),
+});
+//# sourceMappingURL=read.js.map

package/dist/ops/read.js.map

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