@agentproto/corpus 0.1.0-alpha.1

package/dist/ports/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * ClockPort — abstracted time source.
+ *
+ * Tests need deterministic timestamps; production wants Date.now().
+ * Every component that emits `*_at` fields or temporal scores takes
+ * a ClockPort so the same code is testable + real.
+ */
+interface ClockPort {
+    /** Wall-clock now. */
+    now(): Date;
+    /** Current ms since epoch. Equivalent to `now().getTime()`. */
+    nowMs(): number;
+}
+/** Real-time implementation. The local CLI host wires this in. */
+declare const systemClock: ClockPort;
+
+/**
+ * FsPort — filesystem boundary the corpus kit consumes.
+ *
+ * Structural interface, NOT a nominal one — any object exposing this
+ * shape satisfies it. Matches the existing Guilde `WorkspaceFsLike`
+ * convention (projects/guilde/packages/core/src/services/role-source/
+ * workspace.ts:38-47) so cloud and local topologies share the same
+ * minimal contract.
+ *
+ * Paths are relative to the workspace root (no leading slash). The
+ * concrete implementation (MastraFilesystem in cloud, local-fs in CLI,
+ * mcp-filesystem for hybrid topologies) does the resolution.
+ */
+interface FsStat {
+    readonly kind: "file" | "directory";
+    readonly bytes?: number;
+    readonly modifiedAt?: Date;
+}
+interface FsPort {
+    /** True if a file or directory exists at `path`. */
+    exists(path: string): Promise<boolean>;
+    /** Read a file as UTF-8 text. Throws on missing path. */
+    readFile(path: string): Promise<string>;
+    /**
+     * Write a file atomically — caller assumes content is persisted on
+     * resolve. Implementations are expected to write to a temp file +
+     * rename so partial writes never become visible.
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Append to a file. MUST be atomic against concurrent appends to the
+     * same path — used by the event emitter for _log.md. If the file
+     * does not exist, create it.
+     */
+    appendFile(path: string, content: string): Promise<void>;
+    /**
+     * List immediate children of a directory. Returns names only (NOT
+     * full paths). Throws if `path` is not a directory.
+     */
+    readdir(path: string): Promise<readonly string[]>;
+    /**
+     * Recursive directory listing — returns workspace-relative paths of
+     * every file under `path`. Skips directories starting with `.`.
+     */
+    walk(path: string): Promise<readonly string[]>;
+    /** File metadata. Returns null if the path doesn't exist. */
+    stat(path: string): Promise<FsStat | null>;
+    /**
+     * Acquire a cross-process advisory lock on `path`. Used by the
+     * writer for atomic multi-file transactions (entry write + _index
+     * regen + _log append). Implementations MAY no-op for single-process
+     * topologies (local CLI), but cloud hosts MUST enforce real locking.
+     */
+    lock(path: string): Promise<FsLockHandle>;
+}
+interface FsLockHandle {
+    release(): Promise<void>;
+}
+
+/**
+ * IdentityPort — resolves who is currently acting on the corpus.
+ *
+ * Used by the event emitter (attestations) and the access/scope policy
+ * layers (which use the identityTree to match `appliesTo`). Production
+ * Guilde resolves from session; the local CLI resolves from OS user.
+ */
+interface CallerIdentity {
+    /** Stable identity slug. Examples: "operators/sarah", "users/jeremy". */
+    readonly principal: string;
+    /**
+     * Identity tree, most-specific → least-specific. Used by the corpus
+     * scope-policy middleware to match against `appliesTo`. Examples:
+     *
+     *   [
+     *     "ws://operators/sarah",
+     *     "ws://roles/senior-rep",
+     *     "ws://workspaces/sales-na",
+     *     "ws://guilds/acme-sales",
+     *     "ws://orgs/acme-corp",
+     *   ]
+     *
+     * Role hierarchy is resolved here (IdentityPort), not in scope matching.
+     */
+    readonly identityTree: readonly string[];
+    /** Optional display name for `_log.md` attestations. */
+    readonly displayName?: string;
+}
+interface IdentityPort {
+    /** Resolve the current caller. Throws if no identity is in context. */
+    resolve(): Promise<CallerIdentity>;
+}
+
+/**
+ * FetcherPort — the "URL → readable text" boundary the WebImporter
+ * consumes. Keeps the importer PURE and testable: the importer decides
+ * *what* to import (slugging, dedup, candidate shape); the port supplies
+ * the one capability that is environment-bound — fetching and reducing a
+ * URL to text.
+ *
+ * Structural interface, NOT nominal — any object of this shape satisfies
+ * it. Concrete implementations live where the capability lives:
+ *
+ *   - `plugin-local-browser` (agentproto daemon / PTY): tier-1 YouTube
+ *     captions via InnerTube + tier-2 article readability, using the
+ *     user's authenticated browser. This is the rich path.
+ *   - a server-side headless fetcher (Guilde corpus-host): public
+ *     captions + readability only, no user session.
+ *   - a fake (tests): canned { title, text } per URL.
+ *
+ * The port is deliberately strategy-agnostic. A tier-3 Whisper impl
+ * (yt-dlp → ffmpeg → STT) is just a fatter `fetch()` for caption-less
+ * videos — the importer never changes.
+ */
+type FetchedSourceKind = "video" | "article" | "page" | "unknown";
+interface FetchedSource {
+    /** Human-readable title (video/page title or article headline). */
+    readonly title: string;
+    /** Extracted text — a transcript for video, readable body for articles. */
+    readonly text: string;
+    /** What the fetcher determined the URL to be. */
+    readonly kind: FetchedSourceKind;
+    /** BCP-47 language code, when the fetcher can detect it. */
+    readonly language?: string;
+    /** How the text was obtained — for provenance / dedup auditing. */
+    readonly via?: "captions" | "readability" | "transcription" | string;
+}
+interface FetcherPort {
+    /**
+     * Fetch a URL and reduce it to text. Resolves with the extracted
+     * source, or `null` when the URL cannot be reduced to text (e.g. a
+     * caption-less video on a tier that does not transcribe). Returning
+     * `null` lets the importer skip-with-warning rather than abort the
+     * batch; throwing is reserved for hard failures (auth, network).
+     */
+    fetch(url: string): Promise<FetchedSource | null>;
+}
+
+/**
+ * EvaluatorPort — minimal evaluator contract the corpus kit consumes.
+ *
+ * The kit never imports IEvaluator from @agstudio/integration-evaluator
+ * (that's an agstudio type, would break the purity invariant). Instead
+ * it consumes this minimal port; the agstudio side's
+ * `RubricStringEvaluatorAdapter` / `LLMJudgeEvaluatorAdapter` /
+ * `EnsembleEvaluatorAdapter` all satisfy it structurally.
+ *
+ * Matches @agstudio/integration-evaluator IEvaluator shape so cloud
+ * adapters drop in as `EvaluatorPort` instances without conversion.
+ */
+interface EvalRubricPort {
+    readonly slug: string;
+    readonly title: string;
+    readonly version: string;
+    readonly dimensions: readonly {
+        readonly id: string;
+        readonly weight: number;
+        readonly description: string;
+    }[];
+    readonly scoringScale: "0..1" | "0..5";
+    readonly passingThreshold: number;
+    readonly guidance?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface EvalContextPort {
+    readonly operatorRef?: string;
+    readonly conversationId?: string;
+    readonly appliedPlaybooks?: readonly string[];
+    readonly arm?: "shadow" | "baseline" | string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface EvalInputPort {
+    readonly rubric: EvalRubricPort;
+    readonly prompt: string;
+    readonly response: string;
+    readonly context?: EvalContextPort;
+}
+interface EvalResultPort {
+    readonly score: number;
+    readonly dimensions: Readonly<Record<string, number>>;
+    readonly rationale?: string;
+    readonly evaluatorEngineId: string;
+    readonly evaluatorVersion: string;
+    readonly evaluatedAt: string;
+}
+interface EvaluatorPort {
+    evaluate(input: EvalInputPort): Promise<EvalResultPort>;
+}
+
+export { type CallerIdentity, type ClockPort, type EvalContextPort, type EvalInputPort, type EvalResultPort, type EvalRubricPort, type EvaluatorPort, type FetchedSource, type FetchedSourceKind, type FetcherPort, type FsLockHandle, type FsPort, type FsStat, type IdentityPort, systemClock };

package/dist/ports/index.mjs

@@ -0,0 +1,3 @@
+export { systemClock } from '../chunk-KYX2DTEH.mjs';
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/ports/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/dist/sidecar-TTWQD5R3.mjs

@@ -0,0 +1,3 @@
+export { CandidatesSidecar, SidecarDuplicateError, SidecarNotFoundError } from './chunk-UPX26MYH.mjs';
+//# sourceMappingURL=sidecar-TTWQD5R3.mjs.map
+//# sourceMappingURL=sidecar-TTWQD5R3.mjs.map

package/dist/sidecar-TTWQD5R3.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"sidecar-TTWQD5R3.mjs"}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@agentproto/corpus",
+  "version": "0.1.0-alpha.1",
+  "description": "@agentproto/corpus — canonical composition of AIP-10 KNOWLEDGE, AIP-12 PLAYBOOK, AIP-18 COLLECTION, AIP-9 OPERATOR, AIP-15 WORKFLOW, AIP-41 ROUTINE into an autonomous knowledge-improvement system. Pure: zero runtime, zero filesystem, zero HTTP — all I/O via injected ports.",
+  "keywords": [
+    "agentproto",
+    "corpus",
+    "aip-10",
+    "aip-12",
+    "aip-18",
+    "knowledge-base",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/corpus",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/corpus"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./ports": {
+      "types": "./dist/ports/index.d.ts",
+      "import": "./dist/ports/index.mjs",
+      "default": "./dist/ports/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.7.0",
+    "zod": "^4.4.3",
+    "@agentproto/collection": "0.1.0-alpha.1",
+    "@agentproto/playbook": "0.1.0-alpha.1",
+    "@agentproto/knowledge": "0.1.0-alpha.1",
+    "@agentproto/operator": "0.1.0-alpha.1",
+    "@agentproto/routine": "0.1.0-alpha.1",
+    "@agentproto/registry": "0.1.0-alpha.1",
+    "@agentproto/workflow": "0.1.0-alpha.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}