@ferrule-io/ok-fine 0.3.12 → 0.3.14

package/dist/auth/verifier.js

@@ -97,14 +97,7 @@ export class JwtTokenVerifier {
                 }
             }
             if (requiredGroups.length > 0) {
-                const groupsVal = payload[groupsClaim];
-                let tokenGroups = [];
-                if (typeof groupsVal === "string") {
-                    tokenGroups = [groupsVal];
-                }
-                else if (Array.isArray(groupsVal)) {
-                    tokenGroups = groupsVal.filter((g) => typeof g === "string");
-                }
+                const tokenGroups = readGroups(payload[groupsClaim]);
                 const hasRequiredGroup = tokenGroups.some((g) => requiredGroups.includes(g));
                 if (!hasRequiredGroup) {
                     throw new OAuthError(OAuthErrorCode.InsufficientScope, "token not permitted by this server's access policy");
@@ -133,6 +126,7 @@ export class JwtTokenVerifier {
                 break;
             }
         }
+        const groups = readGroups(payload[this.access?.groupsClaim ?? "groups"]);
         return {
             token,
             clientId,
@@ -141,10 +135,19 @@ export class JwtTokenVerifier {
             extra: {
                 sub: typeof payload.sub === "string" ? payload.sub : "unknown",
                 identity,
+                groups,
             },
         };
     }
 }
+/** Normalizes a groups claim, accepted as a string or an array of strings. */
+function readGroups(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((g) => typeof g === "string");
+    return [];
+}
 /**
  * Computes a Principal from an AuthInfo and configured scope names.
  * Hierarchy:
@@ -161,12 +164,15 @@ export function principalFromAuthInfo(info, scopeNames) {
     const canRead = hasRead || hasWrite || hasAdmin;
     const extraSub = info.extra?.sub;
     const extraIdentity = info.extra?.identity;
+    const extraGroups = info.extra?.groups;
     const sub = typeof extraSub === "string" ? extraSub : "unknown";
     const identity = typeof extraIdentity === "string" ? extraIdentity : null;
+    const groups = Array.isArray(extraGroups) ? extraGroups.filter((g) => typeof g === "string") : [];
     return {
         subject: sub,
         clientId: info.clientId,
         identity,
+        groups,
         scopes: info.scopes,
         canRead,
         canWrite,

package/dist/config.js

@@ -1,5 +1,7 @@
+import { readFileSync } from "node:fs";
 import { isIPv4 } from "node:net";
 import { z } from "zod";
+import { PROJECT_RE } from "./okf/paths.js";
 /** A whole-string decimal integer env var (rejects `8080junk`, `1x`, `1.5`, and blanks). */
 function intEnv(name, fallback, min, max = Number.MAX_SAFE_INTEGER) {
     return z
@@ -73,6 +75,10 @@ const storageEnvShape = {
         .default("/data")
         .refine((v) => v.startsWith("/"), "DATA_DIR must be an absolute path"),
     GIT_BRANCH: z.string().default("main"),
+    HUB_PROJECT: z
+        .string()
+        .default("org")
+        .transform((v) => (v.trim() === "" ? "org" : v.trim())),
     GIT_REMOTE_URL: z.string().optional(),
     GIT_SYNC_INTERVAL_SECONDS: intEnv("GIT_SYNC_INTERVAL_SECONDS", "60", 0),
     GIT_SSH_KEY_PATH: z.string().optional(),
@@ -82,7 +88,99 @@ const storageEnvShape = {
     MAX_FILE_BYTES: intEnv("MAX_FILE_BYTES", "1048576", 1),
     MAX_ARCHIVE_BYTES: intEnv("MAX_ARCHIVE_BYTES", "52428800", 1),
     DEFAULT_STALE_AFTER_DAYS: optionalIntEnv("DEFAULT_STALE_AFTER_DAYS", 1, 36500),
+    METRICS_RETENTION_DAYS: intEnv("METRICS_RETENTION_DAYS", "30", 1, 3650),
+    PROJECT_ACCESS: z.string().optional(),
+    PROJECT_ACCESS_FILE: z.string().optional(),
 };
+const projectAccessRuleSchema = z.object({
+    readGroups: z.array(z.string()).default([]),
+    writeGroups: z.array(z.string()).default([]),
+});
+const projectAccessMapSchema = z.record(z.string(), projectAccessRuleSchema);
+function refineProjectAccess(data, ctx) {
+    if (data.PROJECT_ACCESS && data.PROJECT_ACCESS_FILE) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["PROJECT_ACCESS"],
+            message: "PROJECT_ACCESS and PROJECT_ACCESS_FILE cannot both be set",
+        });
+        return;
+    }
+    let jsonStr;
+    let targetPath = "PROJECT_ACCESS";
+    if (data.PROJECT_ACCESS !== undefined && data.PROJECT_ACCESS.trim() !== "") {
+        jsonStr = data.PROJECT_ACCESS;
+        targetPath = "PROJECT_ACCESS";
+    }
+    else if (data.PROJECT_ACCESS_FILE !== undefined && data.PROJECT_ACCESS_FILE.trim() !== "") {
+        targetPath = "PROJECT_ACCESS_FILE";
+        try {
+            jsonStr = readFileSync(data.PROJECT_ACCESS_FILE, "utf-8");
+        }
+        catch (err) {
+            ctx.addIssue({
+                code: "custom",
+                path: ["PROJECT_ACCESS_FILE"],
+                message: `could not read PROJECT_ACCESS_FILE: ${err.message}`,
+            });
+            return;
+        }
+    }
+    if (jsonStr === undefined)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonStr);
+    }
+    catch {
+        ctx.addIssue({
+            code: "custom",
+            path: [targetPath],
+            message: `${targetPath} must be valid JSON`,
+        });
+        return;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        ctx.addIssue({
+            code: "custom",
+            path: [targetPath],
+            message: `${targetPath} must be a JSON object`,
+        });
+        return;
+    }
+    for (const key of Object.keys(parsed)) {
+        if (!PROJECT_RE.test(key)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [targetPath, key],
+                message: `invalid project name "${key}": must match ${PROJECT_RE}`,
+            });
+        }
+    }
+    const result = projectAccessMapSchema.safeParse(parsed);
+    if (!result.success) {
+        for (const issue of result.error.issues) {
+            ctx.addIssue({
+                code: "custom",
+                path: [targetPath, ...issue.path],
+                message: issue.message,
+            });
+        }
+    }
+}
+function parseProjectAccess(projectAccess, projectAccessFile) {
+    let jsonStr;
+    if (projectAccess !== undefined && projectAccess.trim() !== "") {
+        jsonStr = projectAccess;
+    }
+    else if (projectAccessFile !== undefined && projectAccessFile.trim() !== "") {
+        jsonStr = readFileSync(projectAccessFile, "utf-8");
+    }
+    if (!jsonStr)
+        return {};
+    const parsed = JSON.parse(jsonStr);
+    return projectAccessMapSchema.parse(parsed);
+}
 const httpEnvShape = {
     AUTH_MODE: z.enum(["oidc", "none"], "AUTH_MODE must be oidc or none").default("oidc"),
     PORT: intEnv("PORT", "8080", 0, 65535),
@@ -150,6 +248,7 @@ const rawEnvSchema = z.object({ ...httpEnvShape, ...storageEnvShape }).superRefi
     if (!data || typeof data !== "object")
         return;
     refineGitCredentials(data, ctx);
+    refineProjectAccess(data, ctx);
     if (data.AUTH_MODE === "none") {
         const isLoopback = isLoopbackHost(data.HOST ?? "0.0.0.0");
         const allowUnauthenticated = data.ALLOW_UNAUTHENTICATED_NETWORK === "true";
@@ -220,7 +319,10 @@ const rawEnvSchema = z.object({ ...httpEnvShape, ...storageEnvShape }).superRefi
         }
     }
 }, { when: () => true });
-const storageEnvSchema = z.object(storageEnvShape).superRefine(refineGitCredentials, { when: () => true });
+const storageEnvSchema = z
+    .object(storageEnvShape)
+    .superRefine(refineGitCredentials, { when: () => true })
+    .superRefine(refineProjectAccess, { when: () => true });
 function formatConfigError(error) {
     const errorMessages = error.issues.map((issue) => `${issue.path.join(".") || "config"}: ${issue.message}`);
     return new Error(`Configuration errors:\n  ${errorMessages.join("\n  ")}`);
@@ -230,6 +332,7 @@ function storageFromRaw(raw, env, options) {
         logLevel: raw.LOG_LEVEL,
         dataDir: raw.DATA_DIR,
         gitBranch: raw.GIT_BRANCH,
+        hubProject: raw.HUB_PROJECT,
         gitRemoteUrl: raw.GIT_REMOTE_URL,
         gitSyncIntervalSeconds: raw.GIT_SYNC_INTERVAL_SECONDS,
         gitSshKeyPath: raw.GIT_SSH_KEY_PATH,
@@ -244,6 +347,8 @@ function storageFromRaw(raw, env, options) {
         maxFileBytes: raw.MAX_FILE_BYTES,
         maxArchiveBytes: raw.MAX_ARCHIVE_BYTES,
         defaultStaleAfterDays: raw.DEFAULT_STALE_AFTER_DAYS,
+        metricsRetentionDays: raw.METRICS_RETENTION_DAYS,
+        projectAccess: parseProjectAccess(raw.PROJECT_ACCESS, raw.PROJECT_ACCESS_FILE),
     };
 }
 /** Storage-only settings for the stdio transport: needs neither PUBLIC_BASE_URL nor OAUTH_*. */

package/dist/http/metrics.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { METRICS_WINDOWS } from "../metrics/types.js";
+const metricsQuery = z.object({ window: z.enum(METRICS_WINDOWS).default("24h") });
+/** Reads MetricsStore directly: metrics are not knowledge, and the service stays free of database access. */
+export function registerMetricsRoutes(app, metrics) {
+    app.get("/api/v1/metrics", { config: { permission: "read" } }, async (req) => {
+        const { window } = metricsQuery.parse(req.query);
+        return metrics.report(window);
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/http/rest.js

@@ -105,8 +105,24 @@ export function registerRestRoutes(app, service) {
     const write = { permission: "write" };
     const admin = { permission: "admin" };
     app.get("/api/v1/projects", { config: read }, async (req) => {
-        const { repository } = z.object({ repository: z.string().optional() }).parse(req.query);
-        return service.listProjects({ repository });
+        const { repository, team, query } = z
+            .object({
+            repository: z.string().optional(),
+            team: z.string().optional(),
+            query: z.string().optional(),
+        })
+            .parse(req.query);
+        return service.listProjects(principalOf(req), { repository, team, query });
+    });
+    app.get("/api/v1/orient", { config: read }, async (req) => {
+        const { question, project, limit } = z
+            .object({
+            question: z.string().min(1).max(512),
+            project: z.string().optional(),
+            limit: z.coerce.number().int().min(1).max(50).optional(),
+        })
+            .parse(req.query);
+        return service.orient(principalOf(req), { question, project, limit });
     });
     app.post("/api/v1/projects", { config: write }, async (req, reply) => {
         const body = z
@@ -117,7 +133,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/projects/:project", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
-        return service.getProject(project);
+        return service.getProject(principalOf(req), project);
     });
     app.delete("/api/v1/projects/:project", { config: admin }, async (req) => {
         const { project } = projectParams.parse(req.params);
@@ -126,11 +142,11 @@ export function registerRestRoutes(app, service) {
     app.get("/api/v1/projects/:project/index", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
         const { path } = z.object({ path: z.string().optional() }).parse(req.query);
-        return service.getIndex(project, path ?? "");
+        return service.getIndex(principalOf(req), project, path ?? "");
     });
     app.get("/api/v1/projects/:project/concepts/*", { config: read }, async (req, reply) => {
         const { project, "*": id } = wildcardParams.parse(req.params);
-        const concept = withRevision(reply, await service.readConcept(project, id));
+        const concept = withRevision(reply, await service.readConcept(principalOf(req), project, id));
         if ((req.headers.accept ?? "").includes("text/markdown")) {
             return reply.type("text/markdown; charset=utf-8").send(concept.markdown);
         }
@@ -173,7 +189,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/projects/:project/files/*", { config: read }, async (req, reply) => {
         const { project, "*": path } = wildcardParams.parse(req.params);
-        const file = withRevision(reply, await service.readFile(project, path));
+        const file = withRevision(reply, await service.readFile(principalOf(req), project, path));
         const extension = /\.[^./]+$/.exec(path)?.[0].toLowerCase() ?? "";
         return reply.type(CONTENT_TYPE_BY_EXTENSION[extension] ?? "text/plain; charset=utf-8").send(file.content);
     });
@@ -204,19 +220,19 @@ export function registerRestRoutes(app, service) {
         const { id, limit } = z
             .object({ id: z.string().optional(), limit: z.coerce.number().int().min(1).max(100).optional() })
             .parse(req.query);
-        return service.history(project, id, limit);
+        return service.history(principalOf(req), project, id, limit);
     });
     app.get("/api/v1/projects/:project/lint", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
-        return service.lint(project);
+        return service.lint(principalOf(req), project);
     });
     app.get("/api/v1/projects/:project/conflicts", { config: read }, async (req) => {
         const { project } = projectParams.parse(req.params);
-        return service.listConflicts(project);
+        return service.listConflicts(principalOf(req), project);
     });
     app.get("/api/v1/projects/:project/conflicts/:id/files/*", { config: read }, async (req) => {
         const { project, id, "*": path, } = z.object({ project: z.string(), id: z.string(), "*": z.string() }).parse(req.params);
-        return service.readConflict(project, id, path);
+        return service.readConflict(principalOf(req), project, id, path);
     });
     app.post("/api/v1/projects/:project/conflicts/:id/resolution", { config: write }, async (req, reply) => {
         const { project, id } = z.object({ project: z.string(), id: z.string() }).parse(req.params);
@@ -226,7 +242,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/projects/:project/archive", { config: read }, async (req, reply) => {
         const { project } = projectParams.parse(req.params);
-        const stream = await service.exportArchive(project);
+        const stream = service.exportArchive(principalOf(req), project);
         return reply
             .type("application/gzip")
             .header("content-disposition", `attachment; filename="${project}.tar.gz"`)
@@ -241,7 +257,7 @@ export function registerRestRoutes(app, service) {
     });
     app.get("/api/v1/search", { config: read }, async (req) => {
         const q = searchQuery.parse(req.query);
-        return service.search({
+        return service.search(principalOf(req), {
             ...(q.q === undefined ? {} : { query: q.q }),
             ...(q.project === undefined ? {} : { project: q.project }),
             ...(q.type === undefined ? {} : { type: q.type }),

package/dist/local-host.js

@@ -85,6 +85,7 @@ export async function createLocalHost(options) {
                 subject: "local",
                 clientId: "stdio",
                 identity,
+                groups: [],
                 scopes: [],
                 canRead: true,
                 canWrite: true,

package/dist/mcp/server.js

@@ -4,11 +4,11 @@ import { OkfError } from "../errors.js";
 import { TRUST_TIERS } from "../okf/semantics.js";
 import { FEEDBACK_TYPES, feedbackLink } from "../service/feedback.js";
 import { VERSION } from "../version.js";
-export const INSTRUCTIONS = `ok-fine holds shared project knowledge outside the codebase, as OKF v0.2 markdown concepts grouped into projects. In a git repository, first run \`git remote get-url origin\` and call list_projects with that URL as \`repository\`; use the returned project(s) for every read and write. If none match, say the repository is not onboarded and offer to onboard it (ok-fine-onboard skill). Search before planning or editing; record durable decisions, conventions, and runbooks afterwards.
-1. Discover: get_index (progressive disclosure) or search_concepts with \`project\`.
-2. Read: read_concept returns frontmatter, body, trust tier (proposed | unverified | machine-confirmed | human-reviewed), staleness, and links. Freshness comes first: a concept that is stale, when its code sources changed since \`sources[].commit\`, or when that commit is not an ancestor of HEAD (unmerged or rebased away), is a lead to re-check whatever its tier; among fresh concepts prefer higher trust tiers. Knowledge about unmerged work is written at its usual id (e.g. \`decisions/<slug>\`, never over an existing concept) with a \`proposal: { ref: <URI> }\` frontmatter key; such concepts have trust tier \`proposed\` and are not current truth. When one you read has landed in the mainline, rewrite it as current truth without the \`proposal\` key and verify it; when its work was abandoned, set \`status: deprecated\`. Deprecated concepts are history; when code contradicts a concept, trust the code and update the concept.
-3. Write: write_concept with frontmatter containing \`type\` (e.g. Decision, Convention, Architecture, Component, Playbook, Interface, Reference) plus \`title\`, \`description\`, \`tags\`, and \`stale_after\` (ISO 8601, e.g. 180 days ahead). Record provenance in \`sources\` (each with \`resource\` and a stable \`id\`; code sources carry \`commit\`) and cite claims with footnotes [^id]. Link concepts with bundle-absolute links such as [orders](/tables/orders.md). After re-checking a concept against the code, refresh \`sources[].commit\` and \`stale_after\` with write_concept, then call verify_concept.
-4. Pass \`actor\` as <harness>/<model> (e.g. claude-code/claude-opus-4-5, codex/gpt-5-codex, gemini-cli/gemini-2.5-pro). Use human:<email>, with the email from \`git config user.email\`, only when the user personally reviewed the concept; on forbidden_actor, report both identities instead of retrying as another. The server stamps \`generated\`; \`verified\` changes only through verify_concept.
+export const INSTRUCTIONS = `ok-fine holds shared project knowledge outside the codebase, as OKF v0.2 markdown concepts grouped into projects. Project resolution order: 1) A project named explicitly by the user or by harness project/workspace instructions (e.g. Claude Project instructions, a custom GPT's instructions): use it. 2) In a git repository with a remote: call list_projects with \`repository\` set to the remote URL (\`git remote get-url origin\`, falling back to the first remote); use the returned project(s) for every read and write. If none match, say the repository is not onboarded and offer to onboard it (ok-fine-onboard skill). 3) Otherwise (no repository, no shell, or no remote): call orient with your question to rank relevant projects and concepts across the organization, or call list_projects with \`team\` and/or \`query\` (or no arguments). Never run git commands and never say "not onboarded" or offer onboarding on this path. If several fit, read from all; ask before writing only when the write target is ambiguous. Search before planning or editing; record durable decisions, conventions, and runbooks afterwards.
+1. Discover: orient (cross-org ranked discovery with working rules), get_index (progressive disclosure) or search_concepts with \`project\` (omitting \`project\` searches all projects).
+2. Read: read_concept returns frontmatter, body, trust tier (proposed | unverified | machine-confirmed | human-reviewed), staleness, and links. Freshness comes first: a concept that is stale is a lead to re-check whatever its tier. For concepts with code sources, that means when code changed since \`sources[].commit\` or that commit is not an ancestor of HEAD (unmerged or rebased away); for concepts without code sources, fresh means \`stale_after\` is set and not past (additionally, when a tool available in the session can fetch a source's \`resource\` URL and report its last-modified time, a source modified after \`generated.at\` counts as drifted). Among fresh concepts prefer higher trust tiers. Knowledge about unmerged work is written at its usual id (e.g. \`decisions/<slug>\`, never over an existing concept) with a \`proposal: { ref: <URI> }\` frontmatter key; such concepts have trust tier \`proposed\` and are not current truth. When one you read has landed in the mainline, rewrite it as current truth without the \`proposal\` key and verify it; when its work was abandoned, set \`status: deprecated\`. Deprecated concepts are history; when code contradicts a concept, trust the code and update the concept.
+3. Write: write_concept with frontmatter containing \`type\` (e.g. Decision, Convention, Architecture, Component, Playbook, Interface, Reference) plus \`title\`, \`description\`, \`tags\`, and \`stale_after\` (ISO 8601, e.g. 180 days ahead). Record provenance in \`sources\` (each with \`resource\` and a stable \`id\`; code sources carry \`commit\`; non-code sources use a URL or stable URI \`resource\` without \`commit\`) and cite claims with footnotes [^id]. Link concepts with bundle-absolute links such as [orders](/tables/orders.md). After re-checking a concept against the code or sources, refresh \`sources[].commit\` and \`stale_after\` with write_concept, then call verify_concept.
+4. Pass \`actor\` as <harness>/<model> (e.g. claude-code/claude-opus-4-5, claude-desktop/<model>, claude-ai/<model>, chatgpt/<model>, gemini-cli/gemini-2.5-pro). Use human:<email>, with the email from \`git config user.email\` in a repository or the email confirmed by the user outside one, only when the user personally reviewed the concept; on forbidden_actor, report both identities instead of retrying as another. The server stamps \`generated\`; \`verified\` changes only through verify_concept.
 5. When updating, pass expectedRevision from read_concept (null to create only).
 6. An \`unresolved_conflict\` issue (lint_project, read_concept) is a write ok-fine accepted but could not merge with a concurrent edit from another ok-fine instance. Before editing the affected file: read_conflict, merge \`preserved\` into \`current\` (use \`base\` to see what each side changed), write the result with expectedRevision set to \`current.revision\`, then call resolve_conflict with every file path of the conflict. Resolve only conflicts of the project you are working in.
 7. Prefer \`status: deprecated\` over delete_concept. index.md and log.md are maintained by the server; do not write them. A project is bound to repositories through the \`repositories\` list in its overview frontmatter.
@@ -62,30 +62,49 @@ export function createMcpServer(service, principal, log) {
     const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
     tool("list_projects", "read", {
         title: "List projects",
-        description: "List projects (OKF bundles) with concept and staleness counts and the git repositories bound to each; pass repository to find the projects that hold a codebase's knowledge.",
+        description: "Call first to pick the project. In a git repository pass `repository` (the remote URL); outside a git repository (e.g. desktop chat), call with `team` and/or `query` (or no arguments) and choose by title, description, teams, domains, keywords; a project named by the user or project instructions wins. Lists projects (OKF bundles) with concept and staleness counts, bound git repositories, and routing metadata (teams, domains, audience, keywords, owners).",
         inputSchema: z.object({
             repository: z
                 .string()
                 .optional()
-                .describe("Git remote URL of the current repository, e.g. the output of `git remote get-url origin`; returns only the projects bound to it"),
+                .describe("Git remote URL of the current repository, e.g. the output of `git remote get-url origin`; returns only the projects bound to it. Omit outside a git repository."),
+            team: z.string().optional().describe("Case-insensitive match on the overview's `teams`"),
+            query: z
+                .string()
+                .optional()
+                .describe("Keywords matched against title, description, `domains`, and `keywords`; any term matches by word prefix"),
+        }),
+        annotations: readOnly,
+    }, (a) => service.listProjects(principal, { repository: a.repository, team: a.team, query: a.query }));
+    tool("orient", "read", {
+        title: "Orient across organization knowledge",
+        description: "Call before answering any question about how the organization works: processes, policies, customers, products, campaigns. Returns ranked projects, each with its top concepts and scores, plus working rules (freshness first, trust tier, citing sources, and rephrasing queries).",
+        inputSchema: z.object({
+            question: z
+                .string()
+                .min(1)
+                .max(512)
+                .describe("The user's question, task, or search terms to orient against (max 512 chars)"),
+            project: z.string().optional().describe("Restrict orientation to a single project"),
+            limit: z.number().int().min(1).max(50).optional().describe("Maximum projects to return (default: 5)"),
         }),
         annotations: readOnly,
-    }, (a) => service.listProjects({ repository: a.repository }));
+    }, (a) => service.orient(principal, { question: a.question, project: a.project, limit: a.limit }));
     tool("get_index", "read", {
         title: "Get directory index",
         description: "Progressive-disclosure listing of one bundle directory: its concepts grouped by type, files, and subdirectories.",
         inputSchema: z.object({ project, path: z.string().optional().describe("directory, default bundle root") }),
         annotations: readOnly,
-    }, (a) => service.getIndex(a.project, a.path ?? ""));
+    }, (a) => service.getIndex(principal, a.project, a.path ?? ""));
     tool("read_concept", "read", {
         title: "Read concept",
         description: "Read one concept with frontmatter, body, derived trust/staleness, links, and lint issues; returns `revision` to pass back as expectedRevision when updating.",
         inputSchema: z.object({ project, id }),
         annotations: readOnly,
-    }, (a) => service.readConcept(a.project, a.id));
+    }, (a) => service.readConcept(principal, a.project, a.id));
     tool("search_concepts", "read", {
         title: "Search concepts",
-        description: "Keyword full-text search over concepts, optionally filtered by project, type, tags, status, trust tier, and staleness.",
+        description: "Keyword full-text search over concepts, optionally filtered by project, type, tags, status, trust tier, and staleness. Omitting project searches every project (use when no project is resolved yet or outside a repository); results carry project to use for follow-up read_concept calls. Cite concepts read.",
         inputSchema: z.object({
             query: z.string().max(512).optional(),
             project: z.string().optional(),
@@ -97,32 +116,32 @@ export function createMcpServer(service, principal, log) {
             limit,
         }),
         annotations: readOnly,
-    }, (a) => service.search(a));
+    }, (a) => service.search(principal, a));
     tool("get_history", "read", {
         title: "Get history",
         description: "List git commits that changed a concept, or the whole project when id is omitted.",
         inputSchema: z.object({ project, id: id.optional(), limit }),
         annotations: readOnly,
-    }, (a) => service.history(a.project, a.id, a.limit));
+    }, (a) => service.history(principal, a.project, a.id, a.limit));
     tool("read_file", "read", {
         title: "Read file",
         description: "Read any text file in a bundle verbatim (including index.md, log.md, and non-markdown assets).",
         inputSchema: z.object({ project, path: z.string().describe("bundle-relative file path") }),
         annotations: readOnly,
-    }, (a) => service.readFile(a.project, a.path));
+    }, (a) => service.readFile(principal, a.project, a.path));
     tool("lint_project", "read", {
         title: "Lint project",
         description: "Check a bundle for OKF v0.2 conformance and return errors, warnings, and info issues.",
         inputSchema: z.object({ project }),
         annotations: readOnly,
-    }, (a) => service.lint(a.project));
+    }, (a) => service.lint(principal, a.project));
     const conflictId = z.string().describe("Conflict id from list_conflicts or an unresolved_conflict lint issue");
     tool("list_conflicts", "read", {
         title: "List conflicts",
         description: "List the project's unresolved conflicts: writes the server accepted but could not reconcile with a concurrent edit from another ok-fine instance. Each lists changed files (divergent = the current version also changed) and the commits that made them.",
         inputSchema: z.object({ project }),
         annotations: readOnly,
-    }, (a) => service.listConflicts(a.project));
+    }, (a) => service.listConflicts(principal, a.project));
     tool("read_conflict", "read", {
         title: "Read conflict file",
         description: "Read one file of a conflict: `preserved` (the unapplied write), `base` (common ancestor), and `current` (with the revision to pass as expectedRevision when writing the merge). null = absent on that side.",
@@ -132,7 +151,7 @@ export function createMcpServer(service, principal, log) {
             path: z.string().describe("bundle-relative file path, e.g. tables/orders.md"),
         }),
         annotations: readOnly,
-    }, (a) => service.readConflict(a.project, a.id, a.path));
+    }, (a) => service.readConflict(principal, a.project, a.id, a.path));
     tool("resolve_conflict", "write", {
         title: "Resolve conflict",
         description: "Discard a conflict's preserved copy after merging what should survive with write_concept/write_file. `paths` must list every file of the conflict, confirming each was reconciled; only this project's part of the conflict is resolved.",

package/dist/metrics/histogram.js

@@ -0,0 +1,36 @@
+/**
+ * Inclusive upper bounds (ms) of the latency histogram buckets; one overflow bucket follows the last.
+ * Changing them changes the database columns: bump SCHEMA_VERSION in store.ts.
+ */
+export const LATENCY_BUCKETS_MS = [
+    0.1, 0.25, 0.5, 1, 2.5, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000,
+];
+export const BUCKET_COUNT = LATENCY_BUCKETS_MS.length + 1;
+export function bucketIndex(ms) {
+    const i = LATENCY_BUCKETS_MS.findIndex((upper) => ms <= upper);
+    return i === -1 ? BUCKET_COUNT - 1 : i;
+}
+/** Estimates quantile q (0..1) by linear interpolation inside the bucket holding the rank, clamped to [minMs, maxMs]. */
+export function quantile(buckets, q, minMs, maxMs) {
+    let total = 0;
+    for (const c of buckets)
+        total += c;
+    if (total === 0)
+        return 0;
+    const rank = q * total;
+    let cum = 0;
+    for (let i = 0; i < buckets.length; i++) {
+        const c = buckets[i] ?? 0;
+        if (c === 0)
+            continue;
+        if (cum + c >= rank) {
+            const lower = i === 0 ? 0 : (LATENCY_BUCKETS_MS[i - 1] ?? 0);
+            const upper = i < LATENCY_BUCKETS_MS.length ? (LATENCY_BUCKETS_MS[i] ?? maxMs) : maxMs;
+            const value = lower + (upper - lower) * ((rank - cum) / c);
+            return Math.min(Math.max(value, minMs), maxMs);
+        }
+        cum += c;
+    }
+    return maxMs;
+}
+//# sourceMappingURL=histogram.js.map

package/dist/metrics/instrument.js

@@ -0,0 +1,146 @@
+import { performance } from "node:perf_hooks";
+import { finished, Readable } from "node:stream";
+import { OkfError } from "../errors.js";
+/** The service reports client errors only as OkfError with a 4xx status; anything else is a server error. */
+export function outcomeOf(err) {
+    return err instanceof OkfError && err.status < 500 ? "client_error" : "server_error";
+}
+async function time(sink, layer, op, fn) {
+    const startedAt = performance.now();
+    try {
+        const value = await fn();
+        sink.record(layer, op, startedAt, "ok");
+        return value;
+    }
+    catch (err) {
+        sink.record(layer, op, startedAt, outcomeOf(err));
+        throw err;
+    }
+}
+/** Records once the stream ends, errors, or is destroyed. */
+function timeStream(sink, layer, op, startedAt, stream) {
+    finished(stream, (err) => sink.record(layer, op, startedAt, err ? outcomeOf(err) : "ok"));
+    return stream;
+}
+class InstrumentedTx {
+    inner;
+    sink;
+    constructor(inner, sink) {
+        this.inner = inner;
+        this.sink = sink;
+    }
+    writeFile(project, path, content) {
+        return time(this.sink, "storage", "tx.writeFile", () => this.inner.writeFile(project, path, content));
+    }
+    deleteFile(project, path) {
+        return time(this.sink, "storage", "tx.deleteFile", () => this.inner.deleteFile(project, path));
+    }
+    deleteProject(project) {
+        return time(this.sink, "storage", "tx.deleteProject", () => this.inner.deleteProject(project));
+    }
+    replaceProject(project, source) {
+        return time(this.sink, "storage", "tx.replaceProject", () => this.inner.replaceProject(project, source));
+    }
+    resolveConflict(project, id) {
+        return time(this.sink, "storage", "tx.resolveConflict", () => this.inner.resolveConflict(project, id));
+    }
+}
+/** Times every StorageBackend and StorageTx call under layer `storage`, op = method name. */
+export class InstrumentedStorage {
+    inner;
+    sink;
+    constructor(inner, sink) {
+        this.inner = inner;
+        this.sink = sink;
+    }
+    projects() {
+        return time(this.sink, "storage", "projects", () => this.inner.projects());
+    }
+    tree(project) {
+        return time(this.sink, "storage", "tree", () => this.inner.tree(project));
+    }
+    readFile(project, path) {
+        return time(this.sink, "storage", "readFile", () => this.inner.readFile(project, path));
+    }
+    /** Duration includes lock wait, the work, commit, and push. */
+    transaction(spec, work) {
+        return time(this.sink, "storage", "transaction", () => this.inner.transaction(spec, (tx) => work(new InstrumentedTx(tx, this.sink))));
+    }
+    setResyncHandler(handler) {
+        this.inner.setResyncHandler((project, tx) => handler(project, new InstrumentedTx(tx, this.sink)));
+    }
+    history(project, path, limit) {
+        return time(this.sink, "storage", "history", () => this.inner.history(project, path, limit));
+    }
+    archive(project) {
+        const startedAt = performance.now();
+        let stream;
+        try {
+            stream = this.inner.archive(project);
+        }
+        catch (err) {
+            this.sink.record("storage", "archive", startedAt, outcomeOf(err));
+            throw err;
+        }
+        return timeStream(this.sink, "storage", "archive", startedAt, stream);
+    }
+    sync() {
+        return time(this.sink, "storage", "sync", () => this.inner.sync());
+    }
+    syncStatus() {
+        return time(this.sink, "storage", "syncStatus", () => this.inner.syncStatus());
+    }
+    conflicts(project) {
+        return time(this.sink, "storage", "conflicts", () => this.inner.conflicts(project));
+    }
+    readConflictFile(project, id, side, path) {
+        return time(this.sink, "storage", "readConflictFile", () => this.inner.readConflictFile(project, id, side, path));
+    }
+    close() {
+        return this.inner.close();
+    }
+}
+/**
+ * Times every KnowledgeService method call under layer `service`, op = method name. A Proxy covers methods added
+ * later; methods run bound to the raw service, so its internal `this.*` calls are not counted twice.
+ */
+export function instrumentService(service, sink) {
+    const wrappers = new Map();
+    return new Proxy(service, {
+        get(target, prop) {
+            const value = Reflect.get(target, prop);
+            if (typeof prop !== "string" || prop === "constructor" || typeof value !== "function")
+                return value;
+            let wrapper = wrappers.get(prop);
+            if (!wrapper) {
+                wrapper = (...args) => {
+                    const startedAt = performance.now();
+                    let result;
+                    try {
+                        result = Reflect.apply(value, target, args);
+                    }
+                    catch (err) {
+                        sink.record("service", prop, startedAt, outcomeOf(err));
+                        throw err;
+                    }
+                    if (result instanceof Promise) {
+                        return result.then((v) => {
+                            sink.record("service", prop, startedAt, "ok");
+                            return v;
+                        }, (err) => {
+                            sink.record("service", prop, startedAt, outcomeOf(err));
+                            throw err;
+                        });
+                    }
+                    if (result instanceof Readable)
+                        return timeStream(sink, "service", prop, startedAt, result);
+                    sink.record("service", prop, startedAt, "ok");
+                    return result;
+                };
+                wrappers.set(prop, wrapper);
+            }
+            return wrapper;
+        },
+    });
+}
+//# sourceMappingURL=instrument.js.map