@agentdocstore/core 0.2.0

package/dist/search/CoreSearchIndex.js

@@ -0,0 +1,87 @@
+import MiniSearch from 'minisearch';
+const SEARCH_FIELDS = ['title', 'content'];
+const STORE_FIELDS = ['owner', 'visibility', 'expiresAt'];
+const OPTIONS = {
+    idField: 'id',
+    fields: SEARCH_FIELDS,
+    storeFields: STORE_FIELDS,
+    searchOptions: { prefix: true, fuzzy: 0.2, combineWith: 'AND' },
+};
+/**
+ * The default {@link SearchIndex} implementation, backed by MiniSearch. Used by
+ * any provider whose {@link Capabilities.search} is `'core-fallback'`.
+ *
+ * `query` returns PUBLIC hits plus the viewer's own PRIVATE hits — a PRIVATE
+ * doc owned by someone else is never returned.
+ */
+export class CoreSearchIndex {
+    mini;
+    constructor() {
+        this.mini = new MiniSearch(OPTIONS);
+    }
+    add(doc) {
+        // Idempotent: replace any prior doc with the same id.
+        if (this.mini.has(doc.documentId))
+            this.mini.discard(doc.documentId);
+        this.mini.add(toIndexed(doc));
+    }
+    update(doc) {
+        this.add(doc);
+    }
+    remove(documentId) {
+        if (this.mini.has(documentId))
+            this.mini.discard(documentId);
+    }
+    query(q, viewer, opts) {
+        const trimmed = q.trim();
+        if (trimmed.length > 0 && this.mini.dirtCount > 0) {
+            // Replacing or removing a document only marks its old entry as
+            // discarded; MiniSearch drops those entries later, or when a search
+            // meets them. A search that meets one scores the matches it saw before
+            // it as if the discarded entry still counted, which can make scores
+            // negative and put a weaker match first. This throwaway search drops
+            // the discarded entries for these terms, so the one below scores right.
+            this.mini.search(trimmed);
+        }
+        const raw = trimmed.length === 0 ? [] : this.mini.search(trimmed);
+        const now = Date.now();
+        const visible = raw.filter((r) => {
+            const visibility = r['visibility'];
+            const owner = r['owner'];
+            const expiresAt = r['expiresAt'];
+            if (expiresAt !== undefined && Date.parse(expiresAt) <= now)
+                return false;
+            return visibility === 'PUBLIC' || (viewer !== null && owner === viewer);
+        });
+        const total = visible.length;
+        const offset = opts?.offset ?? 0;
+        const limit = opts?.limit ?? 50;
+        const hits = visible
+            .slice(offset, offset + limit)
+            .map((r) => ({ documentId: String(r.id), score: r.score }));
+        return { hits, total };
+    }
+    snapshot() {
+        return JSON.stringify(this.mini);
+    }
+    restore(snapshot) {
+        this.mini = MiniSearch.loadJSON(snapshot, OPTIONS);
+    }
+    clear() {
+        this.mini = new MiniSearch(OPTIONS);
+    }
+    size() {
+        return this.mini.documentCount;
+    }
+}
+function toIndexed(doc) {
+    return {
+        id: doc.documentId,
+        owner: doc.owner,
+        visibility: doc.visibility,
+        title: doc.title,
+        content: doc.content,
+        ...(doc.expiresAt !== undefined ? { expiresAt: doc.expiresAt } : {}),
+    };
+}
+//# sourceMappingURL=CoreSearchIndex.js.map

package/dist/spi/capabilities.d.ts

@@ -0,0 +1,28 @@
+/** How a provider satisfies search. */
+export type SearchCapability = 
+/** Provider has no native search; the core MiniSearch fallback is used. */
+'core-fallback'
+/** Provider implements search natively (e.g. a database full-text index). */
+ | 'native';
+/** Static description of what a {@link Provider} supports. */
+export interface Capabilities {
+    /** Search strategy this provider uses. */
+    readonly search: SearchCapability;
+    /** True if the store expires documents itself; false means the server must sweep. */
+    readonly nativeTtl: boolean;
+    /** True if version appends are committed atomically (content-before-pointer). */
+    readonly atomicVersioning: boolean;
+    /**
+     * True if this provider talks to anything off-box (a database, an object
+     * store, a remote API). Providers MUST declare this honestly: offline mode
+     * refuses to start when a provider reports `true`, and the network fuse would
+     * sever its connections anyway. Only a provider that is entirely local —
+     * in-process memory, or files on this machine — may report `false`.
+     *
+     * A unix-domain socket to a local daemon still counts as `true`: the fuse
+     * permits unix sockets, but the operator deserves to know the store is not
+     * self-contained.
+     */
+    readonly requiresNetwork: boolean;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/spi/capabilities.js

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

package/dist/spi/comments.d.ts

@@ -0,0 +1,14 @@
+import type { Comment } from '../model/comment.js';
+/** Input to add a comment. */
+export interface AddCommentInput {
+    readonly author: string;
+    readonly body: string;
+}
+/** Storage of per-doc comments. */
+export interface CommentStore {
+    add(documentId: string, input: AddCommentInput): Promise<Comment>;
+    list(documentId: string): Promise<readonly Comment[]>;
+    setResolved(documentId: string, commentId: string, resolved: boolean): Promise<Comment>;
+    delete(documentId: string, commentId: string): Promise<void>;
+}
+//# sourceMappingURL=comments.d.ts.map

package/dist/spi/comments.js

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

package/dist/spi/identity.d.ts

@@ -0,0 +1,13 @@
+/** The resolved caller identity. */
+export interface Identity {
+    /** The authenticated user, or the configured single-user default. */
+    readonly user: string;
+}
+/**
+ * Resolves the caller identity from request headers. Implementations are
+ * selected by server auth mode (single-user / trusted-header / token).
+ */
+export interface IdentityProvider {
+    identify(headers: Readonly<Record<string, string | undefined>>): Identity | Promise<Identity>;
+}
+//# sourceMappingURL=identity.d.ts.map

package/dist/spi/identity.js

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

package/dist/spi/index.d.ts

@@ -0,0 +1,8 @@
+export * from './capabilities.js';
+export * from './repository.js';
+export * from './comments.js';
+export * from './search.js';
+export * from './identity.js';
+export * from './provider.js';
+export * from './module.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/spi/index.js

@@ -0,0 +1,8 @@
+export * from './capabilities.js';
+export * from './repository.js';
+export * from './comments.js';
+export * from './search.js';
+export * from './identity.js';
+export * from './provider.js';
+export * from './module.js';
+//# sourceMappingURL=index.js.map

package/dist/spi/module.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The loading contract for a third-party storage backend.
+ *
+ * A provider ships as an ordinary npm package that the operator installs next
+ * to AgentDocStore and names in configuration:
+ *
+ * ```json
+ * { "provider": { "module": "@acme/agentdocstore-provider-postgres",
+ *                 "options": { "url": "postgres://localhost/agentdocstore" } } }
+ * ```
+ *
+ * The package's entry point must satisfy {@link ProviderModule}. It is resolved
+ * from the operator's working directory, NOT from AgentDocStore's own
+ * `node_modules`, so no fork of this repository is required to add a store.
+ */
+import type { Provider } from './provider.js';
+/**
+ * The subset of a schema object the loader needs. Zod's `ZodType` satisfies
+ * this structurally, so a provider may export a zod schema without core taking
+ * a dependency on zod.
+ */
+export interface OptionsSchema {
+    /** Return the validated options, or throw to reject them. */
+    parse(input: unknown): unknown;
+}
+/** The shape a provider package's entry point must export. */
+export interface ProviderModule {
+    /**
+     * Human-readable name, reported at boot and by `agentdocstore doctor`. Use the
+     * store, not the package: `postgres`, `dynamodb`, `s3`.
+     */
+    readonly providerName: string;
+    /**
+     * Optional validator for this provider's `options` block. Supply one: it
+     * turns a mistyped connection string into a readable boot failure instead of
+     * a 500 on first write.
+     */
+    readonly optionsSchema?: OptionsSchema;
+    /**
+     * Construct the provider. Any connection, migration, or handshake work
+     * belongs here — a returned provider is expected to be ready to serve.
+     * Throwing aborts startup with the message shown to the operator.
+     */
+    createProvider(options: unknown): Promise<Provider>;
+}
+/**
+ * Runtime shape check for a dynamically imported module. Kept in core so the
+ * CLI, a fork's own host process, and the conformance kit all reject the same
+ * malformed modules with the same message.
+ */
+export declare function isProviderModule(value: unknown): value is ProviderModule;
+/** Explains precisely which clause of the contract a module failed. */
+export declare function describeProviderModuleDefect(value: unknown): string;
+//# sourceMappingURL=module.d.ts.map

package/dist/spi/module.js

@@ -0,0 +1,57 @@
+/**
+ * The loading contract for a third-party storage backend.
+ *
+ * A provider ships as an ordinary npm package that the operator installs next
+ * to AgentDocStore and names in configuration:
+ *
+ * ```json
+ * { "provider": { "module": "@acme/agentdocstore-provider-postgres",
+ *                 "options": { "url": "postgres://localhost/agentdocstore" } } }
+ * ```
+ *
+ * The package's entry point must satisfy {@link ProviderModule}. It is resolved
+ * from the operator's working directory, NOT from AgentDocStore's own
+ * `node_modules`, so no fork of this repository is required to add a store.
+ */
+/**
+ * Runtime shape check for a dynamically imported module. Kept in core so the
+ * CLI, a fork's own host process, and the conformance kit all reject the same
+ * malformed modules with the same message.
+ */
+export function isProviderModule(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const m = value;
+    if (typeof m.providerName !== 'string' || m.providerName.length === 0)
+        return false;
+    if (typeof m.createProvider !== 'function')
+        return false;
+    if (m.optionsSchema !== undefined &&
+        (typeof m.optionsSchema !== 'object' ||
+            m.optionsSchema === null ||
+            typeof m.optionsSchema.parse !== 'function')) {
+        return false;
+    }
+    return true;
+}
+/** Explains precisely which clause of the contract a module failed. */
+export function describeProviderModuleDefect(value) {
+    if (typeof value !== 'object' || value === null) {
+        return 'module did not export an object';
+    }
+    const m = value;
+    if (typeof m.providerName !== 'string' || m.providerName.length === 0) {
+        return "missing a non-empty 'providerName' export";
+    }
+    if (typeof m.createProvider !== 'function') {
+        return "missing a 'createProvider(options)' export";
+    }
+    if (m.optionsSchema !== undefined) {
+        const s = m.optionsSchema;
+        if (typeof s !== 'object' || s === null || typeof s.parse !== 'function') {
+            return "'optionsSchema' is present but has no parse() method";
+        }
+    }
+    return 'unknown defect';
+}
+//# sourceMappingURL=module.js.map

package/dist/spi/provider.d.ts

@@ -0,0 +1,33 @@
+import type { DocumentRepository } from './repository.js';
+import type { CommentStore } from './comments.js';
+import type { SearchIndex } from './search.js';
+import type { Capabilities } from './capabilities.js';
+/** Result of an optional provider health probe. */
+export interface ProviderHealth {
+    /** False when the backing store is unreachable or refusing work. */
+    readonly healthy: boolean;
+    /** Short human-readable detail, shown by `/healthz` and `agentdocstore doctor`. */
+    readonly detail?: string;
+}
+/**
+ * A storage backend: the composition of a repository, comment store, search
+ * index, and a static capabilities descriptor. Concrete providers
+ * (filesystem, in-memory, or a fork's S3/DDB/Postgres) implement this.
+ */
+export interface Provider {
+    readonly repository: DocumentRepository;
+    readonly comments: CommentStore;
+    readonly search: SearchIndex;
+    readonly capabilities: Capabilities;
+    /**
+     * Optional liveness probe for a store that can be down independently of this
+     * process (a database, an object store). Omit it for a local provider whose
+     * health is implied by successful construction. When present it is surfaced
+     * on `/healthz`, so it MUST be cheap and MUST NOT throw — report
+     * `{ healthy: false, detail }` instead.
+     */
+    healthCheck?(): Promise<ProviderHealth>;
+    /** Release any held resources (locks, file handles, timers). */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/spi/provider.js

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

package/dist/spi/repository.d.ts

@@ -0,0 +1,64 @@
+import type { Document, Language, Visibility } from '../model/document.js';
+import type { DocumentVersion } from '../model/version.js';
+/** Input to create a new doc (with its initial version content). */
+export interface CreateDocumentInput {
+    readonly title: string;
+    readonly language: Language;
+    readonly visibility: Visibility;
+    /** Initial version-1 content. */
+    readonly content: string;
+    readonly createdBy: string;
+    /** Optional ISO-8601 expiry. */
+    readonly expiresAt?: string;
+}
+/** Partial metadata update. `expiresAt: null` clears an existing expiry. */
+export interface UpdateMetaInput {
+    readonly title?: string;
+    readonly language?: Language;
+    readonly expiresAt?: string | null;
+}
+/** Input to append a new immutable version under optimistic concurrency (CAS). */
+export interface AppendVersionInput {
+    readonly content: string;
+    readonly editedBy: string;
+    /** Optional edit note, stored on the new version as `message`. */
+    readonly message?: string;
+    /** CAS guard: the version the caller believes is current. */
+    readonly expect: {
+        readonly latestVersion: number;
+    };
+}
+/** Opaque forward-cursor pagination request. */
+export interface ListQuery {
+    readonly limit?: number;
+    readonly cursor?: string;
+}
+/** A page of results with an optional continuation cursor. */
+export interface Page<T> {
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+}
+/**
+ * Storage of documents and their immutable versions.
+ *
+ * Contract highlights:
+ * - `appendVersion` MUST throw {@link VersionConflictError} when
+ *   `expect.latestVersion` does not match the stored latest (CAS).
+ * - Reads for an unknown OR malformed id return `null`/empty rather than throw.
+ * - Mutations for an unknown id throw {@link NotFoundError}.
+ */
+export interface DocumentRepository {
+    create(input: CreateDocumentInput): Promise<Document>;
+    get(id: string): Promise<Document | null>;
+    getVersion(id: string, version: number): Promise<DocumentVersion | null>;
+    listVersions(id: string): Promise<readonly DocumentVersion[]>;
+    appendVersion(id: string, input: AppendVersionInput): Promise<Document>;
+    updateMeta(id: string, meta: UpdateMetaInput): Promise<Document>;
+    setVisibility(id: string, visibility: Visibility): Promise<Document>;
+    delete(id: string): Promise<void>;
+    /** List documents owned by `owner`, newest first. */
+    listByOwner(owner: string, query?: ListQuery): Promise<Page<Document>>;
+    /** Ids of documents whose `expiresAt` is at or before `nowIso` (sweep target). */
+    listExpired(nowIso: string, limit: number): Promise<readonly string[]>;
+}
+//# sourceMappingURL=repository.d.ts.map

package/dist/spi/repository.js

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

package/dist/spi/search.d.ts

@@ -0,0 +1,53 @@
+import type { Visibility } from '../model/document.js';
+/** A document indexed for search. */
+export interface SearchDoc {
+    readonly documentId: string;
+    readonly owner: string;
+    readonly visibility: Visibility;
+    readonly title: string;
+    readonly content: string;
+    /**
+     * Optional ISO-8601 expiry. An expired entry is excluded from `query` hits
+     * and `total` even before the sweep removes it. Optional so existing index
+     * writers keep working; they simply get no read-time expiry filtering.
+     */
+    readonly expiresAt?: string;
+}
+/** Query pagination options. */
+export interface SearchQueryOptions {
+    readonly limit?: number;
+    readonly offset?: number;
+}
+/** A single search hit. */
+export interface SearchHit {
+    readonly documentId: string;
+    readonly score: number;
+}
+/** Search results with the total number of visible matches (pre-pagination). */
+export interface SearchResults {
+    readonly hits: readonly SearchHit[];
+    readonly total: number;
+}
+/**
+ * Full-text index over documents.
+ *
+ * `query` MUST enforce visibility: it returns PUBLIC hits plus the `viewer`'s
+ * own PRIVATE hits, and nothing else. `snapshot`/`restore` allow a provider to
+ * persist and reload the index (filesystem provider persists a snapshot and
+ * rebuilds it from the store if the snapshot is missing or corrupt).
+ */
+export interface SearchIndex {
+    add(doc: SearchDoc): void;
+    update(doc: SearchDoc): void;
+    remove(documentId: string): void;
+    query(q: string, viewer: string | null, opts?: SearchQueryOptions): SearchResults;
+    /** Serialize the whole index to a string. */
+    snapshot(): string;
+    /** Replace the index contents from a prior {@link snapshot}. */
+    restore(snapshot: string): void;
+    /** Empty the index. */
+    clear(): void;
+    /** Number of indexed documents. */
+    size(): number;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/spi/search.js

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

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@agentdocstore/core",
+  "version": "0.2.0",
+  "description": "AgentDocStore core: domain model, storage provider SPI, authorization, credential scanner and diff engine.",
+  "homepage": "https://github.com/koushikginjupally/agentdocstore/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/koushikginjupally/agentdocstore/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koushikginjupally/agentdocstore.git",
+    "directory": "packages/core"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "agentdocstore",
+    "documents",
+    "storage-provider",
+    "spi"
+  ],
+  "scripts": {
+    "clean": "node ../../scripts/clean.mjs packages/core",
+    "prebuild": "npm run clean",
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "minisearch": "^7.1.0",
+    "nanoid": "^5.0.7",
+    "diff": "^9.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^5.0.0"
+  }
+}