@tenphi/akno-protocol 0.1.0

package/dist/ops/timeline.d.ts

@@ -0,0 +1,264 @@
+import { z } from 'zod';
+/** Reading is always filtered — a ledger spans years. */
+export declare const TimelineInput: z.ZodObject<{
+    since: z.ZodOptional<z.ZodString>;
+    until: z.ZodOptional<z.ZodString>;
+    match: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodEnum<{
+        document: "document";
+        event: "event";
+        both: "both";
+    }>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    order: z.ZodOptional<z.ZodEnum<{
+        newest: "newest";
+        oldest: "oldest";
+    }>>;
+}, z.core.$strip>;
+export type TimelineInput = z.infer<typeof TimelineInput>;
+export declare const Event: z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    summary: z.ZodString;
+    slug: z.ZodNullable<z.ZodString>;
+    source: z.ZodString;
+    line: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type Event = z.infer<typeof Event>;
+export declare const TimelineEvent: z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    summary: z.ZodString;
+    slug: z.ZodNullable<z.ZodString>;
+    source: z.ZodString;
+    line: z.ZodNullable<z.ZodNumber>;
+    type: z.ZodLiteral<"event">;
+}, z.core.$strip>;
+export type TimelineEvent = z.infer<typeof TimelineEvent>;
+/**
+ * A date evidenced by an unfiled document. It is deliberately not an `Event`:
+ * a date in source material or filesystem metadata is not an authored claim
+ * about what happened.
+ */
+export declare const DocumentTimelineEvidence: z.ZodObject<{
+    type: z.ZodLiteral<"document_evidence">;
+    id: z.ZodString;
+    date: z.ZodString;
+    date_basis: z.ZodEnum<{
+        extracted: "extracted";
+        file_created: "file_created";
+        file_modified: "file_modified";
+    }>;
+    document_id: z.ZodString;
+    path: z.ZodString;
+    label: z.ZodString;
+    mime: z.ZodNullable<z.ZodString>;
+    matched_page: z.ZodOptional<z.ZodNumber>;
+    quote: z.ZodOptional<z.ZodString>;
+    text_source: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            none: "none";
+            original_text: "original_text";
+            ocr_text: "ocr_text";
+            model_description: "model_description";
+        }>;
+        via: z.ZodEnum<{
+            none: "none";
+            plain: "plain";
+            textutil: "textutil";
+            "text-layer": "text-layer";
+            ocr: "ocr";
+            vision: "vision";
+        }>;
+        confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    availability: 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>;
+    suggested_actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        op: z.ZodLiteral<"adopt">;
+        args: z.ZodObject<{
+            documentId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type DocumentTimelineEvidence = z.infer<typeof DocumentTimelineEvidence>;
+export declare const TimelineResult: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    date: z.ZodString;
+    summary: z.ZodString;
+    slug: z.ZodNullable<z.ZodString>;
+    source: z.ZodString;
+    line: z.ZodNullable<z.ZodNumber>;
+    type: z.ZodLiteral<"event">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"document_evidence">;
+    id: z.ZodString;
+    date: z.ZodString;
+    date_basis: z.ZodEnum<{
+        extracted: "extracted";
+        file_created: "file_created";
+        file_modified: "file_modified";
+    }>;
+    document_id: z.ZodString;
+    path: z.ZodString;
+    label: z.ZodString;
+    mime: z.ZodNullable<z.ZodString>;
+    matched_page: z.ZodOptional<z.ZodNumber>;
+    quote: z.ZodOptional<z.ZodString>;
+    text_source: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            none: "none";
+            original_text: "original_text";
+            ocr_text: "ocr_text";
+            model_description: "model_description";
+        }>;
+        via: z.ZodEnum<{
+            none: "none";
+            plain: "plain";
+            textutil: "textutil";
+            "text-layer": "text-layer";
+            ocr: "ocr";
+            vision: "vision";
+        }>;
+        confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    availability: 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>;
+    suggested_actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        op: z.ZodLiteral<"adopt">;
+        args: z.ZodObject<{
+            documentId: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>], "type">;
+export type TimelineResult = z.infer<typeof TimelineResult>;
+export declare function isTimelineEvent(result: TimelineResult): result is TimelineEvent;
+export declare function isDocumentTimelineEvidence(result: TimelineResult): result is DocumentTimelineEvidence;
+export declare const TimelineOutput: 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>;
+    results: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        date: z.ZodString;
+        summary: z.ZodString;
+        slug: z.ZodNullable<z.ZodString>;
+        source: z.ZodString;
+        line: z.ZodNullable<z.ZodNumber>;
+        type: z.ZodLiteral<"event">;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"document_evidence">;
+        id: z.ZodString;
+        date: z.ZodString;
+        date_basis: z.ZodEnum<{
+            extracted: "extracted";
+            file_created: "file_created";
+            file_modified: "file_modified";
+        }>;
+        document_id: z.ZodString;
+        path: z.ZodString;
+        label: z.ZodString;
+        mime: z.ZodNullable<z.ZodString>;
+        matched_page: z.ZodOptional<z.ZodNumber>;
+        quote: z.ZodOptional<z.ZodString>;
+        text_source: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                none: "none";
+                original_text: "original_text";
+                ocr_text: "ocr_text";
+                model_description: "model_description";
+            }>;
+            via: z.ZodEnum<{
+                none: "none";
+                plain: "plain";
+                textutil: "textutil";
+                "text-layer": "text-layer";
+                ocr: "ocr";
+                vision: "vision";
+            }>;
+            confidence: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>>;
+        availability: 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>;
+        suggested_actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            op: z.ZodLiteral<"adopt">;
+            args: z.ZodObject<{
+                documentId: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>], "type">>;
+    total: z.ZodNumber;
+    range: z.ZodObject<{
+        since: z.ZodNullable<z.ZodString>;
+        until: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type TimelineOutput = z.infer<typeof TimelineOutput>;
+//# sourceMappingURL=timeline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/ops/timeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,yDAAyD;AACzD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;iBAUxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,eAAO,MAAM,KAAK;;;;;;;iBAWhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,CAAC,CAAC;AAE1C,eAAO,MAAM,aAAa;;;;;;;;iBAA6C,CAAC;AACxE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAsBnC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAA0E,CAAC;AACtG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,IAAI,aAAa,CAE/E;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,IAAI,wBAAwB,CAErG;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/ops/timeline.js

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { DatePrefix, DocumentAvailability, DocumentTextSource, ResultEnvelope } from "../common.js";
+/** Reading is always filtered — a ledger spans years. */
+export const TimelineInput = z.object({
+    since: DatePrefix.optional(),
+    until: DatePrefix.optional(),
+    match: z.string().optional(),
+    /** A page slug, or an orphan document id/path. */
+    subject: z.string().optional(),
+    /** Restrict results to authored events, orphan document evidence, or both. */
+    source: z.enum(['event', 'document', 'both']).optional(),
+    limit: z.number().int().positive().max(2000).optional(),
+    order: z.enum(['newest', 'oldest']).optional(),
+});
+export const Event = z.object({
+    id: z.string(),
+    date: z.string(),
+    summary: z.string(),
+    /** The page this event links to, when it has one. Plenty of events never will. */
+    slug: z.string().nullable(),
+    /** Where the line lives — `timeline` for the ledger, otherwise the page it was
+     *  written on. Dated lines are indexed from any page, so someone typing events
+     *  into their own daily notes gets them for free. */
+    source: z.string(),
+    line: z.number().int().positive().nullable(),
+});
+export const TimelineEvent = Event.extend({ type: z.literal('event') });
+/**
+ * A date evidenced by an unfiled document. It is deliberately not an `Event`:
+ * a date in source material or filesystem metadata is not an authored claim
+ * about what happened.
+ */
+export const DocumentTimelineEvidence = z.object({
+    type: z.literal('document_evidence'),
+    id: z.string(),
+    date: z.string(),
+    date_basis: z.enum(['extracted', 'file_created', 'file_modified']),
+    document_id: z.string(),
+    path: z.string(),
+    label: z.string(),
+    mime: z.string().nullable(),
+    matched_page: z.number().int().positive().optional(),
+    /** Required for an extracted date; absent when the date is filesystem metadata. */
+    quote: z.string().optional(),
+    text_source: DocumentTextSource.optional(),
+    availability: DocumentAvailability,
+    suggested_actions: z
+        .array(z.object({
+        op: z.literal('adopt'),
+        args: z.object({ documentId: z.string() }),
+    }))
+        .optional(),
+});
+export const TimelineResult = z.discriminatedUnion('type', [TimelineEvent, DocumentTimelineEvidence]);
+export function isTimelineEvent(result) {
+    return result.type === 'event';
+}
+export function isDocumentTimelineEvidence(result) {
+    return result.type === 'document_evidence';
+}
+export const TimelineOutput = ResultEnvelope.extend({
+    /** Authoritative mixed authored-event and document-evidence results. */
+    results: z.array(TimelineResult),
+    total: z.number().int().nonnegative(),
+    /** The window actually read, after defaults were applied. */
+    range: z.object({ since: z.string().nullable(), until: z.string().nullable() }),
+});
+//# sourceMappingURL=timeline.js.map

package/dist/ops/timeline.js.map

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

package/dist/ops/write.d.ts

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+/**
+ * There is no `add_event` op, and nothing about line syntax reaches a
+ * prompt. The caller hands over a date and a summary; Akno formats and files
+ * the ledger line.
+ */
+export declare const EventInput: z.ZodObject<{
+    date: z.ZodString;
+    summary: z.ZodString;
+}, z.core.$strip>;
+export type EventInput = z.infer<typeof EventInput>;
+export declare const DocumentInput: z.ZodObject<{
+    path: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type DocumentInput = z.infer<typeof DocumentInput>;
+/**
+ * Create, append, patch or replace a page. Carries documents, events, tags and
+ * links. A write with only an `event` and no slug appends a ledger line with no
+ * link — still a real line in a real file, addressable as `timeline:47`.
+ */
+export declare const WriteInput: z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    propose_slug: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    content: z.ZodOptional<z.ZodString>;
+    append: z.ZodOptional<z.ZodString>;
+    patch: z.ZodOptional<z.ZodString>;
+    replace: z.ZodOptional<z.ZodObject<{
+        find: z.ZodString;
+        with: z.ZodString;
+    }, z.core.$strip>>;
+    section: z.ZodOptional<z.ZodString>;
+    event: z.ZodOptional<z.ZodObject<{
+        date: z.ZodString;
+        summary: z.ZodString;
+    }, z.core.$strip>>;
+    documents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    links: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dry_run: z.ZodOptional<z.ZodBoolean>;
+    resolve_conflict: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WriteInput = z.infer<typeof WriteInput>;
+export declare const WriteTarget: z.ZodObject<{
+    slug: z.ZodString;
+    line: z.ZodOptional<z.ZodNumber>;
+    action: z.ZodEnum<{
+        event: "event";
+        superseded: "superseded";
+        created: "created";
+        appended: "appended";
+        patched: "patched";
+        replaced: "replaced";
+        attached: "attached";
+    }>;
+}, z.core.$strip>;
+export type WriteTarget = z.infer<typeof WriteTarget>;
+/** A conflict is two live claims on one attribute, surfaced *before* the write. */
+export declare const ConflictReport: z.ZodObject<{
+    slug: z.ZodString;
+    line: z.ZodNumber;
+    existing: z.ZodString;
+    incoming: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    token: z.ZodString;
+}, z.core.$strip>;
+export type ConflictReport = z.infer<typeof ConflictReport>;
+/** A declined proposal is remembered, so the agent stops re-asking. */
+export declare const ApprovalRequest: z.ZodObject<{
+    proposal_id: z.ZodString;
+    reason: z.ZodString;
+    reason_code: z.ZodOptional<z.ZodEnum<{
+        conflict: "conflict";
+        routing_uncertain: "routing_uncertain";
+        no_writable_destination: "no_writable_destination";
+    }>>;
+    nearest: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ApprovalRequest = z.infer<typeof ApprovalRequest>;
+/**
+ * The write named a folder that does not exist and has no rule.
+ *
+ * **Nothing is waiting on the user here** — this is not an approval under another name. It is
+ * the caller being asked to say what the folder is for, with `folder`, and then repeat the
+ * write. The declaration is ungated; only the silence is refused.
+ */
+export declare const FolderRequired: z.ZodObject<{
+    folder: z.ZodString;
+    nearest: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type FolderRequired = z.infer<typeof FolderRequired>;
+export declare const WriteOutput: 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>;
+    outcome: z.ZodEnum<{
+        ok: "ok";
+        requires_approval: "requires_approval";
+        conflict: "conflict";
+        requires_folder: "requires_folder";
+        noop: "noop";
+    }>;
+    change_id: z.ZodOptional<z.ZodString>;
+    wrote: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        slug: z.ZodString;
+        line: z.ZodOptional<z.ZodNumber>;
+        action: z.ZodEnum<{
+            event: "event";
+            superseded: "superseded";
+            created: "created";
+            appended: "appended";
+            patched: "patched";
+            replaced: "replaced";
+            attached: "attached";
+        }>;
+    }, z.core.$strip>>>;
+    facts: z.ZodOptional<z.ZodObject<{
+        retired: z.ZodNumber;
+        added: z.ZodNumber;
+    }, z.core.$strip>>;
+    documents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        rel_path: z.ZodString;
+        text_from: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    conflict: z.ZodOptional<z.ZodObject<{
+        slug: z.ZodString;
+        line: z.ZodNumber;
+        existing: z.ZodString;
+        incoming: z.ZodString;
+        subject: z.ZodOptional<z.ZodString>;
+        token: z.ZodString;
+    }, z.core.$strip>>;
+    approval: z.ZodOptional<z.ZodObject<{
+        proposal_id: z.ZodString;
+        reason: z.ZodString;
+        reason_code: z.ZodOptional<z.ZodEnum<{
+            conflict: "conflict";
+            routing_uncertain: "routing_uncertain";
+            no_writable_destination: "no_writable_destination";
+        }>>;
+        nearest: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    requires_folder: z.ZodOptional<z.ZodObject<{
+        folder: z.ZodString;
+        nearest: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WriteOutput = z.infer<typeof WriteOutput>;
+//# sourceMappingURL=write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/ops/write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;iBAGrB,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,aAAa;;;iBAMxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;iBAqCnB,CAAC;AACL,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAEpD,eAAO,MAAM,WAAW;;;;;;;;;;;;iBAItB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,mFAAmF;AACnF,eAAO,MAAM,cAAc;;;;;;;iBAQzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,uEAAuE;AACvE,eAAO,MAAM,eAAe;;;;;;;;;iBAO1B,CAAC;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;;;;GAMG;AACH,eAAO,MAAM,cAAc;;;iBAKzB,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBActB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC"}

package/dist/ops/write.js

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+import { ResultEnvelope } from "../common.js";
+/**
+ * There is no `add_event` op, and nothing about line syntax reaches a
+ * prompt. The caller hands over a date and a summary; Akno formats and files
+ * the ledger line.
+ */
+export const EventInput = z.object({
+    date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'expected YYYY-MM-DD'),
+    summary: z.string().min(1),
+});
+export const DocumentInput = z.object({
+    /** Path on disk to attach. Stored content-addressed as
+     *  `<page-basename>-<sha8>.<ext>`, so files are unique by construction and
+     *  `label` is a description rather than a disambiguator. */
+    path: z.string(),
+    label: z.string().optional(),
+});
+/**
+ * Create, append, patch or replace a page. Carries documents, events, tags and
+ * links. A write with only an `event` and no slug appends a ledger line with no
+ * link — still a real line in a real file, addressable as `timeline:47`.
+ */
+export const WriteInput = z
+    .object({
+    slug: z.string().optional(),
+    /** Akno proposes the slug when the caller does not; the caller may suggest. */
+    propose_slug: z.string().optional(),
+    title: z.string().optional(),
+    type: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    /** Exactly one body operation. */
+    content: z.string().optional(),
+    append: z.string().optional(),
+    patch: z.string().optional(),
+    replace: z.object({ find: z.string(), with: z.string() }).optional(),
+    /**
+     * Heading to append under, with `append`. The text lands at the end of that section rather
+     * than at the end of the page.
+     *
+     * Matched on the heading's own text, at any level and case-insensitively, so a caller can
+     * say `"Rent"` without knowing whether the page wrote it as `##` or `###`. A heading that
+     * is absent, or that appears more than once, is an error rather than a guess — the same
+     * rule `replace` follows, and for the same reason: the wrong guess edits a part of the page
+     * nobody was looking at.
+     */
+    section: z.string().optional(),
+    event: EventInput.optional(),
+    documents: z.array(DocumentInput).optional(),
+    links: z.array(z.string()).optional(),
+    /** Report what would happen without touching disk. */
+    dry_run: z.boolean().optional(),
+    /** Approve past a conflict the caller has already resolved with the user. */
+    resolve_conflict: z.string().optional(),
+})
+    .refine((v) => Boolean(v.slug || v.propose_slug || v.event), {
+    message: 'write requires a slug, a proposed slug, or an event',
+})
+    .refine((v) => [v.content, v.append, v.patch, v.replace].filter((x) => x !== undefined).length <= 1, {
+    message: 'write takes at most one of: content, append, patch, replace',
+});
+export const WriteTarget = z.object({
+    slug: z.string(),
+    line: z.number().int().positive().optional(),
+    action: z.enum(['created', 'appended', 'patched', 'replaced', 'superseded', 'event', 'attached']),
+});
+/** A conflict is two live claims on one attribute, surfaced *before* the write. */
+export const ConflictReport = z.object({
+    slug: z.string(),
+    line: z.number().int().positive(),
+    existing: z.string(),
+    incoming: z.string(),
+    subject: z.string().optional(),
+    /** Echo this back as `resolve_conflict` to proceed. */
+    token: z.string(),
+});
+/** A declined proposal is remembered, so the agent stops re-asking. */
+export const ApprovalRequest = z.object({
+    proposal_id: z.string(),
+    reason: z.string(),
+    /** Stable caller-facing reason. Older proposal producers may omit it. */
+    reason_code: z.enum(['routing_uncertain', 'no_writable_destination', 'conflict']).optional(),
+    /** Where this could go instead, so the agent has something to offer the user. */
+    nearest: z.array(z.string()),
+});
+/**
+ * The write named a folder that does not exist and has no rule.
+ *
+ * **Nothing is waiting on the user here** — this is not an approval under another name. It is
+ * the caller being asked to say what the folder is for, with `folder`, and then repeat the
+ * write. The declaration is ungated; only the silence is refused.
+ */
+export const FolderRequired = z.object({
+    /** The shallowest undeclared folder on the way to the slug. */
+    folder: z.string(),
+    /** Folders that already exist and might be the intended home, so a new one is a choice. */
+    nearest: z.array(z.string()),
+});
+export const WriteOutput = ResultEnvelope.extend({
+    /** Distinguishes a committed write from one waiting on the user. */
+    outcome: z.enum(['ok', 'requires_approval', 'requires_folder', 'conflict', 'noop']),
+    /** Durable — `undo` takes an id that outlives the session. */
+    change_id: z.string().optional(),
+    wrote: z.array(WriteTarget).optional(),
+    facts: z.object({ retired: z.number().int(), added: z.number().int() }).optional(),
+    /** Attachments stored by this write, content-addressed and extracted. */
+    documents: z
+        .array(z.object({ id: z.string(), rel_path: z.string(), text_from: z.string().optional() }))
+        .optional(),
+    conflict: ConflictReport.optional(),
+    approval: ApprovalRequest.optional(),
+    requires_folder: FolderRequired.optional(),
+});
+//# sourceMappingURL=write.js.map

package/dist/ops/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/ops/write.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;IACpE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC;;gEAE4D;IAC5D,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAGH;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC;KACxB,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,+EAA+E;IAC/E,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,kCAAkC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC7B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpE;;;;;;;;;OASG;IACH,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,KAAK,EAAE,UAAU,CAAC,QAAQ,EAAE;IAC5B,SAAS,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAC5C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrC,sDAAsD;IACtD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC/B,6EAA6E;IAC7E,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACxC,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,KAAK,CAAC,EAAE;IAC3D,OAAO,EAAE,qDAAqD;CAC/D,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,MAAM,IAAI,CAAC,EAAE;IACnG,OAAO,EAAE,6DAA6D;CACvE,CAAC,CAAC;AAGL,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;CAClG,CAAC,CAAC;AAGH,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;IACjC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,uDAAuD;IACvD,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;CAClB,CAAC,CAAC;AAGH,uEAAuE;AACvE,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,yEAAyE;IACzE,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,mBAAmB,EAAE,yBAAyB,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC5F,iFAAiF;IACjF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC7B,CAAC,CAAC;AAGH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,+DAA+D;IAC/D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,2FAA2F;IAC3F,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC7B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC;IAC/C,oEAAoE;IACpE,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IACnF,8DAA8D;IAC9D,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,QAAQ,EAAE;IAClF,yEAAyE;IACzE,SAAS,EAAE,CAAC;SACT,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;SAC3F,QAAQ,EAAE;IACb,QAAQ,EAAE,cAAc,CAAC,QAAQ,EAAE;IACnC,QAAQ,EAAE,eAAe,CAAC,QAAQ,EAAE;IACpC,eAAe,EAAE,cAAc,CAAC,QAAQ,EAAE;CAC3C,CAAC,CAAC"}