synomem 0.8.0 → 0.9.0

package/src/project.ts

@@ -1,60 +1,56 @@
 /**
- * Per-project workspace selection.
+ * Per-project profile selection.
  *
- * The goal is that opening an agent in a repository is enough: every note,
- * memo, task, todo and post it writes lands in that repository's workspace,
- * with nobody naming the workspace again for the rest of the session.
+ * Opening an agent in a repository should be enough to act as the right
+ * identity: a `.synomem/project.json` found by walking up from the working
+ * directory may name a profile (or an MCP preset) from the user's own
+ * `profiles.json`.
  *
- * That cannot be a command typed into a running session. The stdio MCP server
- * is bound to a home and an actor when the harness launches it, so a later
- * instruction has nothing to retarget. It also should not be one global
- * "current workspace": two agents open in two repositories would fight over
- * it, which is exactly the case this exists to serve.
- *
- * So it is a file in the project, found by walking up from the working
- * directory — the same shape as `.git`, `.nvmrc` or `.npmrc`, and for the same
- * reason: the directory somebody is working in is the thing that knows which
- * project this is.
- *
- * `.synomem/config.json` holds a POINTER, never a store:
- *
- *     { "workspace": "lumina", "actor": "claude" }
- *
- * The database stays under the Synomem home. Putting one in the repository
- * would mean an append-only event log inside somebody's git history, committed
- * by accident the first time they ran `git add -A`.
+ * It may name ONLY that. A cloned repository is untrusted input, so the file
+ * cannot carry a credential, an API origin, a context id, or an actor — it can
+ * point at a profile the user already created, and nothing else. An unknown
+ * key is refused rather than ignored, so an old `{ "workspace", "actor" }`
+ * pointer fails loudly instead of silently doing nothing.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, parse, resolve } from 'node:path';
-import { resolveHome } from './config.js';
 import { z } from 'zod';
 import { SynomemError } from './errors.js';
-import { localWorkspaceHome, workspaceNameSchema } from './workspaces.js';
 
 export const PROJECT_DIRECTORY = '.synomem';
-export const PROJECT_CONFIG_FILE = 'config.json';
+/*
+ * `project.json`, never `config.json`: a Synomem home (a local store) keeps its
+ * own policy in `.synomem/config.json`, and the walk up from a project directory
+ * passes through the user's home — so a shared name would read the store's
+ * config as a project pointer and break every command run beneath it.
+ */
+export const PROJECT_CONFIG_FILE = 'project.json';
+
+const nameSchema = z
+  .string()
+  .trim()
+  .regex(/^[a-z0-9][a-z0-9._-]{0,62}$/i, 'must be a profile or preset name');
 
-export const projectConfigSchema = z.object({
-  /** The local workspace this project's records belong in. */
-  workspace: workspaceNameSchema.optional(),
-  /** The agent this project's records are written by, when it is always one. */
-  actor: z.string().trim().min(1).max(63).optional(),
-});
+export const projectConfigSchema = z
+  .object({
+    profile: nameSchema.optional(),
+    preset: nameSchema.optional(),
+  })
+  .strict()
+  .refine((value) => !(value.profile && value.preset), {
+    message: 'name a profile or a preset, not both',
+  });
 
 export type ProjectConfig = z.infer<typeof projectConfigSchema>;
 
 export interface ProjectSelection extends ProjectConfig {
-  /** The directory whose `.synomem` was used, so tools can say where it came from. */
-  directory: string;
+  /** The file that supplied the selection, so errors can say where it came from. */
+  path: string;
 }
 
 /**
- * The nearest project configuration at or above `from`.
- *
- * Walking up stops at the filesystem root, and never treats the Synomem home
- * itself as a project: `~/.synomem/config.json` is a real Synomem config with a
- * different shape, and reading it as a project pointer would silently apply a
- * home's settings to every command run anywhere under the home directory.
+ * The nearest project file at or above `from`. The Synomem home itself is
+ * never treated as a project directory.
  */
 export function findProjectSelection(
   from: string = process.cwd(),
@@ -63,12 +59,11 @@ export function findProjectSelection(
   const stopAt = parse(resolve(from)).root;
   let directory = resolve(from);
   for (;;) {
-    const candidate = join(directory, PROJECT_DIRECTORY, PROJECT_CONFIG_FILE);
-    // `<home>/config.json` is the home's own config, not a project pointer, and
-    // the home is never a project directory.
-    const isHome = home !== undefined && resolve(home) === join(directory, PROJECT_DIRECTORY);
+    const folder = join(directory, PROJECT_DIRECTORY);
+    const candidate = join(folder, PROJECT_CONFIG_FILE);
+    const isHome = home !== undefined && resolve(home) === folder;
     if (!isHome && existsSync(candidate)) {
-      return { ...readProjectConfig(candidate), directory };
+      return { ...readProjectConfig(candidate), path: candidate };
     }
     if (directory === stopAt) return undefined;
     const parent = dirname(directory);
@@ -88,7 +83,9 @@ function readProjectConfig(path: string): ProjectConfig {
   if (!parsed.success) {
     throw new SynomemError(
       'CONFIG_INVALID',
-      `${path} is not a valid Synomem project file: ${parsed.error.issues[0]?.message ?? 'unknown problem'}`,
+      `${path} is not a valid Synomem project file (it may name only a "profile" or a "preset"): ${
+        parsed.error.issues[0]?.message ?? 'unknown problem'
+      }`,
     );
   }
   return parsed.data;
@@ -103,66 +100,3 @@ export function writeProjectSelection(directory: string, config: ProjectConfig):
   writeFileSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
   return path;
 }
-
-/**
- * Which workspace to act in, and as whom.
- *
- * One resolver, used by both the CLI and the stdio MCP server, so the two
- * cannot disagree about precedence. Order, most specific first:
- *
- *   1. `--workspace` / `--actor` — said on this invocation
- *   2. `SYNOMEM_WORKSPACE` / `SYNOMEM_ACTOR_ID` — set for this process
- *   3. `.synomem/config.json` in the project, found by walking up from the
- *      working directory
- *   4. the root home, which is the default workspace
- *
- * The project file is third rather than first because a flag someone typed
- * should always beat a file they may have forgotten is there.
- */
-export function resolveWorkspaceSelection(input: {
-  flag?: string;
-  actorFlag?: string;
-  env?: NodeJS.ProcessEnv;
-  cwd?: string;
-  explicitRoot?: string;
-}): { home: string; workspace?: string; actor?: string; source: string } {
-  const env = input.env ?? process.env;
-  const root = resolveHome(input.explicitRoot);
-
-  if (input.flag) {
-    return {
-      home: localWorkspaceHome(input.flag, input.explicitRoot),
-      workspace: input.flag,
-      ...(input.actorFlag ? { actor: input.actorFlag } : {}),
-      source: 'the --workspace option',
-    };
-  }
-
-  const fromEnv = env.SYNOMEM_WORKSPACE?.trim();
-  if (fromEnv) {
-    return {
-      home: localWorkspaceHome(fromEnv, input.explicitRoot),
-      workspace: fromEnv,
-      ...((input.actorFlag ?? env.SYNOMEM_ACTOR_ID?.trim())
-        ? { actor: input.actorFlag ?? env.SYNOMEM_ACTOR_ID?.trim() }
-        : {}),
-      source: 'SYNOMEM_WORKSPACE',
-    };
-  }
-
-  const project = findProjectSelection(input.cwd ?? process.cwd(), root);
-  if (project?.workspace) {
-    return {
-      home: localWorkspaceHome(project.workspace, input.explicitRoot),
-      workspace: project.workspace,
-      ...((input.actorFlag ?? project.actor) ? { actor: input.actorFlag ?? project.actor } : {}),
-      source: join(project.directory, PROJECT_DIRECTORY, PROJECT_CONFIG_FILE),
-    };
-  }
-
-  return {
-    home: root,
-    ...((input.actorFlag ?? project?.actor) ? { actor: input.actorFlag ?? project?.actor } : {}),
-    source: 'the default workspace',
-  };
-}

package/src/remote.ts

@@ -1,9 +1,8 @@
 import { actorSchema } from './schemas.js';
-import { asSynomemError, errorCodes, SynomemError, type SynomemErrorCode } from './errors.js';
+import { errorCodes, SynomemError, type SynomemErrorCode } from './errors.js';
 import type { SynomemService, SynomemServiceCapabilities, SynomemServiceInfo } from './service.js';
 import type {
   ActorIdentity,
-  WorkspaceIdentity,
   ChangesInput,
   BindRuntimeInput,
   CreateAgentInput,
@@ -32,26 +31,40 @@ export interface SynomemCredentialProvider {
   getAccessToken(signal?: AbortSignal): Promise<string | undefined>;
 }
 
+/**
+ * Where a remote service gets its bearer: an OAuth access token or a `syn_` access key
+ * (identity contract §6.1). It may refresh; it must never be logged.
+ */
+export interface RemoteCredentialSource {
+  bearer(): Promise<string>;
+}
+
+export type RemoteCredential =
+  RemoteCredentialSource | SynomemCredentialProvider | (() => Promise<string | undefined>);
+
 export interface RemoteSynomemOptions {
   baseUrl: string;
+  /** The workspace in the route. Must equal the selected context's workspace. */
   workspaceId: string;
-  expectedActor: ActorIdentity;
-  credentialProvider: SynomemCredentialProvider;
+  /**
+   * The stable target this service acts as. Sent as `Synomem-Context-Id` on every request.
+   * Omit only for a fixed credential, whose single pinned context the API selects itself.
+   */
+  contextId?: string;
+  credential: RemoteCredential;
   fetch?: typeof fetch;
   signal?: AbortSignal;
   timeoutMs?: number;
   maximumResponseBytes?: number;
-  /**
-   * False when `expectedActor` is only a historical CLI fallback guess (a
-   * caller named no real identity via `--actor`, `SYNOMEM_ACTOR_ID`, or a
-   * project binding), not an identity the caller actually asserted. Defaults
-   * to true, so every existing caller keeps its current strict behavior.
-   * `kind: 'system'` already bypasses the match unconditionally (its own
-   * historical bootstrap placeholder); this is the same bypass for a
-   * fallback of any other kind, without pretending that fallback IS a real
-   * identity.
-   */
-  assertActor?: boolean;
+}
+
+/** Normalizes any accepted credential shape into one bearer lookup. */
+export function bearerFrom(
+  credential: RemoteCredential,
+): (signal?: AbortSignal) => Promise<string | undefined> {
+  if (typeof credential === 'function') return () => credential();
+  if ('bearer' in credential) return () => credential.bearer();
+  return (signal) => credential.getAccessToken(signal);
 }
 
 interface ApiErrorEnvelope {
@@ -111,6 +124,14 @@ function queryString(input: object): string {
   return encoded ? `?${encoded}` : '';
 }
 
+/** Codes a caller must be able to branch on, never collapsed into AUTH_* by status. */
+const contextCodes = new Set<SynomemErrorCode>([
+  'CONTEXT_REQUIRED',
+  'CONTEXT_FORBIDDEN',
+  'CONTEXT_AMBIGUOUS',
+  'REAUTHORIZATION_REQUIRED',
+]);
+
 function knownErrorCode(value: string): SynomemErrorCode {
   return errorCodes.some((code) => code === value)
     ? (value as SynomemErrorCode)
@@ -158,17 +179,19 @@ export function environmentCredentialProvider(
 }
 
 export class RemoteSynomemService implements SynomemService {
-  // Not `readonly`: `init()` resolves it from the server's response when the
-  // caller didn't assert a real identity up front (see `assertedRealActor`).
-  actor: ActorIdentity;
+  /**
+   * The actor this service acts as, learned from the server during `init()` — never asserted
+   * by the caller. Before `init()` it is a placeholder that no request uses.
+   */
+  actor: ActorIdentity = { kind: 'system', id: 'unbound' };
+  readonly contextId?: string;
   private readonly baseUrl: URL;
   private readonly workspaceId: string;
-  private readonly credentialProvider: SynomemCredentialProvider;
+  private readonly bearer: (signal?: AbortSignal) => Promise<string | undefined>;
   private readonly fetchImplementation: typeof fetch;
   private readonly signal?: AbortSignal;
   private readonly timeoutMs: number;
   private readonly maximumResponseBytes: number;
-  private readonly assertActor: boolean;
   private initialized = false;
   private cachedCapabilities?: SynomemServiceCapabilities;
 
@@ -541,13 +564,13 @@ export class RemoteSynomemService implements SynomemService {
       throw new SynomemError('CONFIG_INVALID', 'Remote Synomem workspaceId is required.');
     }
     this.workspaceId = options.workspaceId;
-    try {
-      this.actor = actorSchema.parse(options.expectedActor);
-    } catch (error) {
-      throw asSynomemError(error);
+    if (options.contextId !== undefined) {
+      if (!/^[A-Za-z0-9_-]{1,100}$/.test(options.contextId)) {
+        throw new SynomemError('CONFIG_INVALID', 'Remote Synomem contextId is malformed.');
+      }
+      this.contextId = options.contextId;
     }
-    this.credentialProvider = options.credentialProvider;
-    this.assertActor = options.assertActor ?? true;
+    this.bearer = bearerFrom(options.credential);
     this.fetchImplementation = options.fetch ?? fetch;
     this.signal = options.signal;
     this.timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
@@ -573,30 +596,21 @@ export class RemoteSynomemService implements SynomemService {
       throw new SynomemError('REMOTE_PROTOCOL', 'The configured server is not a remote backend.');
     }
     const binding = this.cachedCapabilities.binding;
-    // `kind: 'system'` is this client's own placeholder for "no actor
-    // asserted" — historically the CLI default for commands that run before
-    // any identity exists (`doctor`, `agent list`, `agent create`, …). No
-    // credential the server authenticates ever reports that kind back, so
-    // asserting it here would make every one of those commands fail against
-    // a remote backend no matter who is actually calling — exactly the
-    // bootstrap deadlock the server-side half of this already fixed.
-    // `assertActor: false` is the same bypass for a fallback of any other
-    // kind: a caller whose "actor" is only a historical guess (never a real
-    // --actor, SYNOMEM_ACTOR_ID, or project binding) that should adopt
-    // whatever the credential actually names rather than fail outright.
-    // Either way, only a caller that named a real identity gets it enforced.
-    const assertedRealActor = this.assertActor && this.actor.kind !== 'system';
-    if (
-      binding.workspaceId !== this.workspaceId ||
-      (assertedRealActor &&
-        (binding.actor.kind !== this.actor.kind || binding.actor.id !== this.actor.id))
-    ) {
+    if (binding.workspaceId !== this.workspaceId) {
       throw new SynomemError(
-        'AUTH_FORBIDDEN',
-        'The authenticated Synomem actor does not match the configured actor.',
+        'CONTEXT_FORBIDDEN',
+        'The selected Synomem context does not belong to the workspace this service addresses.',
       );
     }
-    if (!assertedRealActor) this.actor = binding.actor;
+    if (this.contextId && binding.contextId && binding.contextId !== this.contextId) {
+      throw new SynomemError('CONTEXT_FORBIDDEN', 'The server bound a different context.');
+    }
+    const actor = actorSchema.safeParse(binding.actor);
+    if (!actor.success) {
+      throw new SynomemError('REMOTE_PROTOCOL', 'The server reported an invalid bound actor.');
+    }
+    // The server decides who this is; the client only learns it (plan §5 rule 7).
+    this.actor = actor.data;
     this.initialized = true;
   }
 
@@ -642,10 +656,6 @@ export class RemoteSynomemService implements SynomemService {
     return { backend: 'remote', baseUrl: this.baseUrl.href, workspaceId: this.workspaceId };
   }
 
-  async workspaces(): Promise<WorkspaceIdentity> {
-    return this.request<WorkspaceIdentity>('GET', '../../identity');
-  }
-
   getCanonicalEvent(id: string) {
     return this.request<Awaited<ReturnType<SynomemService['getCanonicalEvent']>>>(
       'GET',
@@ -703,7 +713,7 @@ export class RemoteSynomemService implements SynomemService {
     body?: object,
     idempotencyKey?: string,
   ): Promise<T> {
-    const accessToken = await this.credentialProvider.getAccessToken(this.signal);
+    const accessToken = await this.bearer(this.signal);
     if (!accessToken) {
       throw new SynomemError('AUTH_REQUIRED', 'Remote Synomem authentication is required.');
     }
@@ -726,15 +736,9 @@ export class RemoteSynomemService implements SynomemService {
         headers: {
           accept: 'application/json',
           authorization: `Bearer ${accessToken}`,
-          /*
-           * Harmless for an OAuth actor token (its workspace and identity are
-           * already bound into the token itself), and required for an access
-           * key: an access key authenticates the member who owns it, not a
-           * machine or a workspace, so which workspace and which agent are
-           * meant have to be named on every request.
-           */
-          'synomem-workspace-id': this.workspaceId,
-          ...(this.actor.kind === 'agent' ? { 'synomem-agent-id': this.actor.id } : {}),
+          // The ONLY selector (identity contract §3). The server authorizes it against the
+          // credential's grant on every request; knowing an id grants nothing.
+          ...(this.contextId ? { 'synomem-context-id': this.contextId } : {}),
           ...(body ? { 'content-type': 'application/json' } : {}),
           ...(idempotencyKey ? { 'idempotency-key': idempotencyKey } : {}),
         },
@@ -765,8 +769,10 @@ export class RemoteSynomemService implements SynomemService {
       if (envelope.ok !== false || !envelope.error || typeof envelope.error.message !== 'string') {
         throw new SynomemError('REMOTE_PROTOCOL', 'Remote Synomem returned an invalid error.');
       }
-      const code =
-        response.status === 401
+      const reported = knownErrorCode(envelope.error.code);
+      const code = contextCodes.has(reported)
+        ? reported
+        : response.status === 401
           ? 'AUTH_REQUIRED'
           : response.status === 403
             ? 'AUTH_FORBIDDEN'