@prjct.app/pi-team 0.6.0 → 0.7.0

package/src/storage/lease-store.ts

@@ -0,0 +1,158 @@
+import { randomUUID } from 'node:crypto';
+import { assertLease, leaseExpired, sameLeaseOwner, type Lease, type LeaseKind } from '../domain/lease.ts';
+import { assertEntityId, assertTeam, assertTeamId, type Team } from '../domain/team.ts';
+import {
+  createAtomicJson, ensurePrivateDirectory, ensurePrivateTree, jsonFileNames, readJson, replaceAtomicJson, withStorageLock,
+} from './atomic.ts';
+import { TeamPaths } from './paths.ts';
+
+const LEASE_MAX_BYTES = 16 * 1024;
+const TEAM_MAX_BYTES = 32 * 1024;
+const DEFAULT_MAX_TTL_MS = 24 * 60 * 60 * 1000;
+
+export type AcquireLease = {
+  readonly teamId: string;
+  readonly leaseId: string;
+  readonly kind: LeaseKind;
+  readonly holderId: string;
+  readonly resourceId: string;
+  readonly ttlMs: number;
+};
+
+export type LeaseStoreOptions = {
+  readonly maxTtlMs?: number;
+  readonly now?: () => number;
+};
+
+export class LeaseStore {
+  private readonly maxTtlMs: number;
+  private readonly now: () => number;
+
+  constructor(readonly paths: TeamPaths, options: LeaseStoreOptions = {}) {
+    this.maxTtlMs = options.maxTtlMs ?? DEFAULT_MAX_TTL_MS;
+    this.now = options.now ?? Date.now;
+    if (!Number.isFinite(this.maxTtlMs) || this.maxTtlMs <= 0) throw new Error('Invalid maximum lease TTL.');
+  }
+
+  private lockPath(teamId: string): string { return this.paths.lock(`leases-${assertTeamId(teamId)}`); }
+
+  private async prepare(): Promise<void> {
+    await ensurePrivateTree(this.paths.root, 'teams');
+    await ensurePrivateTree(this.paths.root, 'control');
+  }
+
+  private validateInput(input: AcquireLease): void {
+    assertTeamId(input.teamId);
+    assertEntityId(input.leaseId, 'lease ID');
+    assertEntityId(input.holderId, 'lease holder ID');
+    if (!['presence', 'delivery', 'resource'].includes(input.kind)) throw new Error('Invalid lease kind.');
+    if (!input.resourceId || input.resourceId.length > 4096 || input.resourceId.includes('\0')) throw new Error('Invalid lease resource ID.');
+    if (!Number.isFinite(input.ttlMs) || input.ttlMs <= 0 || input.ttlMs > this.maxTtlMs) throw new Error('Invalid lease TTL.');
+  }
+
+  private async requireTeam(teamId: string): Promise<Team> {
+    try {
+      await ensurePrivateDirectory(this.paths.team(teamId), false);
+      await ensurePrivateDirectory(this.paths.leases(teamId), false);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw Object.assign(new Error(`Unknown team "${teamId}".`), { code: 'NOT_FOUND' });
+      }
+      throw error;
+    }
+    const team = await readJson(this.paths.teamRecord(teamId), assertTeam, TEAM_MAX_BYTES);
+    if (!team) throw Object.assign(new Error(`Team "${teamId}" is incomplete.`), { code: 'NOT_FOUND' });
+    return team;
+  }
+
+  async read(teamId: string, leaseId: string): Promise<Lease | undefined> {
+    await this.prepare();
+    await this.requireTeam(teamId);
+    const lease = await readJson(this.paths.lease(teamId, leaseId), assertLease, LEASE_MAX_BYTES);
+    if (lease && (lease.teamId !== teamId || lease.leaseId !== leaseId)) {
+      throw Object.assign(new Error('Lease identity does not match its storage path.'), { code: 'CORRUPT_RECORD' });
+    }
+    return lease;
+  }
+
+  async acquire(input: AcquireLease): Promise<Lease> {
+    this.validateInput(input);
+    await this.prepare();
+    return withStorageLock(this.lockPath(input.teamId), async () => {
+      const team = await this.requireTeam(input.teamId);
+      if (team.state !== 'open') throw Object.assign(new Error(`Team "${input.teamId}" is ${team.state}.`), { code: 'TEAM_CLOSED' });
+      const current = await this.read(input.teamId, input.leaseId);
+      const now = this.now();
+      if (current && !leaseExpired(current, now)) {
+        throw Object.assign(new Error(`Lease "${input.leaseId}" is held.`), { code: 'LEASE_HELD' });
+      }
+      const lease: Lease = {
+        schemaVersion: 2,
+        teamId: input.teamId,
+        leaseId: input.leaseId,
+        kind: input.kind,
+        holderId: input.holderId,
+        resourceId: input.resourceId,
+        token: randomUUID(),
+        generation: (current?.generation ?? 0) + 1,
+        acquiredAt: new Date(now).toISOString(),
+        expiresAt: new Date(now + input.ttlMs).toISOString(),
+      };
+      assertLease(lease);
+      if (current) await replaceAtomicJson(this.paths.lease(input.teamId, input.leaseId), lease, { maxBytes: LEASE_MAX_BYTES });
+      else await createAtomicJson(this.paths.lease(input.teamId, input.leaseId), lease, LEASE_MAX_BYTES);
+      return lease;
+    });
+  }
+
+  async renew(
+    teamId: string,
+    leaseId: string,
+    holderId: string,
+    token: string,
+    generation: number,
+    ttlMs: number,
+  ): Promise<Lease> {
+    assertEntityId(holderId, 'lease holder ID');
+    if (!Number.isFinite(ttlMs) || ttlMs <= 0 || ttlMs > this.maxTtlMs) throw new Error('Invalid lease TTL.');
+    await this.prepare();
+    return withStorageLock(this.lockPath(teamId), async () => {
+      await this.requireTeam(teamId);
+      const current = await this.read(teamId, leaseId);
+      if (!current || current.holderId !== holderId || !sameLeaseOwner(current, token, generation)) {
+        throw Object.assign(new Error('Lease ownership has been fenced.'), { code: 'FENCED' });
+      }
+      const now = this.now();
+      if (leaseExpired(current, now)) throw Object.assign(new Error('Lease has expired.'), { code: 'EXPIRED' });
+      const renewed = { ...current, expiresAt: new Date(now + ttlMs).toISOString() } satisfies Lease;
+      assertLease(renewed);
+      await replaceAtomicJson(this.paths.lease(teamId, leaseId), renewed, { maxBytes: LEASE_MAX_BYTES });
+      return renewed;
+    });
+  }
+
+  async release(teamId: string, leaseId: string, holderId: string, token: string, generation: number): Promise<void> {
+    assertEntityId(holderId, 'lease holder ID');
+    await this.prepare();
+    await withStorageLock(this.lockPath(teamId), async () => {
+      await this.requireTeam(teamId);
+      const current = await this.read(teamId, leaseId);
+      if (!current || current.holderId !== holderId || !sameLeaseOwner(current, token, generation)) {
+        throw Object.assign(new Error('Lease ownership has been fenced.'), { code: 'FENCED' });
+      }
+      const releasedAt = Math.max(this.now(), Date.parse(current.acquiredAt));
+      const released = { ...current, releasedAt: new Date(releasedAt).toISOString() } satisfies Lease;
+      assertLease(released);
+      await replaceAtomicJson(this.paths.lease(teamId, leaseId), released, { maxBytes: LEASE_MAX_BYTES });
+    });
+  }
+
+  async list(teamId: string): Promise<readonly Lease[]> {
+    assertTeamId(teamId);
+    await this.prepare();
+    await this.requireTeam(teamId);
+    const ids = await jsonFileNames(this.paths.leases(teamId), false);
+    const leases = await Promise.all(ids.map(id => this.read(teamId, id)));
+    return leases.filter((lease): lease is Lease => lease !== undefined);
+  }
+}

package/src/storage/paths.ts

@@ -0,0 +1,76 @@
+import { lstat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { assertEntityId, assertTeamId } from '../domain/team.ts';
+
+export type LegacyDetection = {
+  readonly path: string;
+  readonly present: boolean;
+  readonly kind: 'directory' | 'symlink' | 'other' | 'absent';
+};
+
+export function defaultStorageRoot(environment: NodeJS.ProcessEnv = process.env): string {
+  const projectHome = environment.PRJCT_HOME?.trim();
+  const base = projectHome ? (isAbsolute(projectHome) ? projectHome : resolve(projectHome)) : join(homedir(), '.prjct');
+  return join(base, 'pi-team');
+}
+
+export async function detectLegacyRoot(path = join(homedir(), '.pi', 'agent', 'teams')): Promise<LegacyDetection> {
+  const info = await lstat(path).catch(error => {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  });
+  if (!info) return { path, present: false, kind: 'absent' };
+  return {
+    path,
+    present: true,
+    kind: info.isSymbolicLink() ? 'symlink' : info.isDirectory() ? 'directory' : 'other',
+  };
+}
+
+export class TeamPaths {
+  readonly root: string;
+
+  constructor(root = defaultStorageRoot()) {
+    this.root = resolve(root);
+  }
+
+  teams(): string { return join(this.root, 'teams'); }
+  control(): string { return join(this.root, 'control'); }
+  team(teamId: string): string { return join(this.teams(), assertTeamId(teamId)); }
+  teamRecord(teamId: string): string { return join(this.team(teamId), 'team.json'); }
+  members(teamId: string): string { return join(this.team(teamId), 'members'); }
+  member(teamId: string, memberId: string): string {
+    return join(this.members(teamId), `${assertEntityId(memberId, 'member ID')}.json`);
+  }
+  runtimes(teamId: string): string { return join(this.team(teamId), 'runtimes'); }
+  runtime(teamId: string, runtimeId: string): string {
+    return join(this.runtimes(teamId), `${assertEntityId(runtimeId, 'runtime ID')}.json`);
+  }
+  inbox(teamId: string): string { return join(this.team(teamId), 'inbox'); }
+  memberInbox(teamId: string, memberId: string): string {
+    return join(this.inbox(teamId), assertEntityId(memberId, 'member ID'));
+  }
+  pending(teamId: string, memberId: string): string { return join(this.memberInbox(teamId, memberId), 'pending'); }
+  claimed(teamId: string, memberId: string): string { return join(this.memberInbox(teamId, memberId), 'claimed'); }
+  pendingMessage(teamId: string, memberId: string, messageId: string): string {
+    return join(this.pending(teamId, memberId), `${assertEntityId(messageId, 'message ID')}.json`);
+  }
+  claimedMessage(teamId: string, memberId: string, messageId: string): string {
+    return join(this.claimed(teamId, memberId), `${assertEntityId(messageId, 'message ID')}.json`);
+  }
+  receipts(teamId: string): string { return join(this.team(teamId), 'receipts'); }
+  recipientReceipts(teamId: string, recipientId: string): string {
+    return join(this.receipts(teamId), assertEntityId(recipientId, 'recipient ID'));
+  }
+  receipt(teamId: string, recipientId: string, messageId: string): string {
+    return join(this.recipientReceipts(teamId, recipientId), `${assertEntityId(messageId, 'message ID')}.json`);
+  }
+  leases(teamId: string): string { return join(this.team(teamId), 'leases'); }
+  lease(teamId: string, leaseId: string): string {
+    return join(this.leases(teamId), `${assertEntityId(leaseId, 'lease ID')}.json`);
+  }
+  lock(name: string): string { return join(this.control(), `${assertEntityId(name, 'lock ID')}.lock`); }
+  teamLock(teamId: string): string { return this.lock(`team-${assertTeamId(teamId)}`); }
+  inboxLock(teamId: string): string { return this.lock(`inbox-${assertTeamId(teamId)}`); }
+}

package/src/storage/receipt-store.ts

@@ -0,0 +1,117 @@
+import { assertReceipt, type Receipt, type ReceiptStatus } from '../domain/message.ts';
+import { assertEntityId, assertTeamId, timestampMillis } from '../domain/team.ts';
+import {
+  createAtomicJson, ensurePrivateDirectory, ensurePrivateTree, jsonFileNames, readJson, removeAtomic, replaceAtomicJson,
+  withStorageLock,
+} from './atomic.ts';
+import { TeamPaths } from './paths.ts';
+
+const RECEIPT_MAX_BYTES = 16 * 1024;
+const TERMINAL_RECEIPT_TTL_MS = 24 * 60 * 60 * 1000;
+const terminal = new Set<ReceiptStatus>(['replied', 'cancelled', 'expired', 'failed']);
+const transitions: Readonly<Record<ReceiptStatus, readonly ReceiptStatus[]>> = {
+  delivered: ['read', 'replied', 'cancelled', 'expired', 'failed'],
+  read: ['replied', 'cancelled', 'expired', 'failed'],
+  replied: [],
+  cancelled: [],
+  expired: [],
+  failed: [],
+};
+
+export type ReceiptStoreOptions = {
+  readonly terminalTtlMs?: number;
+  readonly now?: () => number;
+};
+
+export class ReceiptStore {
+  private readonly terminalTtlMs: number;
+  private readonly now: () => number;
+
+  constructor(readonly paths: TeamPaths, options: ReceiptStoreOptions = {}) {
+    this.terminalTtlMs = options.terminalTtlMs ?? TERMINAL_RECEIPT_TTL_MS;
+    this.now = options.now ?? Date.now;
+    if (!Number.isFinite(this.terminalTtlMs) || this.terminalTtlMs <= 0) throw new Error('Invalid receipt TTL.');
+  }
+
+  private lockPath(teamId: string): string { return this.paths.lock(`receipts-${assertTeamId(teamId)}`); }
+
+  private async prepare(): Promise<void> {
+    await ensurePrivateTree(this.paths.root, 'teams');
+    await ensurePrivateTree(this.paths.root, 'control');
+  }
+
+  private async prepareRecipient(teamId: string, recipientId: string, create: boolean): Promise<boolean> {
+    try {
+      await ensurePrivateDirectory(this.paths.team(teamId), false);
+      await ensurePrivateDirectory(this.paths.receipts(teamId), false);
+      await ensurePrivateDirectory(this.paths.recipientReceipts(teamId, recipientId), create);
+      return true;
+    } catch (error) {
+      if (!create && (error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+      throw error;
+    }
+  }
+
+  private assertStoredReceipt(receipt: Receipt, teamId: string, recipientId: string, messageId: string): void {
+    if (receipt.teamId !== teamId || receipt.recipientId !== recipientId || receipt.messageId !== messageId) {
+      throw Object.assign(new Error('Receipt identity does not match its storage path.'), { code: 'CORRUPT_RECORD' });
+    }
+  }
+
+  async read(teamId: string, recipientId: string, messageId: string): Promise<Receipt | undefined> {
+    await this.prepare();
+    if (!await this.prepareRecipient(teamId, recipientId, false)) return undefined;
+    const receipt = await readJson(this.paths.receipt(teamId, recipientId, messageId), assertReceipt, RECEIPT_MAX_BYTES);
+    if (receipt) this.assertStoredReceipt(receipt, teamId, recipientId, messageId);
+    return receipt;
+  }
+
+  async record(receipt: Receipt): Promise<void> {
+    assertReceipt(receipt);
+    await this.prepare();
+    await withStorageLock(this.lockPath(receipt.teamId), async () => {
+      await this.prepareRecipient(receipt.teamId, receipt.recipientId, true);
+      const path = this.paths.receipt(receipt.teamId, receipt.recipientId, receipt.messageId);
+      const current = await readJson(path, assertReceipt, RECEIPT_MAX_BYTES);
+      if (!current) {
+        await createAtomicJson(path, receipt, RECEIPT_MAX_BYTES);
+        return;
+      }
+      this.assertStoredReceipt(current, receipt.teamId, receipt.recipientId, receipt.messageId);
+      if (current.status === receipt.status) return;
+      if (!transitions[current.status].includes(receipt.status)) {
+        throw Object.assign(new Error(`Invalid receipt transition: ${current.status} → ${receipt.status}.`), { code: 'INVALID_TRANSITION' });
+      }
+      if (timestampMillis(receipt.at, 'receipt timestamp') < timestampMillis(current.at, 'receipt timestamp')) {
+        throw new Error('Receipt timestamp moved backwards.');
+      }
+      await replaceAtomicJson(path, receipt, { maxBytes: RECEIPT_MAX_BYTES });
+    });
+  }
+
+  async list(teamId: string, recipientId: string, limit = 100, cursor?: string): Promise<readonly Receipt[]> {
+    assertTeamId(teamId);
+    assertEntityId(recipientId, 'recipient ID');
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) throw new Error('Receipt page limit must be between 1 and 100.');
+    if (cursor !== undefined) assertEntityId(cursor, 'receipt cursor');
+    await this.prepare();
+    if (!await this.prepareRecipient(teamId, recipientId, false)) return [];
+    const ids = await jsonFileNames(this.paths.recipientReceipts(teamId, recipientId), false);
+    const page = (cursor === undefined ? ids : ids.filter(id => id > cursor)).slice(0, limit);
+    const records = await Promise.all(page.map(id => this.read(teamId, recipientId, id)));
+    return records.filter((receipt): receipt is Receipt => receipt !== undefined);
+  }
+
+  async purgeExpired(teamId: string, recipientId: string): Promise<number> {
+    await this.prepare();
+    return withStorageLock(this.lockPath(teamId), async () => {
+      if (!await this.prepareRecipient(teamId, recipientId, false)) return 0;
+      const ids = await jsonFileNames(this.paths.recipientReceipts(teamId, recipientId), false);
+      const receipts = await Promise.all(ids.map(id => this.read(teamId, recipientId, id)));
+      const expired = receipts.filter((receipt): receipt is Receipt => receipt !== undefined && terminal.has(receipt.status) &&
+        this.now() - timestampMillis(receipt.at, 'receipt timestamp') >= this.terminalTtlMs);
+      await Promise.all(expired.map(receipt => removeAtomic(this.paths.receipt(teamId, recipientId, receipt.messageId))));
+      return expired.length;
+    });
+  }
+}

package/src/storage/team-store.ts

@@ -0,0 +1,190 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { assertMember, memberBelongsToTeam, type Member } from '../domain/member.ts';
+import { assertTeam, assertTeamId, assertTeamTransition, type Team } from '../domain/team.ts';
+import {
+  createAtomicJson, ensurePrivateDirectory, ensurePrivateTree, jsonFileNames, moveAtomic, readJson,
+  replaceAtomicJson, withStorageLock,
+} from './atomic.ts';
+import { TeamPaths } from './paths.ts';
+
+const TEAM_MAX_BYTES = 32 * 1024;
+const MEMBER_MAX_BYTES = 64 * 1024;
+
+export type TeamStoreOptions = {
+  readonly maxMembers?: number;
+};
+
+export class TeamStore {
+  readonly paths: TeamPaths;
+  private readonly maxMembers: number;
+
+  constructor(paths: TeamPaths, options: TeamStoreOptions = {}) {
+    this.paths = paths;
+    this.maxMembers = options.maxMembers ?? 100;
+    if (!Number.isSafeInteger(this.maxMembers) || this.maxMembers < 1) throw new Error('Invalid member quota.');
+  }
+
+  private async prepare(): Promise<void> {
+    await ensurePrivateTree(this.paths.root, 'teams');
+    await ensurePrivateTree(this.paths.root, 'control');
+  }
+
+  private async requireTeamDirectory(teamId: string): Promise<void> {
+    try {
+      await ensurePrivateDirectory(this.paths.team(teamId), false);
+      await ensurePrivateDirectory(this.paths.members(teamId), false);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw Object.assign(new Error(`Unknown team "${teamId}".`), { code: 'NOT_FOUND' });
+      }
+      throw error;
+    }
+  }
+
+  async create(team: Team): Promise<void> {
+    assertTeam(team);
+    await this.prepare();
+    await withStorageLock(this.paths.teamLock(team.teamId), async () => {
+      const target = this.paths.team(team.teamId);
+      const existing = await lstat(target).catch(error => {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+        throw error;
+      });
+      if (existing) throw Object.assign(new Error(`Team "${team.teamId}" already exists.`), { code: 'ALREADY_EXISTS' });
+      const temporary = join(this.paths.teams(), `.${team.teamId}.${randomUUID()}.tmp`);
+      await mkdir(temporary, { mode: 0o700 });
+      try {
+        await Promise.all(['members', 'runtimes', 'inbox', 'receipts', 'leases'].map(
+          name => ensurePrivateDirectory(join(temporary, name)),
+        ));
+        await createAtomicJson(join(temporary, 'team.json'), team, TEAM_MAX_BYTES);
+        await moveAtomic(temporary, target);
+      } catch (error) {
+        await rm(temporary, { recursive: true, force: true });
+        throw error;
+      }
+    });
+  }
+
+  async list(): Promise<string[]> {
+    await this.prepare();
+    const entries = await readdir(this.paths.teams(), { withFileTypes: true });
+    return entries
+      .filter(entry => entry.isDirectory() && !entry.isSymbolicLink())
+      .map(entry => entry.name)
+      .filter(name => {
+        try { assertTeamId(name); return true; }
+        catch { return false; }
+      })
+      .sort();
+  }
+
+  async read(teamId: string): Promise<Team | undefined> {
+    assertTeamId(teamId);
+    await this.prepare();
+    try { await this.requireTeamDirectory(teamId); }
+    catch (error) {
+      if ((error as { code?: string }).code === 'NOT_FOUND') return undefined;
+      throw error;
+    }
+    const team = await readJson(this.paths.teamRecord(teamId), assertTeam, TEAM_MAX_BYTES);
+    if (team && team.teamId !== teamId) throw Object.assign(new Error('Team ID does not match its storage path.'), { code: 'CORRUPT_RECORD' });
+    return team;
+  }
+
+  async update(teamId: string, change: (team: Team) => Team): Promise<Team> {
+    assertTeamId(teamId);
+    await this.prepare();
+    return withStorageLock(this.paths.teamLock(teamId), async () => {
+      await this.requireTeamDirectory(teamId);
+      const current = await readJson(this.paths.teamRecord(teamId), assertTeam, TEAM_MAX_BYTES);
+      if (!current) throw Object.assign(new Error(`Team "${teamId}" is incomplete or missing.`), { code: 'NOT_FOUND' });
+      const next = change(current);
+      assertTeam(next);
+      if (next.teamId !== current.teamId || next.createdAt !== current.createdAt) {
+        throw new Error('Team identity and creation timestamp are immutable.');
+      }
+      if (Date.parse(next.updatedAt) < Date.parse(current.updatedAt)) throw new Error('Team updatedAt moved backwards.');
+      assertTeamTransition(current.state, next.state);
+      await replaceAtomicJson(this.paths.teamRecord(teamId), next, { maxBytes: TEAM_MAX_BYTES, previous: true });
+      return next;
+    });
+  }
+
+  async createMember(member: Member): Promise<void> {
+    assertMember(member);
+    await this.prepare();
+    await withStorageLock(this.paths.teamLock(member.teamId), async () => {
+      await this.requireTeamDirectory(member.teamId);
+      const team = await readJson(this.paths.teamRecord(member.teamId), assertTeam, TEAM_MAX_BYTES);
+      if (!team) throw Object.assign(new Error(`Unknown team "${member.teamId}".`), { code: 'NOT_FOUND' });
+      if (team.state !== 'open') throw Object.assign(new Error(`Team "${member.teamId}" is ${team.state}.`), { code: 'TEAM_CLOSED' });
+      memberBelongsToTeam(member, team);
+      await ensurePrivateDirectory(this.paths.members(member.teamId));
+      const ids = await jsonFileNames(this.paths.members(member.teamId));
+      if (ids.length >= this.maxMembers) throw Object.assign(new Error(`Team member quota reached (${this.maxMembers}).`), { code: 'QUOTA_EXCEEDED' });
+      const members = await Promise.all(ids.map(id => readJson(this.paths.member(member.teamId, id), assertMember, MEMBER_MAX_BYTES)));
+      if (members.some(existing => existing?.alias === member.alias && existing.state === 'active')) {
+        throw Object.assign(new Error(`Member alias "${member.alias}" is already active.`), { code: 'ALREADY_EXISTS' });
+      }
+      await createAtomicJson(this.paths.member(member.teamId, member.memberId), member, MEMBER_MAX_BYTES);
+    });
+  }
+
+  async readMember(teamId: string, memberId: string): Promise<Member | undefined> {
+    await this.prepare();
+    try { await this.requireTeamDirectory(teamId); }
+    catch (error) {
+      if ((error as { code?: string }).code === 'NOT_FOUND') return undefined;
+      throw error;
+    }
+    const member = await readJson(this.paths.member(teamId, memberId), assertMember, MEMBER_MAX_BYTES);
+    if (member && (member.teamId !== teamId || member.memberId !== memberId)) {
+      throw Object.assign(new Error('Member identity does not match its storage path.'), { code: 'CORRUPT_RECORD' });
+    }
+    return member;
+  }
+
+  async listMembers(teamId: string): Promise<Member[]> {
+    assertTeamId(teamId);
+    await this.prepare();
+    await this.requireTeamDirectory(teamId);
+    const ids = await jsonFileNames(this.paths.members(teamId));
+    const members = await Promise.all(ids.map(id => this.readMember(teamId, id)));
+    return members.filter((member): member is Member => member !== undefined);
+  }
+
+  async updateMember(
+    teamId: string,
+    memberId: string,
+    expectedGeneration: number,
+    change: (member: Member) => Member,
+  ): Promise<Member> {
+    await this.prepare();
+    return withStorageLock(this.paths.teamLock(teamId), async () => {
+      await this.requireTeamDirectory(teamId);
+      const current = await this.readMember(teamId, memberId);
+      if (!current) throw Object.assign(new Error(`Unknown member "${memberId}".`), { code: 'NOT_FOUND' });
+      if (current.generation !== expectedGeneration) {
+        throw Object.assign(new Error('Member generation has changed.'), { code: 'FENCED' });
+      }
+      const next = change(current);
+      assertMember(next);
+      if (next.teamId !== current.teamId || next.memberId !== current.memberId || next.joinedAt !== current.joinedAt ||
+          next.generation < current.generation || next.generation > current.generation + 1) {
+        throw new Error('Invalid member identity or generation update.');
+      }
+      if (Date.parse(next.updatedAt) < Date.parse(current.updatedAt)) throw new Error('Member updatedAt moved backwards.');
+      if (next.state === 'active' && (next.alias !== current.alias || current.state !== 'active')) {
+        const members = await this.listMembers(teamId);
+        if (members.some(member => member.memberId !== memberId && member.alias === next.alias && member.state === 'active')) {
+          throw Object.assign(new Error(`Member alias "${next.alias}" is already active.`), { code: 'ALREADY_EXISTS' });
+        }
+      }
+      await replaceAtomicJson(this.paths.member(teamId, memberId), next, { maxBytes: MEMBER_MAX_BYTES, previous: true });
+      return next;
+    });
+  }
+}

package/src/supervisor/control-protocol.ts

@@ -0,0 +1,125 @@
+import { timingSafeEqual } from 'node:crypto';
+import { Type } from 'typebox';
+import { Value } from 'typebox/value';
+import { EntityIdSchema } from '../domain/team.ts';
+import type { OwnerIdentity } from './runtime-store.ts';
+
+export const CONTROL_PROTOCOL_VERSION = 1;
+export const MAX_CONTROL_FRAME_BYTES = 4 * 1024;
+export const MAX_CONTROL_BUFFER_BYTES = 8 * 1024;
+
+const BaseSchema = {
+  version: Type.Literal(CONTROL_PROTOCOL_VERSION),
+  runtimeId: EntityIdSchema,
+  seq: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+};
+
+const OwnedWorkerSchema = {
+  ...BaseSchema,
+  ownerEpoch: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+};
+
+const OwnerSchema = Type.Object({
+  ownerSessionId: EntityIdSchema,
+  ownerInstanceId: EntityIdSchema,
+  ownerProcessNonce: Type.String({ pattern: '^[a-f0-9]{64}$' }),
+  ownerEpoch: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+}, { additionalProperties: false });
+
+export const WorkerFrameSchema = Type.Union([
+  Type.Object({ ...BaseSchema, type: Type.Literal('hello'), token: Type.String({ minLength: 64, maxLength: 128 }), ownerProcessNonce: Type.String({ pattern: '^[a-f0-9]{64}$' }) }, { additionalProperties: false }),
+  Type.Object({ ...OwnedWorkerSchema, type: Type.Literal('ready') }, { additionalProperties: false }),
+  Type.Object({ ...OwnedWorkerSchema, type: Type.Literal('state'), state: Type.Union([Type.Literal('ready'), Type.Literal('busy')]), requestId: Type.Optional(EntityIdSchema) }, { additionalProperties: false }),
+  Type.Object({ ...OwnedWorkerSchema, type: Type.Literal('pong'), nonce: EntityIdSchema }, { additionalProperties: false }),
+  Type.Object({ ...OwnedWorkerSchema, type: Type.Literal('shutdown_ack') }, { additionalProperties: false }),
+]);
+
+export const SupervisorFrameSchema = Type.Union([
+  Type.Object({ ...BaseSchema, type: Type.Literal('hello_ack'), owner: OwnerSchema }, { additionalProperties: false }),
+  Type.Object({ ...BaseSchema, type: Type.Literal('ping'), nonce: EntityIdSchema }, { additionalProperties: false }),
+  Type.Object({ ...BaseSchema, type: Type.Literal('cancel_request'), requestId: EntityIdSchema }, { additionalProperties: false }),
+  Type.Object({ ...BaseSchema, type: Type.Literal('prepare_shutdown'), reason: Type.Union([Type.Literal('stop'), Type.Literal('close'), Type.Literal('reload_failed'), Type.Literal('owner_lost')]), deadlineAt: Type.String({ format: 'date-time' }) }, { additionalProperties: false }),
+]);
+
+export type WorkerFrame =
+  | { readonly version: 1; readonly type: 'hello'; readonly runtimeId: string; readonly seq: number; readonly token: string; readonly ownerProcessNonce: string }
+  | { readonly version: 1; readonly type: 'ready'; readonly runtimeId: string; readonly seq: number; readonly ownerEpoch: number }
+  | { readonly version: 1; readonly type: 'state'; readonly runtimeId: string; readonly seq: number; readonly ownerEpoch: number; readonly state: 'ready' | 'busy'; readonly requestId?: string }
+  | { readonly version: 1; readonly type: 'pong'; readonly runtimeId: string; readonly seq: number; readonly ownerEpoch: number; readonly nonce: string }
+  | { readonly version: 1; readonly type: 'shutdown_ack'; readonly runtimeId: string; readonly seq: number; readonly ownerEpoch: number };
+
+export type SupervisorFrame =
+  | { readonly version: 1; readonly type: 'hello_ack'; readonly runtimeId: string; readonly seq: number; readonly owner: OwnerIdentity }
+  | { readonly version: 1; readonly type: 'ping'; readonly runtimeId: string; readonly seq: number; readonly nonce: string }
+  | { readonly version: 1; readonly type: 'cancel_request'; readonly runtimeId: string; readonly seq: number; readonly requestId: string }
+  | { readonly version: 1; readonly type: 'prepare_shutdown'; readonly runtimeId: string; readonly seq: number; readonly reason: 'stop' | 'close' | 'reload_failed' | 'owner_lost'; readonly deadlineAt: string };
+
+export type WorkerFramePayload = WorkerFrame extends infer Frame
+  ? Frame extends WorkerFrame ? Omit<Frame, 'version' | 'runtimeId' | 'seq' | 'ownerEpoch'> : never
+  : never;
+export type SupervisorFramePayload = SupervisorFrame extends infer Frame
+  ? Frame extends SupervisorFrame ? Omit<Frame, 'version' | 'runtimeId' | 'seq'> : never
+  : never;
+
+export function assertWorkerFrame(value: unknown): asserts value is WorkerFrame {
+  if (!Value.Check(WorkerFrameSchema, value)) throw Object.assign(new Error('Invalid worker control frame.'), { code: 'INVALID_FRAME' });
+  const frame = value as WorkerFrame;
+  if (frame.type === 'state' && (frame.state === 'busy') !== (frame.requestId !== undefined)) {
+    throw Object.assign(new Error('Busy worker state requires exactly one request ID.'), { code: 'INVALID_FRAME' });
+  }
+}
+
+export function assertSupervisorFrame(value: unknown): asserts value is SupervisorFrame {
+  if (!Value.Check(SupervisorFrameSchema, value)) throw Object.assign(new Error('Invalid supervisor control frame.'), { code: 'INVALID_FRAME' });
+}
+
+export function controlTokenMatches(expected: string, received: string): boolean {
+  const left = Buffer.from(expected, 'utf8');
+  const right = Buffer.from(received, 'utf8');
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+export function encodeControlFrame(frame: WorkerFrame | SupervisorFrame): Buffer {
+  if (frame.type === 'hello' || frame.type === 'ready' || frame.type === 'state' || frame.type === 'pong' || frame.type === 'shutdown_ack') {
+    assertWorkerFrame(frame);
+  } else {
+    assertSupervisorFrame(frame);
+  }
+  const text = `${JSON.stringify(frame)}\n`;
+  if (Buffer.byteLength(text, 'utf8') > MAX_CONTROL_FRAME_BYTES) {
+    throw Object.assign(new Error('Control frame is too large.'), { code: 'FRAME_TOO_LARGE' });
+  }
+  return Buffer.from(text, 'utf8');
+}
+
+export class NdjsonFrameDecoder<T> {
+  private buffer = Buffer.alloc(0);
+
+  constructor(private readonly validate: (value: unknown) => asserts value is T) {}
+
+  push(chunk: Buffer): readonly T[] {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    if (this.buffer.length > MAX_CONTROL_BUFFER_BYTES) {
+      this.buffer = Buffer.alloc(0);
+      throw Object.assign(new Error('Control frame buffer is too large.'), { code: 'FRAME_TOO_LARGE' });
+    }
+    return this.drain([]);
+  }
+
+  private drain(frames: readonly T[]): readonly T[] {
+    const newline = this.buffer.indexOf(0x0a);
+    if (newline < 0) return frames;
+    const line = this.buffer.subarray(0, newline);
+    this.buffer = this.buffer.subarray(newline + 1);
+    if (line.length === 0) return this.drain(frames);
+    if (line.length + 1 > MAX_CONTROL_FRAME_BYTES) {
+      throw Object.assign(new Error('Control frame is too large.'), { code: 'FRAME_TOO_LARGE' });
+    }
+    const parsed = (() => {
+      try { return JSON.parse(line.toString('utf8')) as unknown; }
+      catch { throw Object.assign(new Error('Malformed control frame JSON.'), { code: 'INVALID_FRAME' }); }
+    })();
+    this.validate(parsed);
+    return this.drain([...frames, parsed]);
+  }
+}