@agentdocstore/core 0.2.0

package/README.md

@@ -0,0 +1,55 @@
+# `@agentdocstore/core`
+
+Domain model and extension contracts for
+[AgentDocStore](https://github.com/koushikginjupally/agentdocstore), an offline-first,
+self-hostable artifact-sharing service.
+
+This package is the stable surface for storage-provider authors. It exports:
+
+- `Provider`, `ProviderModule`, `DocumentRepository`, `CommentStore`, `SearchIndex`
+  and `Capabilities`.
+- Document, version, comment, page and search types.
+- Typed errors including `VersionConflictError`, `NotFoundError`,
+  `ValidationError` and `ContentTooLargeError`.
+- Authorization helpers, id generation/validation, the credential scanner,
+  redaction, the diff engine and the MiniSearch-backed fallback index.
+
+## Install
+
+```bash
+npm install @agentdocstore/core
+```
+
+## Provider module shape
+
+```ts
+import type { ProviderModule } from '@agentdocstore/core';
+
+export const providerName = 'example';
+export const optionsSchema = {
+  parse(value: unknown) {
+    // Validate and return typed options, or throw a helpful error.
+    return value;
+  },
+};
+
+export const createProvider: ProviderModule['createProvider'] = async (options) => {
+  return makeYourProvider(options);
+};
+```
+
+A provider must declare whether it needs a network, implement compare-and-set
+version appends, keep versions immutable, hide private search results, and make
+delete cascade through versions/comments/search. Do not rely on this summary as
+the contract: read the complete [provider SPI guide](../../docs/PROVIDERS.md)
+and prove the implementation with `@agentdocstore/provider-tests`.
+
+## Compatibility
+
+AgentDocStore is pre-1.0. The package follows semantic versioning, but a minor
+release may change the SPI; such changes are called out in the root
+[CHANGELOG](../../CHANGELOG.md).
+
+## License
+
+Apache-2.0.

package/dist/authz.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Authorization helper.
+ *
+ * Enforces the single access rule that governs every doc-scoped surface
+ * (read, raw, update/write, delete, comments):
+ *
+ *   - PUBLIC documents are readable / commentable by anyone (including anonymous).
+ *   - PRIVATE documents are owner-only for ALL surfaces.
+ *   - Mutation (write / delete) is owner-only regardless of visibility.
+ *
+ * Denials throw {@link NotFoundError}, never a "forbidden" error: a non-owner
+ * must not be able to distinguish "exists but you can't touch it" from "does
+ * not exist", so a PRIVATE doc's existence is never disclosed. (There is also
+ * no dedicated Forbidden error in the core taxonomy by design.) The denial
+ * message never contains the owner's identity.
+ */
+import type { Visibility } from './model/document.js';
+/** The caller's identity. `null`/`undefined`/`''` == unauthenticated / anonymous. */
+export type Viewer = string | null | undefined;
+/** The minimal doc projection authorization decisions depend on. */
+export interface AccessTarget {
+    readonly id: string;
+    readonly visibility: Visibility;
+    readonly createdBy: string;
+}
+/** True when `viewer` is the authenticated creator of `doc`. */
+export declare function isOwner(doc: AccessTarget, viewer: Viewer): boolean;
+/** True when `viewer` may view `doc` (and its raw content / comments). */
+export declare function canRead(doc: AccessTarget, viewer: Viewer): boolean;
+/** True when `viewer` may update `doc` (owner-only, any visibility). */
+export declare function canWrite(doc: AccessTarget, viewer: Viewer): boolean;
+/** True when `viewer` may delete `doc` (owner-only, any visibility). */
+export declare function canDelete(doc: AccessTarget, viewer: Viewer): boolean;
+/** True when `viewer` may post/read comments on `doc` (same gate as read). */
+export declare function canComment(doc: AccessTarget, viewer: Viewer): boolean;
+/**
+ * True when `viewer` may delete a comment on `doc`: its author or the document
+ * owner, and only while they can still read the document. Anyone who can read
+ * a PUBLIC document may comment on it, so without this rule any reader could
+ * erase anyone else's feedback.
+ */
+export declare function canDeleteComment(doc: AccessTarget, comment: {
+    readonly author: string;
+}, viewer: Viewer): boolean;
+/**
+ * True when `doc` has an `expiresAt` at or before `now`.
+ *
+ * Expiry is enforced at read time with this check: the background sweep (or a
+ * store's native TTL) only reclaims storage, and may run minutes later — or,
+ * for the stdio MCP server, not at all. An expired document must behave as
+ * deleted from the moment it expires.
+ */
+export declare function isExpired(doc: {
+    readonly expiresAt?: string;
+}, now?: Date): boolean;
+/** Assert `viewer` may read `doc`, else throw {@link NotFoundError}. */
+export declare function assertCanRead(doc: AccessTarget, viewer: Viewer): void;
+/** Assert `viewer` may read `doc`'s raw content (`/raw` is read-gated). */
+export declare function assertCanReadRaw(doc: AccessTarget, viewer: Viewer): void;
+/** Assert `viewer` may update `doc` (owner-only), else throw {@link NotFoundError}. */
+export declare function assertCanWrite(doc: AccessTarget, viewer: Viewer): void;
+/** Assert `viewer` may delete `doc` (owner-only), else throw {@link NotFoundError}. */
+export declare function assertCanDelete(doc: AccessTarget, viewer: Viewer): void;
+/** Assert `viewer` may comment on `doc` (same gate as read), else throw {@link NotFoundError}. */
+export declare function assertCanComment(doc: AccessTarget, viewer: Viewer): void;
+/**
+ * Assert `viewer` may delete `comment` on `doc`. A viewer who cannot read the
+ * document gets the document denial; one who can read it but neither wrote the
+ * comment nor owns the document gets "comment not found", matching how every
+ * other denial is shaped.
+ */
+export declare function assertCanDeleteComment(doc: AccessTarget, comment: {
+    readonly id: string;
+    readonly author: string;
+}, viewer: Viewer): void;
+//# sourceMappingURL=authz.d.ts.map

package/dist/authz.js

@@ -0,0 +1,106 @@
+/**
+ * Authorization helper.
+ *
+ * Enforces the single access rule that governs every doc-scoped surface
+ * (read, raw, update/write, delete, comments):
+ *
+ *   - PUBLIC documents are readable / commentable by anyone (including anonymous).
+ *   - PRIVATE documents are owner-only for ALL surfaces.
+ *   - Mutation (write / delete) is owner-only regardless of visibility.
+ *
+ * Denials throw {@link NotFoundError}, never a "forbidden" error: a non-owner
+ * must not be able to distinguish "exists but you can't touch it" from "does
+ * not exist", so a PRIVATE doc's existence is never disclosed. (There is also
+ * no dedicated Forbidden error in the core taxonomy by design.) The denial
+ * message never contains the owner's identity.
+ */
+import { NotFoundError } from './errors.js';
+/** True when `viewer` is the authenticated creator of `doc`. */
+export function isOwner(doc, viewer) {
+    return typeof viewer === 'string' && viewer.length > 0 && doc.createdBy === viewer;
+}
+/** True when `viewer` may view `doc` (and its raw content / comments). */
+export function canRead(doc, viewer) {
+    return doc.visibility === 'PUBLIC' || isOwner(doc, viewer);
+}
+/** True when `viewer` may update `doc` (owner-only, any visibility). */
+export function canWrite(doc, viewer) {
+    return isOwner(doc, viewer);
+}
+/** True when `viewer` may delete `doc` (owner-only, any visibility). */
+export function canDelete(doc, viewer) {
+    return isOwner(doc, viewer);
+}
+/** True when `viewer` may post/read comments on `doc` (same gate as read). */
+export function canComment(doc, viewer) {
+    return canRead(doc, viewer);
+}
+/**
+ * True when `viewer` may delete a comment on `doc`: its author or the document
+ * owner, and only while they can still read the document. Anyone who can read
+ * a PUBLIC document may comment on it, so without this rule any reader could
+ * erase anyone else's feedback.
+ */
+export function canDeleteComment(doc, comment, viewer) {
+    if (!canComment(doc, viewer))
+        return false;
+    if (isOwner(doc, viewer))
+        return true;
+    return typeof viewer === 'string' && viewer.length > 0 && comment.author === viewer;
+}
+/**
+ * True when `doc` has an `expiresAt` at or before `now`.
+ *
+ * Expiry is enforced at read time with this check: the background sweep (or a
+ * store's native TTL) only reclaims storage, and may run minutes later — or,
+ * for the stdio MCP server, not at all. An expired document must behave as
+ * deleted from the moment it expires.
+ */
+export function isExpired(doc, now = new Date()) {
+    return doc.expiresAt !== undefined && Date.parse(doc.expiresAt) <= now.getTime();
+}
+/**
+ * Uniform denial: throw NotFound with a message that reveals neither the
+ * owner nor whether the doc merely exists.
+ */
+function deny(doc) {
+    throw new NotFoundError(`Document '${doc.id}' not found`);
+}
+/** Assert `viewer` may read `doc`, else throw {@link NotFoundError}. */
+export function assertCanRead(doc, viewer) {
+    if (!canRead(doc, viewer))
+        deny(doc);
+}
+/** Assert `viewer` may read `doc`'s raw content (`/raw` is read-gated). */
+export function assertCanReadRaw(doc, viewer) {
+    if (!canRead(doc, viewer))
+        deny(doc);
+}
+/** Assert `viewer` may update `doc` (owner-only), else throw {@link NotFoundError}. */
+export function assertCanWrite(doc, viewer) {
+    if (!canWrite(doc, viewer))
+        deny(doc);
+}
+/** Assert `viewer` may delete `doc` (owner-only), else throw {@link NotFoundError}. */
+export function assertCanDelete(doc, viewer) {
+    if (!canDelete(doc, viewer))
+        deny(doc);
+}
+/** Assert `viewer` may comment on `doc` (same gate as read), else throw {@link NotFoundError}. */
+export function assertCanComment(doc, viewer) {
+    if (!canComment(doc, viewer))
+        deny(doc);
+}
+/**
+ * Assert `viewer` may delete `comment` on `doc`. A viewer who cannot read the
+ * document gets the document denial; one who can read it but neither wrote the
+ * comment nor owns the document gets "comment not found", matching how every
+ * other denial is shaped.
+ */
+export function assertCanDeleteComment(doc, comment, viewer) {
+    assertCanComment(doc, viewer);
+    if (!canDeleteComment(doc, comment, viewer)) {
+        throw new NotFoundError(`Comment '${comment.id}' not found`);
+    }
+}
+//# sourceMappingURL=authz.js.map

package/dist/diff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Unified-diff generation backed by the `diff` npm package.
+ *
+ * Provides a single function {@link unifiedDiff} that produces a standard
+ * unified diff string from two content strings, with a configurable size cap
+ * to prevent runaway memory use on very large inputs.
+ */
+/** Options for {@link unifiedDiff}. */
+export interface UnifiedDiffOptions {
+    /** Label for the old file in the diff header. */
+    readonly oldLabel?: string;
+    /** Label for the new file in the diff header. */
+    readonly newLabel?: string;
+    /** Number of unchanged context lines around each hunk. */
+    readonly context?: number;
+}
+/**
+ * Produce a unified diff between two content strings.
+ *
+ * Returns an empty string when `oldContent` and `newContent` are identical
+ * (byte-equal). Throws {@link ContentTooLargeError} if either input exceeds
+ * {@link LIMITS.MAX_DIFF_INPUT_BYTES}, or if the diff would add or remove
+ * more than {@link LIMITS.MAX_DIFF_CHANGED_LINES} lines.
+ *
+ * @param oldContent - The original content.
+ * @param newContent - The updated content.
+ * @param opts       - Optional labels and context lines.
+ * @returns A unified diff string, or `''` when inputs are identical.
+ */
+export declare function unifiedDiff(oldContent: string, newContent: string, opts?: UnifiedDiffOptions): string;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.js

@@ -0,0 +1,57 @@
+/**
+ * Unified-diff generation backed by the `diff` npm package.
+ *
+ * Provides a single function {@link unifiedDiff} that produces a standard
+ * unified diff string from two content strings, with a configurable size cap
+ * to prevent runaway memory use on very large inputs.
+ */
+import { createTwoFilesPatch } from 'diff';
+import { ContentTooLargeError } from './errors.js';
+import { LIMITS } from './model/limits.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Produce a unified diff between two content strings.
+ *
+ * Returns an empty string when `oldContent` and `newContent` are identical
+ * (byte-equal). Throws {@link ContentTooLargeError} if either input exceeds
+ * {@link LIMITS.MAX_DIFF_INPUT_BYTES}, or if the diff would add or remove
+ * more than {@link LIMITS.MAX_DIFF_CHANGED_LINES} lines.
+ *
+ * @param oldContent - The original content.
+ * @param newContent - The updated content.
+ * @param opts       - Optional labels and context lines.
+ * @returns A unified diff string, or `''` when inputs are identical.
+ */
+export function unifiedDiff(oldContent, newContent, opts) {
+    // Size guard — measure byte length, not character count.
+    const oldBytes = Buffer.byteLength(oldContent, 'utf8');
+    const newBytes = Buffer.byteLength(newContent, 'utf8');
+    const limit = LIMITS.MAX_DIFF_INPUT_BYTES;
+    if (oldBytes > limit) {
+        throw new ContentTooLargeError(`Old content exceeds diff size limit (${oldBytes} > ${limit} bytes)`, limit, oldBytes);
+    }
+    if (newBytes > limit) {
+        throw new ContentTooLargeError(`New content exceeds diff size limit (${newBytes} > ${limit} bytes)`, limit, newBytes);
+    }
+    // Identical inputs produce no diff.
+    if (oldContent === newContent)
+        return '';
+    const oldLabel = opts?.oldLabel ?? 'a';
+    const newLabel = opts?.newLabel ?? 'b';
+    const context = opts?.context ?? 3;
+    // The search grows with the square of the lines that differ and runs on
+    // the caller's thread, so stop it at the cap rather than let two versions
+    // that share few lines hold the server for minutes.
+    const maxEditLength = LIMITS.MAX_DIFF_CHANGED_LINES;
+    const patch = createTwoFilesPatch(oldLabel, newLabel, oldContent, newContent, '', '', {
+        context,
+        maxEditLength,
+    });
+    if (patch === undefined) {
+        throw new ContentTooLargeError(`Too many changes to diff: more than ${maxEditLength} lines added or removed`, maxEditLength);
+    }
+    return patch;
+}
+//# sourceMappingURL=diff.js.map

package/dist/errors.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Typed core errors. Each carries a discriminant `name` (for `switch (e.name)`)
+ * and a stable machine `code`. `Object.setPrototypeOf` keeps `instanceof`
+ * reliable across the compiled ESM output.
+ */
+export type ErrorCode = 'VERSION_CONFLICT' | 'NOT_FOUND' | 'VALIDATION' | 'CONTENT_TOO_LARGE' | 'OFFLINE_VIOLATION';
+/** Raised by CAS `appendVersion` when `expect.latestVersion` is stale. */
+export declare class VersionConflictError extends Error {
+    readonly expected?: number | undefined;
+    readonly actual?: number | undefined;
+    readonly code: "VERSION_CONFLICT";
+    constructor(message?: string, expected?: number | undefined, actual?: number | undefined);
+}
+/**
+ * Raised when a resource does not exist OR the caller is not permitted to see
+ * it. Authorization deliberately surfaces as NotFound (not Forbidden) so a
+ * PRIVATE doc's existence is never disclosed to a non-owner.
+ */
+export declare class NotFoundError extends Error {
+    readonly code: "NOT_FOUND";
+    constructor(message?: string);
+}
+/** Raised on invalid input (bad language, empty title, oversized field, ...). */
+export declare class ValidationError extends Error {
+    readonly code: "VALIDATION";
+    constructor(message?: string);
+}
+/** Raised when content exceeds a configured size cap (write-time or diff-input). */
+export declare class ContentTooLargeError extends Error {
+    readonly limit?: number | undefined;
+    readonly actual?: number | undefined;
+    readonly code: "CONTENT_TOO_LARGE";
+    constructor(message?: string, limit?: number | undefined, actual?: number | undefined);
+}
+/**
+ * Raised when the configured runtime mode forbids what was asked for — an
+ * offline instance pointed at a networked provider, bound to a non-loopback
+ * address, or a dependency attempting outbound egress through the fuse.
+ */
+export declare class OfflineViolationError extends Error {
+    /** What was attempted, e.g. `provider`, `host`, `connect`, `fetch`. */
+    readonly subject?: string | undefined;
+    /** How the operator can proceed deliberately. */
+    readonly remedy?: string | undefined;
+    readonly code: "OFFLINE_VIOLATION";
+    constructor(message?: string, 
+    /** What was attempted, e.g. `provider`, `host`, `connect`, `fetch`. */
+    subject?: string | undefined, 
+    /** How the operator can proceed deliberately. */
+    remedy?: string | undefined);
+}
+/** Any core error carrying a known {@link ErrorCode}. */
+export type AgentDocStoreError = VersionConflictError | NotFoundError | ValidationError | ContentTooLargeError | OfflineViolationError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,75 @@
+/**
+ * Typed core errors. Each carries a discriminant `name` (for `switch (e.name)`)
+ * and a stable machine `code`. `Object.setPrototypeOf` keeps `instanceof`
+ * reliable across the compiled ESM output.
+ */
+/** Raised by CAS `appendVersion` when `expect.latestVersion` is stale. */
+export class VersionConflictError extends Error {
+    expected;
+    actual;
+    code = 'VERSION_CONFLICT';
+    constructor(message = 'Version conflict', expected, actual) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'VersionConflictError';
+        Object.setPrototypeOf(this, VersionConflictError.prototype);
+    }
+}
+/**
+ * Raised when a resource does not exist OR the caller is not permitted to see
+ * it. Authorization deliberately surfaces as NotFound (not Forbidden) so a
+ * PRIVATE doc's existence is never disclosed to a non-owner.
+ */
+export class NotFoundError extends Error {
+    code = 'NOT_FOUND';
+    constructor(message = 'Not found') {
+        super(message);
+        this.name = 'NotFoundError';
+        Object.setPrototypeOf(this, NotFoundError.prototype);
+    }
+}
+/** Raised on invalid input (bad language, empty title, oversized field, ...). */
+export class ValidationError extends Error {
+    code = 'VALIDATION';
+    constructor(message = 'Validation failed') {
+        super(message);
+        this.name = 'ValidationError';
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+/** Raised when content exceeds a configured size cap (write-time or diff-input). */
+export class ContentTooLargeError extends Error {
+    limit;
+    actual;
+    code = 'CONTENT_TOO_LARGE';
+    constructor(message = 'Content too large', limit, actual) {
+        super(message);
+        this.limit = limit;
+        this.actual = actual;
+        this.name = 'ContentTooLargeError';
+        Object.setPrototypeOf(this, ContentTooLargeError.prototype);
+    }
+}
+/**
+ * Raised when the configured runtime mode forbids what was asked for — an
+ * offline instance pointed at a networked provider, bound to a non-loopback
+ * address, or a dependency attempting outbound egress through the fuse.
+ */
+export class OfflineViolationError extends Error {
+    subject;
+    remedy;
+    code = 'OFFLINE_VIOLATION';
+    constructor(message = 'Offline mode violation', 
+    /** What was attempted, e.g. `provider`, `host`, `connect`, `fetch`. */
+    subject, 
+    /** How the operator can proceed deliberately. */
+    remedy) {
+        super(message);
+        this.subject = subject;
+        this.remedy = remedy;
+        this.name = 'OfflineViolationError';
+        Object.setPrototypeOf(this, OfflineViolationError.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/id.d.ts

@@ -0,0 +1,18 @@
+/**
+ * URL-safe id alphabet. Deliberately excludes `/`, `.`, and whitespace so a
+ * valid id can never encode a path segment or traversal sequence — this is the
+ * primary path-traversal defense used by filesystem-backed providers.
+ */
+export declare const ID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-";
+/** Fixed id length. */
+export declare const ID_LENGTH = 10;
+/** Generate a fresh URL-safe id. */
+export declare function newId(): string;
+/**
+ * Type guard: `true` only for a string that is exactly a well-formed id.
+ * Providers MUST call this before constructing any path from a caller-supplied
+ * id, so values like `..`, `../x`, or `a/b` are rejected before touching the
+ * filesystem.
+ */
+export declare function isValidId(id: unknown): id is string;
+//# sourceMappingURL=id.d.ts.map

package/dist/id.js

@@ -0,0 +1,26 @@
+import { customAlphabet } from 'nanoid';
+/**
+ * URL-safe id alphabet. Deliberately excludes `/`, `.`, and whitespace so a
+ * valid id can never encode a path segment or traversal sequence — this is the
+ * primary path-traversal defense used by filesystem-backed providers.
+ */
+export const ID_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-';
+/** Fixed id length. */
+export const ID_LENGTH = 10;
+const generate = customAlphabet(ID_ALPHABET, ID_LENGTH);
+/** Generate a fresh URL-safe id. */
+export function newId() {
+    return generate();
+}
+/** Matches exactly {@link ID_LENGTH} chars from {@link ID_ALPHABET}. */
+const ID_PATTERN = /^[A-Za-z0-9_-]{10}$/;
+/**
+ * Type guard: `true` only for a string that is exactly a well-formed id.
+ * Providers MUST call this before constructing any path from a caller-supplied
+ * id, so values like `..`, `../x`, or `a/b` are rejected before touching the
+ * filesystem.
+ */
+export function isValidId(id) {
+    return typeof id === 'string' && ID_PATTERN.test(id);
+}
+//# sourceMappingURL=id.js.map

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from './model/document.js';
+export * from './model/version.js';
+export * from './model/comment.js';
+export * from './model/limits.js';
+export * from './model/edit-message.js';
+export * from './model/title.js';
+export * from './errors.js';
+export * from './authz.js';
+export * from './offline.js';
+export * from './id.js';
+export * from './spi/index.js';
+export * from './search/CoreSearchIndex.js';
+export * from './scanner.js';
+export * from './diff.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from './model/document.js';
+export * from './model/version.js';
+export * from './model/comment.js';
+export * from './model/limits.js';
+export * from './model/edit-message.js';
+export * from './model/title.js';
+export * from './errors.js';
+export * from './authz.js';
+export * from './offline.js';
+export * from './id.js';
+export * from './spi/index.js';
+export * from './search/CoreSearchIndex.js';
+export * from './scanner.js';
+export * from './diff.js';
+//# sourceMappingURL=index.js.map

package/dist/model/comment.d.ts

@@ -0,0 +1,18 @@
+/** A comment attached to a {@link Document}. */
+export interface Comment {
+    /** URL-safe comment id. */
+    readonly id: string;
+    /** Owning doc id. */
+    readonly documentId: string;
+    /** Identity that authored the comment. */
+    readonly author: string;
+    /** Comment body text. */
+    body: string;
+    /** Whether the comment has been marked resolved. */
+    resolved: boolean;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    updatedAt: string;
+}
+//# sourceMappingURL=comment.d.ts.map

package/dist/model/comment.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=comment.js.map

package/dist/model/document.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Core domain model for AgentDocStore.
+ *
+ * Only the shapes required by the authorization helper are guaranteed stable
+ * here; the full model (limits, comment, version) is layered in by sibling
+ * modules. `visibility` + `createdBy` are the fields authorization decisions
+ * depend on.
+ */
+/** Per-doc visibility. PUBLIC is the default; PRIVATE is owner-only. */
+export type Visibility = 'PUBLIC' | 'PRIVATE';
+/** Supported content languages / render modes (18). */
+export type Language = 'markdown' | 'mermaid' | 'plaintext' | 'text' | 'javascript' | 'typescript' | 'python' | 'java' | 'go' | 'rust' | 'json' | 'yaml' | 'xml' | 'html' | 'css' | 'sql' | 'bash' | 'dockerfile';
+/** All valid {@link Language} values, for validation and UI enumeration. */
+export declare const LANGUAGES: readonly Language[];
+/** The default visibility applied when a caller does not specify one. */
+export declare const DEFAULT_VISIBILITY: Visibility;
+/**
+ * A stored artifact. Content lives in immutable versions addressed by
+ * {@link Document.latestVersion}; the metadata pointer is what this type describes.
+ */
+export interface Document {
+    /** URL-safe identifier (see id.ts). */
+    readonly id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Content language / render mode. */
+    language: Language;
+    /** Access visibility. */
+    visibility: Visibility;
+    /** Identity of the creator; authoritative owner for authorization. */
+    readonly createdBy: string;
+    /** ISO-8601 creation timestamp. */
+    readonly createdAt: string;
+    /** ISO-8601 last-update timestamp. */
+    updatedAt: string;
+    /** Monotonic latest version number (1-based). */
+    latestVersion: number;
+    /** Optional ISO-8601 expiry (TTL sweep target when the provider lacks native TTL). */
+    expiresAt?: string;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/model/document.js

@@ -0,0 +1,32 @@
+/**
+ * Core domain model for AgentDocStore.
+ *
+ * Only the shapes required by the authorization helper are guaranteed stable
+ * here; the full model (limits, comment, version) is layered in by sibling
+ * modules. `visibility` + `createdBy` are the fields authorization decisions
+ * depend on.
+ */
+/** All valid {@link Language} values, for validation and UI enumeration. */
+export const LANGUAGES = [
+    'markdown',
+    'mermaid',
+    'plaintext',
+    'text',
+    'javascript',
+    'typescript',
+    'python',
+    'java',
+    'go',
+    'rust',
+    'json',
+    'yaml',
+    'xml',
+    'html',
+    'css',
+    'sql',
+    'bash',
+    'dockerfile',
+];
+/** The default visibility applied when a caller does not specify one. */
+export const DEFAULT_VISIBILITY = 'PUBLIC';
+//# sourceMappingURL=document.js.map

package/dist/model/edit-message.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Normalize an editor's note before it is stored on a version: trim it, treat
+ * a blank note as no note, and reject one longer than
+ * {@link LIMITS.MAX_EDIT_MESSAGE_CHARS}. REST and MCP both call this so the
+ * two surfaces store the same thing.
+ */
+export declare function normalizeEditMessage(raw: string | undefined): string | undefined;
+//# sourceMappingURL=edit-message.d.ts.map

package/dist/model/edit-message.js

@@ -0,0 +1,20 @@
+import { ValidationError } from '../errors.js';
+import { LIMITS } from './limits.js';
+/**
+ * Normalize an editor's note before it is stored on a version: trim it, treat
+ * a blank note as no note, and reject one longer than
+ * {@link LIMITS.MAX_EDIT_MESSAGE_CHARS}. REST and MCP both call this so the
+ * two surfaces store the same thing.
+ */
+export function normalizeEditMessage(raw) {
+    if (raw === undefined)
+        return undefined;
+    const message = raw.trim();
+    if (message.length === 0)
+        return undefined;
+    if (message.length > LIMITS.MAX_EDIT_MESSAGE_CHARS) {
+        throw new ValidationError(`Edit message must be at most ${LIMITS.MAX_EDIT_MESSAGE_CHARS} characters`);
+    }
+    return message;
+}
+//# sourceMappingURL=edit-message.js.map