@hollware/core 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -439,7 +439,7 @@ export declare const DEFAULT_MAX_MARKDOWN_BYTES = 524288;
  */
 export declare const MAX_MARKDOWN_BYTES_CEILING = 786432;
 declare namespace schemas_d_exports {
-  export { acknowledgedWarning, collectionDescription, collectionName, componentDescription, conflict, contractDescription, document, entry, entryId, entryStatus, entrySummary, format, locale, markdown, phase, publication, review, reviewId, reviewStatus, revisionId, severity, siteDescription, slug, verdict, version, violation };
+  export { acknowledgedWarning, collectionDescription, collectionName, componentDescription, conflict, contractDescription, document, entry, entryId, entryStatus, entrySummary, format, locale, markdown, phase, publication, review, reviewComment, reviewId, reviewStatus, revisionId, searchMode, severity, siteDescription, slug, verdict, version, violation };
 }
 /**
  * The pieces the operation schemas share. Their descriptions become the JSON Schema that agents
@@ -694,6 +694,15 @@ declare const review: z.ZodObject<{
   decidedAt: z.ZodNullable<z.ZodString>;
   note: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/** A comment on a review (v0.6), by a person or by the agent of one. */
+declare const reviewComment: z.ZodObject<{
+  id: z.ZodString;
+  author: z.ZodString;
+  authorName: z.ZodNullable<z.ZodString>;
+  client: z.ZodNullable<z.ZodString>;
+  body: z.ZodString;
+  at: z.ZodString;
+}, z.core.$strip>;
 declare const conflict: z.ZodObject<{
   currentVersion: z.ZodNumber;
   headRevision: z.ZodString;
@@ -703,6 +712,12 @@ declare const format: z.ZodEnum<{
   html: "html";
   markdown: "markdown";
 }>;
+/** How a search is made: by its words, by meaning, or both merged (ADR-030). */
+declare const searchMode: z.ZodEnum<{
+  fulltext: "fulltext";
+  hybrid: "hybrid";
+  semantic: "semantic";
+}>;
 declare const componentDescription: z.ZodObject<{
   name: z.ZodString;
   description: z.ZodNullable<z.ZodString>;
@@ -1048,6 +1063,7 @@ export declare class HollwareError extends Error {
 export declare const ID_PREFIXES: {
   readonly challenge: 'chl';
   readonly delivery: 'dlv';
+  readonly embedding: 'emb';
   readonly entry: 'ent';
   readonly event: 'evt';
   readonly invitation: 'inv';
@@ -1057,6 +1073,7 @@ export declare const ID_PREFIXES: {
   readonly revision: 'rev';
   readonly revisionTag: 'tag';
   readonly review: 'rvw';
+  readonly reviewComment: 'rvc';
   readonly schedule: 'sch';
   readonly session: 'ses';
   readonly token: 'tok';
@@ -1238,6 +1255,48 @@ export declare const listEntries: OperationSpec<"list_entries", z.ZodObject<{
   }, z.core.$strip>>;
   nextCursor: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>>;
+export declare const search: OperationSpec<"search", z.ZodObject<{
+  query: z.ZodString;
+  collection: z.ZodOptional<z.ZodString>;
+  locale: z.ZodOptional<z.ZodString>;
+  limit: z.ZodDefault<z.ZodNumber>;
+  mode: z.ZodOptional<z.ZodEnum<{
+    fulltext: "fulltext";
+    hybrid: "hybrid";
+    semantic: "semantic";
+  }>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+  }>;
+  mode: z.ZodEnum<{
+    fulltext: "fulltext";
+    hybrid: "hybrid";
+    semantic: "semantic";
+  }>;
+  results: z.ZodArray<z.ZodObject<{
+    entry: z.ZodObject<{
+      id: z.ZodString;
+      collection: z.ZodString;
+      locale: z.ZodString;
+      slug: z.ZodString;
+      translationGroup: z.ZodNullable<z.ZodString>;
+      status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        scheduled: "scheduled";
+      }>;
+      version: z.ZodNumber;
+      frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      tags: z.ZodArray<z.ZodString>;
+      hasUnpublishedChanges: z.ZodBoolean;
+      publishedAt: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>;
+    snippet: z.ZodString;
+    score: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
 export declare const getEntry: OperationSpec<"get_entry", z.ZodObject<{
   collection: z.ZodString;
   locale: z.ZodString;
@@ -1248,6 +1307,7 @@ export declare const getEntry: OperationSpec<"get_entry", z.ZodObject<{
     markdown: "markdown";
   }>>>;
   published: z.ZodDefault<z.ZodBoolean>;
+  related: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
   outcome: z.ZodEnum<{
     not_found: "not_found";
@@ -1347,6 +1407,24 @@ export declare const getEntry: OperationSpec<"get_entry", z.ZodObject<{
     }, z.core.$strip>>;
     html: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>;
+  related: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>>;
 }, z.core.$strip>>;
 export declare const getTranslations: OperationSpec<"get_translations", z.ZodObject<{
   collection: z.ZodString;
@@ -1704,6 +1782,14 @@ export declare const listReviews: OperationSpec<"list_reviews", z.ZodObject<{
       publishedAt: z.ZodNullable<z.ZodString>;
       updatedAt: z.ZodString;
     }, z.core.$strip>;
+    comments: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      author: z.ZodString;
+      authorName: z.ZodNullable<z.ZodString>;
+      client: z.ZodNullable<z.ZodString>;
+      body: z.ZodString;
+      at: z.ZodString;
+    }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
 export declare const approveReview: OperationSpec<"approve_review", z.ZodObject<{
@@ -1786,6 +1872,109 @@ export declare const approveReview: OperationSpec<"approve_review", z.ZodObject<
     contractsHash: z.ZodString;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
+export declare const requestReview: OperationSpec<"request_review", z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodNumber;
+  acknowledgeWarnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    contract: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    blocked: "blocked";
+    conflict: "conflict";
+    needs_acknowledgement: "needs_acknowledgement";
+    not_found: "not_found";
+    pending_review: "pending_review";
+  }>;
+  entry: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>;
+  verdict: z.ZodOptional<z.ZodObject<{
+    ok: z.ZodBoolean;
+    phase: z.ZodEnum<{
+      publish: "publish";
+      write: "write";
+    }>;
+    errors: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contractsHash: z.ZodString;
+  }, z.core.$strip>>;
+  conflict: z.ZodOptional<z.ZodObject<{
+    currentVersion: z.ZodNumber;
+    headRevision: z.ZodString;
+  }, z.core.$strip>>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+export declare const commentReview: OperationSpec<"comment_review", z.ZodObject<{
+  id: z.ZodString;
+  body: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    commented: "commented";
+    not_found: "not_found";
+    not_pending: "not_pending";
+  }>;
+  comment: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    author: z.ZodString;
+    authorName: z.ZodNullable<z.ZodString>;
+    client: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+    at: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
 export declare const requestChanges: OperationSpec<"request_changes", z.ZodObject<{
   id: z.ZodString;
   note: z.ZodString;
@@ -1813,6 +2002,38 @@ export declare const requestChanges: OperationSpec<"request_changes", z.ZodObjec
     note: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>>;
 }, z.core.$strip>>;
+export declare const contentStats: OperationSpec<"content_stats", z.ZodObject<{
+  days: z.ZodDefault<z.ZodNumber>;
+  limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+    unavailable: "unavailable";
+  }>;
+  since: z.ZodOptional<z.ZodString>;
+  pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    views: z.ZodNumber;
+    entry: z.ZodNullable<z.ZodObject<{
+      id: z.ZodString;
+      collection: z.ZodString;
+      locale: z.ZodString;
+      slug: z.ZodString;
+      translationGroup: z.ZodNullable<z.ZodString>;
+      status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        scheduled: "scheduled";
+      }>;
+      version: z.ZodNumber;
+      frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      tags: z.ZodArray<z.ZodString>;
+      hasUnpublishedChanges: z.ZodBoolean;
+      publishedAt: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
+}, z.core.$strip>>;
 /** Every operation, sorted by name: the order of `tools/list`. */
 export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.ZodObject<{
   id: z.ZodString;
@@ -1893,6 +2114,54 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     }, z.core.$strip>>;
     contractsHash: z.ZodString;
   }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"comment_review", z.ZodObject<{
+  id: z.ZodString;
+  body: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    commented: "commented";
+    not_found: "not_found";
+    not_pending: "not_pending";
+  }>;
+  comment: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    author: z.ZodString;
+    authorName: z.ZodNullable<z.ZodString>;
+    client: z.ZodNullable<z.ZodString>;
+    body: z.ZodString;
+    at: z.ZodString;
+  }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"content_stats", z.ZodObject<{
+  days: z.ZodDefault<z.ZodNumber>;
+  limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+    unavailable: "unavailable";
+  }>;
+  since: z.ZodOptional<z.ZodString>;
+  pages: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    views: z.ZodNumber;
+    entry: z.ZodNullable<z.ZodObject<{
+      id: z.ZodString;
+      collection: z.ZodString;
+      locale: z.ZodString;
+      slug: z.ZodString;
+      translationGroup: z.ZodNullable<z.ZodString>;
+      status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        scheduled: "scheduled";
+      }>;
+      version: z.ZodNumber;
+      frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      tags: z.ZodArray<z.ZodString>;
+      hasUnpublishedChanges: z.ZodBoolean;
+      publishedAt: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>>;
 }, z.core.$strip>>, OperationSpec<"create_draft", z.ZodObject<{
   collection: z.ZodString;
   locale: z.ZodString;
@@ -1999,6 +2268,7 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     markdown: "markdown";
   }>>>;
   published: z.ZodDefault<z.ZodBoolean>;
+  related: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>, z.ZodObject<{
   outcome: z.ZodEnum<{
     not_found: "not_found";
@@ -2098,6 +2368,24 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     }, z.core.$strip>>;
     html: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>>;
+  related: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>>;
 }, z.core.$strip>>, OperationSpec<"get_translations", z.ZodObject<{
   collection: z.ZodString;
   translationGroup: z.ZodString;
@@ -2204,6 +2492,14 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
       publishedAt: z.ZodNullable<z.ZodString>;
       updatedAt: z.ZodString;
     }, z.core.$strip>;
+    comments: z.ZodArray<z.ZodObject<{
+      id: z.ZodString;
+      author: z.ZodString;
+      authorName: z.ZodNullable<z.ZodString>;
+      client: z.ZodNullable<z.ZodString>;
+      body: z.ZodString;
+      at: z.ZodString;
+    }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"publish", z.ZodObject<{
   id: z.ZodString;
@@ -2323,6 +2619,131 @@ export declare const OPERATIONS: readonly [OperationSpec<"approve_review", z.Zod
     decidedAt: z.ZodNullable<z.ZodString>;
     note: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"request_review", z.ZodObject<{
+  id: z.ZodString;
+  version: z.ZodNumber;
+  acknowledgeWarnings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    contract: z.ZodString;
+    path: z.ZodString;
+  }, z.core.$strip>>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    blocked: "blocked";
+    conflict: "conflict";
+    needs_acknowledgement: "needs_acknowledgement";
+    not_found: "not_found";
+    pending_review: "pending_review";
+  }>;
+  entry: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    collection: z.ZodString;
+    locale: z.ZodString;
+    slug: z.ZodString;
+    translationGroup: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+      draft: "draft";
+      published: "published";
+      scheduled: "scheduled";
+    }>;
+    version: z.ZodNumber;
+    frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    tags: z.ZodArray<z.ZodString>;
+    hasUnpublishedChanges: z.ZodBoolean;
+    publishedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>;
+  verdict: z.ZodOptional<z.ZodObject<{
+    ok: z.ZodBoolean;
+    phase: z.ZodEnum<{
+      publish: "publish";
+      write: "write";
+    }>;
+    errors: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    warnings: z.ZodArray<z.ZodObject<{
+      contract: z.ZodString;
+      severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+      }>;
+      path: z.ZodString;
+      message: z.ZodString;
+      fix: z.ZodString;
+      line: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    contractsHash: z.ZodString;
+  }, z.core.$strip>>;
+  conflict: z.ZodOptional<z.ZodObject<{
+    currentVersion: z.ZodNumber;
+    headRevision: z.ZodString;
+  }, z.core.$strip>>;
+  review: z.ZodOptional<z.ZodObject<{
+    id: z.ZodString;
+    entryId: z.ZodString;
+    revision: z.ZodString;
+    status: z.ZodEnum<{
+      approved: "approved";
+      cancelled: "cancelled";
+      changes_requested: "changes_requested";
+      pending: "pending";
+    }>;
+    requestedBy: z.ZodString;
+    requestedByName: z.ZodNullable<z.ZodString>;
+    requestedAt: z.ZodString;
+    decidedBy: z.ZodNullable<z.ZodString>;
+    decidedAt: z.ZodNullable<z.ZodString>;
+    note: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>>, OperationSpec<"search", z.ZodObject<{
+  query: z.ZodString;
+  collection: z.ZodOptional<z.ZodString>;
+  locale: z.ZodOptional<z.ZodString>;
+  limit: z.ZodDefault<z.ZodNumber>;
+  mode: z.ZodOptional<z.ZodEnum<{
+    fulltext: "fulltext";
+    hybrid: "hybrid";
+    semantic: "semantic";
+  }>>;
+}, z.core.$strict>, z.ZodObject<{
+  outcome: z.ZodEnum<{
+    ok: "ok";
+  }>;
+  mode: z.ZodEnum<{
+    fulltext: "fulltext";
+    hybrid: "hybrid";
+    semantic: "semantic";
+  }>;
+  results: z.ZodArray<z.ZodObject<{
+    entry: z.ZodObject<{
+      id: z.ZodString;
+      collection: z.ZodString;
+      locale: z.ZodString;
+      slug: z.ZodString;
+      translationGroup: z.ZodNullable<z.ZodString>;
+      status: z.ZodEnum<{
+        draft: "draft";
+        published: "published";
+        scheduled: "scheduled";
+      }>;
+      version: z.ZodNumber;
+      frontmatter: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      tags: z.ZodArray<z.ZodString>;
+      hasUnpublishedChanges: z.ZodBoolean;
+      publishedAt: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>;
+    snippet: z.ZodString;
+    score: z.ZodNumber;
+  }, z.core.$strip>>;
 }, z.core.$strip>>, OperationSpec<"unpublish", z.ZodObject<{
   id: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
@@ -2516,7 +2937,38 @@ export interface WebhookCheck {
  */
 export declare function verifyWebhook(check: WebhookCheck): Promise<boolean>;
 //#endregion
+//#region src/search/chunks.d.ts
+/**
+ * The pieces of an entry that semantic search embeds (v0.5): one summary, and one piece for each
+ * section the body has under an `h2`. Vectors are derived data, like the Comark document: a change
+ * of this version makes every vector one to make again.
+ */
+export declare const CHUNKER_VERSION = "1";
+interface Chunk {
+  /** The place of the piece in the entry: 0 is the summary, then the sections in order. */
+  readonly index: number;
+  readonly kind: 'summary' | 'section';
+  /** The heading of a section; `null` for the summary. */
+  readonly heading: string | null;
+  readonly text: string;
+}
+/** How long a piece may grow, in characters, before it is cut at a word. */
+export declare const CHUNK_LIMITS: {
+  readonly summary: 1200;
+  readonly section: 2000;
+};
+/**
+ * The pieces of an entry: the summary (its title, its description and the text before the first
+ * `h2`), then each section (its heading and its text up to the next `h2`). An `h1` adds nothing:
+ * it repeats the title. A section with no text is left out.
+ */
+export declare function chunksOf(entry: {
+  readonly title: string;
+  readonly description?: string;
+  readonly document: EntryDocument;
+}): Chunk[];
+//#endregion
 //#region src/index.d.ts
 export declare const name = "@hollware/core";
 //#endregion
-export { type AcknowledgedWarning, type AuthDefinition, type BuiltInContractId, type BuiltInOptions, type CollectionDefinition, type ComponentDefinition, type ComponentUse, type ConfigProblem, type Contract, type ContractContext, type ContractDescription, type ContractFinding, type ContractText, type CustomContractOptions, type DescribedSchema, type DisallowedMarker, type Effect, type EntryDocument, type EntryFacts, type EntryLookup, type EntryRef, type ErrorCode, type ExtractedContent, type Heading, type HollwareConfig, type IdPrefix, type ImageRef, type LinkRef, type LinkTarget, type Operation, type OperationByName, type OperationName, type OperationSpec, type OutcomeInfo, type OutcomeOf, type Phase, type ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, type ResolvedAuth, type ResolvedCollection, type ResolvedConfig, type ResolvedSite, type RunContractsInput, type SchemaOutput, type Scope, type Severity, type SiteDefinition, type SiteDescription, type Verdict, type Violation, schemas_d_exports as schemas };
+export { type AcknowledgedWarning, type AuthDefinition, type BuiltInContractId, type BuiltInOptions, type Chunk, type CollectionDefinition, type ComponentDefinition, type ComponentUse, type ConfigProblem, type Contract, type ContractContext, type ContractDescription, type ContractFinding, type ContractText, type CustomContractOptions, type DescribedSchema, type DisallowedMarker, type Effect, type EntryDocument, type EntryFacts, type EntryLookup, type EntryRef, type ErrorCode, type ExtractedContent, type Heading, type HollwareConfig, type IdPrefix, type ImageRef, type LinkRef, type LinkTarget, type Operation, type OperationByName, type OperationName, type OperationSpec, type OutcomeInfo, type OutcomeOf, type Phase, type ProcessMarkdown, type ProcessMarkdownOptions, type ProcessResult, type ProcessedMarkdown, type RenderHtml, type ResolveConfig, type ResolvedAuth, type ResolvedCollection, type ResolvedConfig, type ResolvedSite, type RunContractsInput, type SchemaOutput, type Scope, type Severity, type SiteDefinition, type SiteDescription, type Verdict, type Violation, schemas_d_exports as schemas };

package/dist/index.mjs

@@ -1702,6 +1702,7 @@ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 const ID_PREFIXES = {
 	challenge: "chl",
 	delivery: "dlv",
+	embedding: "emb",
 	entry: "ent",
 	event: "evt",
 	invitation: "inv",
@@ -1711,6 +1712,7 @@ const ID_PREFIXES = {
 	revision: "rev",
 	revisionTag: "tag",
 	review: "rvw",
+	reviewComment: "rvc",
 	schedule: "sch",
 	session: "ses",
 	token: "tok",
@@ -3049,9 +3051,11 @@ var schemas_exports = /* @__PURE__ */ __exportAll({
 	phase: () => phase,
 	publication: () => publication,
 	review: () => review,
+	reviewComment: () => reviewComment,
 	reviewId: () => reviewId,
 	reviewStatus: () => reviewStatus,
 	revisionId: () => revisionId,
+	searchMode: () => searchMode,
 	severity: () => severity,
 	siteDescription: () => siteDescription,
 	slug: () => slug,
@@ -3153,6 +3157,15 @@ const review = z.object({
 	decidedAt: z.string().nullable(),
 	note: z.string().nullable().describe("What the reviewer asked to change, or null.")
 });
+/** A comment on a review (v0.6), by a person or by the agent of one. */
+const reviewComment = z.object({
+	id: z.string(),
+	author: z.string().describe("The user who wrote it, or whose token their agent used."),
+	authorName: z.string().nullable(),
+	client: z.string().nullable().describe("The name the client gave, such as hollware-agents for the agents; null for none."),
+	body: z.string(),
+	at: z.string()
+});
 const conflict = z.object({
 	currentVersion: z.number().int().min(1),
 	headRevision: revisionId
@@ -3162,6 +3175,12 @@ const format = z.enum([
 	"document",
 	"html"
 ]);
+/** How a search is made: by its words, by meaning, or both merged (ADR-030). */
+const searchMode = z.enum([
+	"fulltext",
+	"semantic",
+	"hybrid"
+]);
 const componentDescription = z.object({
 	name: z.string(),
 	description: z.string().nullable(),
@@ -3240,6 +3259,30 @@ const listEntries = defineOperation({
 	effect: "read",
 	outcomes: { ok: { isError: false } }
 });
+const search = defineOperation({
+	name: "search",
+	title: "Search entries",
+	description: "Searches the published entries of the site, best match first. Full text finds the entries that hold every word of query, in their title, tags and text; semantic finds them by meaning, in any language; hybrid merges both. Narrow it to a collection or a locale. Drafts are not searched: read them with list_entries.",
+	input: z.strictObject({
+		query: z.string().trim().min(1).max(200).describe("The words to find, or a question; punctuation is ignored by full text."),
+		collection: collectionName.optional(),
+		locale: locale.optional(),
+		limit: z.number().int().min(1).max(50).default(10),
+		mode: searchMode.optional().describe("fulltext, semantic or hybrid; hybrid when not given. Semantic and hybrid need the semantic search of the deployment: without it the search is full text, and mode in the answer says so.")
+	}),
+	output: z.object({
+		outcome: z.enum(["ok"]),
+		mode: searchMode.describe("How the search was made."),
+		results: z.array(z.object({
+			entry: entrySummary,
+			snippet: z.string().describe("The words around the match, the words found between [ and ]; for a match by meaning, the start of the closest part."),
+			score: z.number().describe("How well it matches: higher is better.")
+		}))
+	}),
+	scopes: ["content:read"],
+	effect: "read",
+	outcomes: { ok: { isError: false } }
+});
 const getEntry = defineOperation({
 	name: "get_entry",
 	title: "Get an entry",
@@ -3249,11 +3292,13 @@ const getEntry = defineOperation({
 		locale,
 		slug,
 		formats: z.array(format).min(1).default(["markdown"]).describe("What to return of the revision: markdown, the Comark document, or html."),
-		published: z.boolean().default(false).describe("Read the revision that is live instead of the latest one: not_found when the entry is not published.")
+		published: z.boolean().default(false).describe("Read the revision that is live instead of the latest one: not_found when the entry is not published."),
+		related: z.boolean().default(false).describe("Also return the published entries closest to this one by meaning, in its collection and locale, closest first. Needs the semantic search of the deployment; empty without it.")
 	}),
 	output: z.object({
 		outcome: z.enum(["ok", "not_found"]),
-		entry: entry.optional()
+		entry: entry.optional(),
+		related: z.array(entrySummary).optional().describe("When related was asked for.")
 	}),
 	scopes: ["content:read"],
 	effect: "read",
@@ -3420,7 +3465,10 @@ const listReviews = defineOperation({
 	}),
 	output: z.object({
 		outcome: z.enum(["ok"]),
-		reviews: z.array(review.extend({ entry: entrySummary }))
+		reviews: z.array(review.extend({
+			entry: entrySummary,
+			comments: z.array(reviewComment).describe("What was said about it, oldest first.")
+		}))
 	}),
 	scopes: ["content:read"],
 	effect: "read",
@@ -3456,6 +3504,62 @@ const approveReview = defineOperation({
 		not_found: { isError: true }
 	}
 });
+const requestReview = defineOperation({
+	name: "request_review",
+	title: "Ask for a review",
+	description: "Asks a person who may publish to review the latest revision of an entry, after the same checks publish makes, if the entry is still at the version you read. It never publishes, whatever your scopes: the answer is pending_review, or why not (blocked by the contracts, warnings to acknowledge, a conflict). A new revision of the entry cancels the request.",
+	input: z.strictObject({
+		id: entryId,
+		version,
+		acknowledgeWarnings: z.array(acknowledgedWarning).default([]).describe("The warnings you accept, as needs_acknowledgement listed them.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"pending_review",
+			"blocked",
+			"needs_acknowledgement",
+			"conflict",
+			"not_found"
+		]),
+		entry: entrySummary.optional(),
+		verdict: verdict.optional(),
+		conflict: conflict.optional(),
+		review: review.optional().describe("With pending_review: the request, as list_reviews shows it.")
+	}),
+	scopes: ["content:write"],
+	effect: "write",
+	outcomes: {
+		pending_review: { isError: false },
+		blocked: { isError: true },
+		needs_acknowledgement: { isError: false },
+		conflict: { isError: true },
+		not_found: { isError: true }
+	}
+});
+const commentReview = defineOperation({
+	name: "comment_review",
+	title: "Comment on a review",
+	description: "Adds a comment to a pending review, for the person who decides it and for the author: what to change, what reads well, what the contracts cannot check. It neither approves nor closes the review.",
+	input: z.strictObject({
+		id: reviewId,
+		body: z.string().trim().min(1).max(4e3).describe("The comment, in Markdown.")
+	}),
+	output: z.object({
+		outcome: z.enum([
+			"commented",
+			"not_pending",
+			"not_found"
+		]),
+		comment: reviewComment.optional()
+	}),
+	scopes: ["content:write"],
+	effect: "write",
+	outcomes: {
+		commented: { isError: false },
+		not_pending: { isError: true },
+		not_found: { isError: true }
+	}
+});
 const requestChanges = defineOperation({
 	name: "request_changes",
 	title: "Ask for changes",
@@ -3480,9 +3584,35 @@ const requestChanges = defineOperation({
 		not_found: { isError: true }
 	}
 });
+const contentStats = defineOperation({
+	name: "content_stats",
+	title: "Read what readers read",
+	description: "The most read pages of the sites that read this one, over the last days, most read first, each with the published entry it shows when it shows one. Use it to pick what to update. unavailable when the deployment has no analytics.",
+	input: z.strictObject({
+		days: z.number().int().min(1).max(90).default(30).describe("How many days back to count."),
+		limit: z.number().int().min(1).max(50).default(10)
+	}),
+	output: z.object({
+		outcome: z.enum(["ok", "unavailable"]),
+		since: z.string().optional().describe("The start of the count, in ISO 8601."),
+		pages: z.array(z.object({
+			path: z.string(),
+			views: z.number().describe("Page views, sampling accounted for."),
+			entry: entrySummary.nullable().describe("The published entry at that path, or null.")
+		})).optional()
+	}),
+	scopes: ["content:read"],
+	effect: "read",
+	outcomes: {
+		ok: { isError: false },
+		unavailable: { isError: true }
+	}
+});
 /** Every operation, sorted by name: the order of `tools/list`. */
 const OPERATIONS = [
 	approveReview,
+	commentReview,
+	contentStats,
 	createDraft,
 	describeSite,
 	getEntry,
@@ -3491,6 +3621,8 @@ const OPERATIONS = [
 	listReviews,
 	publish,
 	requestChanges,
+	requestReview,
+	search,
 	unpublish,
 	updateDraft,
 	validate
@@ -3607,7 +3739,82 @@ async function verifyWebhook(check) {
 	return sameText(signature, await signWebhook(check.secret, timestamp, check.body));
 }
 //#endregion
+//#region src/search/chunks.ts
+/**
+* The pieces of an entry that semantic search embeds (v0.5): one summary, and one piece for each
+* section the body has under an `h2`. Vectors are derived data, like the Comark document: a change
+* of this version makes every vector one to make again.
+*/
+const CHUNKER_VERSION = "1";
+/** How long a piece may grow, in characters, before it is cut at a word. */
+const CHUNK_LIMITS = {
+	summary: 1200,
+	section: 2e3
+};
+/** The text a reader sees in a node: its strings, never its tag, attributes or comments. */
+function textOf(node) {
+	if (typeof node === "string") return node;
+	if (!Array.isArray(node) || node[0] === null) return "";
+	return node.slice(2).map((child) => textOf(child)).join("");
+}
+function tagOf(node) {
+	return Array.isArray(node) && typeof node[0] === "string" ? node[0] : null;
+}
+/** The words of a text in one line, cut at the last word that fits in `limit`. */
+function fit(text, limit) {
+	const flat = text.replace(/\s+/g, " ").trim();
+	if (flat.length <= limit) return flat;
+	const cut = flat.slice(0, limit);
+	const lastSpace = cut.lastIndexOf(" ");
+	return (lastSpace > 0 ? cut.slice(0, lastSpace) : cut).trim();
+}
+/**
+* The pieces of an entry: the summary (its title, its description and the text before the first
+* `h2`), then each section (its heading and its text up to the next `h2`). An `h1` adds nothing:
+* it repeats the title. A section with no text is left out.
+*/
+function chunksOf(entry) {
+	const intro = [];
+	const sections = [];
+	for (const node of entry.document.nodes) {
+		const tag = tagOf(node);
+		if (tag === "h1") continue;
+		if (tag === "h2") {
+			sections.push({
+				heading: textOf(node).trim(),
+				parts: []
+			});
+			continue;
+		}
+		const text = textOf(node);
+		const current = sections.at(-1);
+		if (current === void 0) intro.push(text);
+		else current.parts.push(text);
+	}
+	const chunks = [{
+		index: 0,
+		kind: "summary",
+		heading: null,
+		text: fit([
+			entry.title,
+			entry.description ?? "",
+			intro.join(" ")
+		].filter((part) => part !== "").join("\n"), CHUNK_LIMITS.summary)
+	}];
+	for (const section of sections) {
+		const body = section.parts.join(" ").trim();
+		if (body === "") continue;
+		chunks.push({
+			index: chunks.length,
+			kind: "section",
+			heading: section.heading,
+			text: fit(`${section.heading}\n${body}`, CHUNK_LIMITS.section)
+		});
+	}
+	return chunks;
+}
+//#endregion
 //#region src/index.ts
 const name = "@hollware/core";
 //#endregion
-export { BUILT_IN_CONTRACT_IDS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, approveReview, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, name, newId, processMarkdown, publish, renderHtml, requestChanges, resolveConfig, runContracts, schemas_exports as schemas, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };
+export { BUILT_IN_CONTRACT_IDS, CHUNKER_VERSION, CHUNK_LIMITS, COMARK_VERSION, ConfigError, DEFAULT_MAX_MARKDOWN_BYTES, ERROR_CODES, EVENT_ID_HEADER, HollwareError, ID_PREFIXES, MAX_MARKDOWN_BYTES_CEILING, OPERATIONS, PERSONAL_TOKEN_PREFIX, PERSONAL_TOKEN_TTL_DAYS, PIPELINE_VERSION, READ_TOKEN_PREFIX, REFUSAL_CONTRACT_IDS, SCOPES, SIGNATURE_HEADER, SITE_KEY_MAX_LENGTH, SITE_KEY_PATTERN, TIMESTAMP_HEADER, approveReview, chunksOf, commentReview, contentStats, contracts, createDraft, defineCollection, defineComponent, defineConfig, defineContract, defineOperation, describeBuiltInContracts, describeContract, describeResolvedSite, describeSite, generatePersonalToken, generateReadToken, getEntry, getTranslations, hashPersonalToken, isBuiltInContract, isId, isPersonalToken, isReadToken, isScope, isSiteKey, listEntries, listReviews, name, newId, processMarkdown, publish, renderHtml, requestChanges, requestReview, resolveConfig, runContracts, schemas_exports as schemas, search, signWebhook, sizeLimitViolation, ulid, uniqueSlugViolation, uniqueTranslationViolation, unpublish, updateDraft, validate, verifyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hollware/core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Contracts, operation specs, schemas and the Markdown pipeline of Hollware. No Cloudflare dependencies.",
   "homepage": "https://hollware.com",
   "bugs": {