@moretea-labs/forge 1.7.2 → 1.8.1

package/packages/kernel/identity/domain/user-request.ts

@@ -0,0 +1,93 @@
+export type UserRequestKind = 'user_action_request' | 'user_decision_request';
+
+export type UserActionRequired =
+  | 'login'
+  | 'grant_permission'
+  | 'confirm_destructive'
+  | 'product_decision';
+
+export interface UserRequestTargetScope {
+  scopeKind: string;
+  scopeId: string;
+  repoId?: string;
+  workId?: string;
+  requirementId?: string;
+}
+
+export interface UserRequestOption {
+  id: string;
+  label: string;
+  description?: string;
+}
+
+export interface UserRequestPresentation {
+  /** Compatibility lookup key for legacy Handoff callers; never a second authority. */
+  legacyHandoffId?: string;
+  severity?: 'info' | 'needs_review' | 'blocked' | 'failed' | 'ready_to_continue';
+  creationReason?: string;
+  reason?: string;
+  currentState?: Record<string, unknown>;
+  attemptedActions?: string[];
+  evidenceRefs?: Array<{ title: string; summary?: string; detailLevel?: 'summary' | 'detail' | 'raw' }>;
+  blockingDecision?: string;
+  recommendedDecision?: string;
+  recommendedPrompt?: string;
+  recommendedContinuationPrompt?: string;
+  approvalAction?: {
+    operation: 'start' | 'repair';
+    label: string;
+    summary: string;
+    risk: string;
+    payload: Record<string, unknown>;
+  };
+  suggestedNextActions?: Array<{
+    label: string;
+    tool?: string;
+    operation?: string;
+    payload?: Record<string, unknown>;
+    risk?: string;
+    confidence?: string;
+    reason?: string;
+  }>;
+}
+
+export interface UserRequest {
+  schemaVersion: 1;
+  requestId: string;
+  kind: UserRequestKind;
+  rootCauseKey: string;
+  title: string;
+  summary: string;
+  actionRequired: UserActionRequired;
+  targetScope?: UserRequestTargetScope;
+  options?: UserRequestOption[];
+  presentation?: UserRequestPresentation;
+  status: 'pending' | 'resolved' | 'cancelled';
+  resolution?: {
+    decision: string;
+    resolvedBy: string;
+    resolvedAt: string;
+  };
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateUserRequestInput {
+  requestId?: string;
+  kind: UserRequestKind;
+  rootCauseKey: string;
+  title: string;
+  summary: string;
+  actionRequired: UserActionRequired;
+  targetScope?: UserRequestTargetScope;
+  options?: UserRequestOption[];
+  presentation?: UserRequestPresentation;
+  now?: Date;
+}
+
+export interface ResolveUserRequestInput {
+  requestId: string;
+  decision: string;
+  resolvedBy: string;
+  now?: Date;
+}

package/packages/kernel/identity/domain/workspace.ts

@@ -0,0 +1,56 @@
+/** Portable Workspace/Project identity. Repository registration is node-local placement, never semantic identity. */
+export interface WorkspaceIdentity {
+  schemaVersion: 1;
+  workspaceId: string;
+  title: string;
+}
+
+export interface ProjectIdentity {
+  schemaVersion: 1;
+  projectId: string;
+  workspaceId: string;
+  displayName: string;
+  /** Stable digest of a portable source identity (for example a normalized Git remote), never a local path. */
+  sourceFingerprint?: string;
+}
+
+/** Node-local mapping from one portable Project to the repository/checkout used by this ForgeInstance. Never sync this record. */
+export interface ProjectPlacement {
+  schemaVersion: 1;
+  projectId: string;
+  forgeInstanceId: string;
+  repositoryId: string;
+  checkoutId?: string;
+}
+
+function boundedId(value: string, code: string): string {
+  const normalized = value.trim();
+  if (!normalized || normalized.length > 512) throw new Error(code);
+  return normalized;
+}
+
+export function workspaceIdentity(input: Omit<WorkspaceIdentity, 'schemaVersion'>): WorkspaceIdentity {
+  const workspaceId = boundedId(input.workspaceId, 'WORKSPACE_ID_INVALID');
+  const title = input.title.trim();
+  if (!title || title.length > 512) throw new Error('WORKSPACE_TITLE_INVALID');
+  return { schemaVersion: 1, workspaceId, title };
+}
+
+export function projectIdentity(input: Omit<ProjectIdentity, 'schemaVersion'>): ProjectIdentity {
+  const projectId = boundedId(input.projectId, 'PROJECT_ID_INVALID');
+  const workspaceId = boundedId(input.workspaceId, 'WORKSPACE_ID_INVALID');
+  const displayName = input.displayName.trim();
+  if (!displayName || displayName.length > 512) throw new Error('PROJECT_DISPLAY_NAME_INVALID');
+  const sourceFingerprint = input.sourceFingerprint?.trim();
+  if (sourceFingerprint && !/^[a-f0-9]{64}$/i.test(sourceFingerprint)) throw new Error('PROJECT_SOURCE_FINGERPRINT_INVALID');
+  return { schemaVersion: 1, projectId, workspaceId, displayName, ...(sourceFingerprint ? { sourceFingerprint: sourceFingerprint.toLowerCase() } : {}) };
+}
+
+export function projectPlacement(input: Omit<ProjectPlacement, 'schemaVersion'>): ProjectPlacement {
+  const projectId = boundedId(input.projectId, 'PROJECT_ID_INVALID');
+  const forgeInstanceId = boundedId(input.forgeInstanceId, 'FORGE_INSTANCE_ID_INVALID');
+  const repositoryId = boundedId(input.repositoryId, 'PROJECT_REPOSITORY_ID_INVALID');
+  const checkoutId = input.checkoutId?.trim();
+  if (checkoutId && checkoutId.length > 512) throw new Error('PROJECT_CHECKOUT_ID_INVALID');
+  return { schemaVersion: 1, projectId, forgeInstanceId, repositoryId, ...(checkoutId ? { checkoutId } : {}) };
+}

package/packages/kernel/identity/index.ts

@@ -0,0 +1 @@
+export * from './api/index';

package/packages/kernel/identity/infrastructure/activity-projection-store.ts

@@ -0,0 +1,77 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, readdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type { CapabilityActivityItem, UnifiedActivityView, WorkTreeProjectionNode } from '../domain/activity-projection';
+
+function activityDir(controllerHome: string): string {
+  const dir = resolve(controllerHome, 'activity-projection');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function activityFilePath(controllerHome: string, activityId: string): string {
+  const sanitized = activityId.replace(/[^a-zA-Z0-9._-]/g, '_');
+  return join(activityDir(controllerHome), `${sanitized}.json`);
+}
+
+export function recordDirectActivity(
+  controllerHome: string,
+  input: Omit<CapabilityActivityItem, 'activityId' | 'startedAt'> & { activityId?: string; startedAt?: string },
+): CapabilityActivityItem {
+  const now = new Date().toISOString();
+  const activityId = input.activityId || `act-${randomUUID()}`;
+  const item: CapabilityActivityItem = {
+    ...input,
+    activityId,
+    startedAt: input.startedAt ?? now,
+  };
+
+  const filePath = activityFilePath(controllerHome, activityId);
+  const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(item, null, 2), 'utf8');
+  renameSync(tmpPath, filePath);
+
+  return item;
+}
+
+export function listDirectActivities(controllerHome: string, limit = 50): CapabilityActivityItem[] {
+  const dir = activityDir(controllerHome);
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const items: CapabilityActivityItem[] = [];
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(join(dir, file), 'utf8');
+      items.push(JSON.parse(content) as CapabilityActivityItem);
+    } catch {
+      // ignore corrupted file
+    }
+  }
+
+  return items
+    .sort((a, b) => b.startedAt.localeCompare(a.startedAt))
+    .slice(0, limit);
+}
+
+/**
+ * Project unified activity view combining WorkTree with direct capability activities.
+ * Direct capability activity that has no Work appears in directActivities rather than
+ * being forced into synthetic Work.
+ */
+export function projectUnifiedActivityView(
+  controllerHome: string,
+  workTreeNodes: WorkTreeProjectionNode[],
+  limitDirect = 50,
+): UnifiedActivityView {
+  const directActivities = listDirectActivities(controllerHome, limitDirect);
+  const now = new Date();
+
+  return {
+    workTree: workTreeNodes,
+    directActivities: directActivities.filter((act) => !act.associatedWorkId),
+    observedAt: now.toISOString(),
+    freshnessMs: 0,
+  };
+}

package/packages/kernel/identity/infrastructure/capability-broker.ts

@@ -0,0 +1,81 @@
+import { randomUUID } from 'crypto';
+import type {
+  CapabilityInvocationInput,
+  CapabilityInvocationResult,
+  CapabilityTypedHandle,
+} from '../domain/capability-broker';
+import { findActiveCanonicalGrant } from './grant-store';
+
+type CapabilityHandler<TArgs = any, TResult = any> = (
+  input: CapabilityInvocationInput<TArgs>,
+) => Promise<CapabilityInvocationResult<TResult>> | CapabilityInvocationResult<TResult>;
+
+class CapabilityRegistry {
+  private handlers = new Map<string, CapabilityHandler>();
+
+  register<TArgs = any, TResult = any>(capabilityId: string, handler: CapabilityHandler<TArgs, TResult>): void {
+    this.handlers.set(capabilityId, handler);
+  }
+
+  get(capabilityId: string): CapabilityHandler | undefined {
+    return this.handlers.get(capabilityId);
+  }
+
+  has(capabilityId: string): boolean {
+    return this.handlers.has(capabilityId);
+  }
+}
+
+export const canonicalCapabilityRegistry = new CapabilityRegistry();
+
+/**
+ * Broker invocation: verifies canonical grant authorization (if required),
+ * validates invocation parameters, and dispatches mechanically without
+ * inferring engineering method or forcing Plan/Work lifecycle.
+ */
+export async function invokeCapability<TArgs = any, TResult = any>(
+  controllerHome: string,
+  input: CapabilityInvocationInput<TArgs>,
+  options: { checkAuthorization?: boolean } = { checkAuthorization: true },
+): Promise<CapabilityInvocationResult<TResult>> {
+  if (options.checkAuthorization) {
+    const grant = findActiveCanonicalGrant(controllerHome, {
+      principalId: input.principalId,
+      capability: input.capabilityId,
+      risk: 'readonly', // base check; fine-grained capability implementations check specific risk
+    });
+    // In local non-interactive automation mode, allow if principal is system/controller or grant exists
+    if (!grant && !['system', 'controller', 'chatgpt-controller', 'claude-controller', 'codex-controller'].includes(input.principalId)) {
+      return {
+        success: false,
+        error: {
+          code: 'UNAUTHORIZED_CAPABILITY',
+          message: `Principal ${input.principalId} lacks active grant for capability ${input.capabilityId}`,
+        },
+      };
+    }
+  }
+
+  const handler = canonicalCapabilityRegistry.get(input.capabilityId);
+  if (!handler) {
+    return {
+      success: false,
+      error: {
+        code: 'CAPABILITY_NOT_FOUND',
+        message: `Capability ${input.capabilityId} is not registered in the broker`,
+      },
+    };
+  }
+
+  try {
+    return await handler(input);
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        code: 'CAPABILITY_EXECUTION_ERROR',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}

package/packages/kernel/identity/infrastructure/grant-store.ts

@@ -0,0 +1,284 @@
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type {
+  Grant,
+  GrantTarget,
+  QueryGrantInput,
+  ReconcileGrantsInput,
+  ReconcileGrantsResult,
+  RecordGrantInput,
+  RevokeGrantInput,
+} from '../domain/grant';
+import type { ScopeRef } from '../domain/scope';
+
+export const DEFAULT_GRANT_MINUTES = 30 * 24 * 60;
+const MAX_GRANT_MINUTES = 90 * 24 * 60;
+
+interface GrantStoreData {
+  schemaVersion: 1;
+  grants: Grant[];
+}
+
+const RISK_RANK: Record<string, number> = {
+  readonly: 0,
+  workspace_write: 1,
+  remote_write: 2,
+  destructive: 3,
+};
+
+export function canonicalGrantStorePath(controllerHome: string): string {
+  return join(resolve(controllerHome), 'system', 'authorization-grants', 'grants.json');
+}
+
+const GRANT_RISKS = new Set(['readonly', 'workspace_write', 'remote_write', 'destructive']);
+const SCOPE_KINDS = new Set(['workspace', 'project', 'requirement', 'plan', 'plan_step', 'work']);
+
+function validateGrantTarget(value: unknown, label: string): GrantTarget | undefined {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const target = value as Record<string, unknown>;
+  const kind = typeof target.kind === 'string' ? target.kind.trim() : '';
+  const id = typeof target.id === 'string' ? target.id.trim() : '';
+  if (!kind || !id) throw new Error(`${label}.kind/id are required`);
+  const optionalString = (field: 'repoId' | 'identityFingerprint') => {
+    const current = target[field];
+    if (current === undefined) return undefined;
+    if (typeof current !== 'string' || !current.trim()) throw new Error(`${label}.${field} is invalid`);
+    return current.trim();
+  };
+  let scopeRef: GrantTarget['scopeRef'];
+  if (target.scopeRef !== undefined) {
+    if (!target.scopeRef || typeof target.scopeRef !== 'object' || Array.isArray(target.scopeRef)) throw new Error(`${label}.scopeRef is invalid`);
+    const scope = target.scopeRef as Record<string, unknown>;
+    const scopeKind = typeof scope.kind === 'string' ? scope.kind.trim() : '';
+    const scopeId = typeof scope.id === 'string' ? scope.id.trim() : '';
+    if (scope.schemaVersion !== 1 || !SCOPE_KINDS.has(scopeKind) || !scopeId) throw new Error(`${label}.scopeRef is invalid`);
+    scopeRef = { schemaVersion: 1, kind: scopeKind as ScopeRef['kind'], id: scopeId };
+  }
+  const repoId = optionalString('repoId');
+  const identityFingerprint = optionalString('identityFingerprint');
+  return { kind, id, ...(repoId ? { repoId } : {}), ...(scopeRef ? { scopeRef } : {}), ...(identityFingerprint ? { identityFingerprint } : {}) };
+}
+
+function validatePersistedGrant(value: unknown, index: number): Grant {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`grants[${index}] must be an object`);
+  const row = value as Record<string, unknown>;
+  const requiredString = (field: string) => {
+    const current = row[field];
+    if (typeof current !== 'string' || !current.trim()) throw new Error(`grants[${index}].${field} is invalid`);
+    return current.trim();
+  };
+  if (row.schemaVersion !== 1) throw new Error(`grants[${index}].schemaVersion is invalid`);
+  if (!Array.isArray(row.capabilities) || row.capabilities.some((entry) => typeof entry !== 'string' || !entry.trim())) throw new Error(`grants[${index}].capabilities is invalid`);
+  if (row.scopes !== undefined && (!Array.isArray(row.scopes) || row.scopes.some((entry) => typeof entry !== 'string' || !entry.trim()))) throw new Error(`grants[${index}].scopes is invalid`);
+  if (row.riskCeiling !== undefined && (typeof row.riskCeiling !== 'string' || !GRANT_RISKS.has(row.riskCeiling))) throw new Error(`grants[${index}].riskCeiling is invalid`);
+  const createdAt = requiredString('createdAt');
+  const updatedAt = requiredString('updatedAt');
+  const expiresAt = requiredString('expiresAt');
+  if (![createdAt, updatedAt, expiresAt].every((timestamp) => Number.isFinite(Date.parse(timestamp)))) throw new Error(`grants[${index}] timestamps are invalid`);
+  const revokedAt = row.revokedAt;
+  if (revokedAt !== undefined && (typeof revokedAt !== 'string' || !Number.isFinite(Date.parse(revokedAt)))) throw new Error(`grants[${index}].revokedAt is invalid`);
+  if (row.revokedReason !== undefined && typeof row.revokedReason !== 'string') throw new Error(`grants[${index}].revokedReason is invalid`);
+  if (row.ownerScope !== undefined && (typeof row.ownerScope !== 'string' || !row.ownerScope.trim())) throw new Error(`grants[${index}].ownerScope is invalid`);
+  if (row.constraints !== undefined && (!row.constraints || typeof row.constraints !== 'object' || Array.isArray(row.constraints))) throw new Error(`grants[${index}].constraints is invalid`);
+  const target = validateGrantTarget(row.target, `grants[${index}].target`);
+  return {
+    schemaVersion: 1,
+    grantId: requiredString('grantId'),
+    principalId: requiredString('principalId'),
+    ...(typeof row.ownerScope === 'string' && row.ownerScope.trim() ? { ownerScope: row.ownerScope.trim() } : {}),
+    capabilities: [...new Set((row.capabilities as string[]).map((entry) => entry.trim()))].sort(),
+    ...(target ? { target } : {}),
+    ...(Array.isArray(row.scopes) ? { scopes: [...new Set((row.scopes as string[]).map((entry) => entry.trim()))].sort() } : {}),
+    ...(typeof row.riskCeiling === 'string' ? { riskCeiling: row.riskCeiling as Grant['riskCeiling'] } : {}),
+    ...(row.constraints && typeof row.constraints === 'object' && !Array.isArray(row.constraints) ? { constraints: row.constraints as Record<string, unknown> } : {}),
+    createdAt,
+    updatedAt,
+    expiresAt,
+    ...(typeof revokedAt === 'string' ? { revokedAt } : {}),
+    ...(typeof row.revokedReason === 'string' ? { revokedReason: row.revokedReason } : {}),
+  };
+}
+
+function loadStore(controllerHome: string): GrantStoreData {
+  const path = canonicalGrantStorePath(controllerHome);
+  if (!existsSync(path)) return { schemaVersion: 1, grants: [] };
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('store must be an object');
+    const record = raw as Record<string, unknown>;
+    if (record.schemaVersion !== 1 || !Array.isArray(record.grants)) throw new Error('schemaVersion/grants are invalid');
+    return { schemaVersion: 1, grants: record.grants.map(validatePersistedGrant) };
+  } catch (error) {
+    throw new Error(`CANONICAL_GRANT_STORE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function saveStore(controllerHome: string, store: GrantStoreData): void {
+  const path = canonicalGrantStorePath(controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(store, null, 2)}\n`, 'utf8');
+  renameSync(temporary, path);
+}
+
+function targetMatches(left?: GrantTarget, right?: GrantTarget): boolean {
+  if (!left && !right) return true;
+  if (!left || !right) return false;
+  const scopeMatch = (!left.scopeRef && !right.scopeRef)
+    || Boolean(left.scopeRef && right.scopeRef
+      && left.scopeRef.schemaVersion === right.scopeRef.schemaVersion
+      && left.scopeRef.kind === right.scopeRef.kind
+      && left.scopeRef.id === right.scopeRef.id);
+  return left.kind === right.kind
+    && left.id === right.id
+    && left.repoId === right.repoId
+    && left.identityFingerprint === right.identityFingerprint
+    && scopeMatch;
+}
+
+function scopesContain(granted: readonly string[] = [], requested: readonly string[] = []): boolean {
+  const available = new Set(granted);
+  return requested.every((scope) => available.has(scope));
+}
+
+function capabilityMatches(grantedCapabilities: readonly string[], requested: string): boolean {
+  if (grantedCapabilities.includes('*') || grantedCapabilities.includes(requested)) return true;
+  if (requested.includes(':')) {
+    const prefix = requested.split(':')[0] + ':*';
+    if (grantedCapabilities.includes(prefix)) return true;
+  }
+  return false;
+}
+
+export function recordCanonicalGrant(controllerHome: string, input: RecordGrantInput): Grant {
+  const now = input.now ?? new Date();
+  const timestamp = now.toISOString();
+  const expiresInMinutes = Math.min(
+    Math.max(1, Math.trunc(input.expiresInMinutes ?? DEFAULT_GRANT_MINUTES)),
+    MAX_GRANT_MINUTES,
+  );
+  const grantId = input.grantId?.trim() || `grant_${randomUUID().replaceAll('-', '')}`;
+  const grant: Grant = {
+    schemaVersion: 1,
+    grantId,
+    principalId: input.principalId.trim(),
+    ...(input.ownerScope?.trim() ? { ownerScope: input.ownerScope.trim() } : {}),
+    capabilities: [...new Set(input.capabilities.map((c) => c.trim()).filter(Boolean))].sort(),
+    ...(input.target ? { target: input.target } : {}),
+    ...(input.scopes ? { scopes: [...new Set(input.scopes.map((s) => s.trim()).filter(Boolean))].sort() } : {}),
+    ...(input.riskCeiling ? { riskCeiling: input.riskCeiling } : {}),
+    ...(input.constraints ? { constraints: input.constraints } : {}),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+    expiresAt: new Date(now.getTime() + expiresInMinutes * 60_000).toISOString(),
+  };
+
+  const store = loadStore(controllerHome);
+  store.grants = store.grants.filter((entry) => {
+    if (entry.grantId === grantId) return false;
+    const samePrincipal = entry.principalId === grant.principalId;
+    const sameOwner = entry.ownerScope === grant.ownerScope;
+    const sameTarget = targetMatches(entry.target, grant.target);
+    const sameCapabilities = entry.capabilities.length === grant.capabilities.length
+      && entry.capabilities.every((c, i) => c === grant.capabilities[i]);
+    return !(samePrincipal && sameOwner && sameTarget && sameCapabilities);
+  });
+  store.grants.push(grant);
+  saveStore(controllerHome, store);
+  return grant;
+}
+
+export function revokeCanonicalGrant(controllerHome: string, input: RevokeGrantInput): Grant {
+  const grantId = input.grantId.trim();
+  const now = input.now ?? new Date();
+  const store = loadStore(controllerHome);
+  const index = store.grants.findIndex((g) => g.grantId === grantId);
+  if (index < 0) throw new Error(`GRANT_NOT_FOUND: ${grantId}`);
+  const current = store.grants[index]!;
+  if (input.ownerScope && current.ownerScope && current.ownerScope !== input.ownerScope.trim()) {
+    throw new Error(`GRANT_OWNER_MISMATCH: ${grantId}`);
+  }
+  const revoked: Grant = {
+    ...current,
+    updatedAt: now.toISOString(),
+    revokedAt: now.toISOString(),
+    revokedReason: input.reason.trim(),
+  };
+  store.grants[index] = revoked;
+  saveStore(controllerHome, store);
+  return revoked;
+}
+
+export function findActiveCanonicalGrant(controllerHome: string, query: QueryGrantInput): Grant | undefined {
+  const store = loadStore(controllerHome);
+  const nowMs = (query.at ?? new Date()).getTime();
+  const requestedRiskRank = RISK_RANK[query.risk ?? 'readonly'] ?? 0;
+
+  for (const grant of store.grants) {
+    if (grant.revokedAt) continue;
+    if (Date.parse(grant.expiresAt) <= nowMs) continue;
+    if (query.principalId && grant.principalId !== query.principalId.trim()) continue;
+    if (query.ownerScope && grant.ownerScope && grant.ownerScope !== query.ownerScope.trim()) continue;
+    if (!capabilityMatches(grant.capabilities, query.capability)) continue;
+    if (query.target && !targetMatches(grant.target, query.target)) continue;
+    if (query.scopes && !scopesContain(grant.scopes, query.scopes)) continue;
+    if (grant.riskCeiling) {
+      const grantRiskRank = RISK_RANK[grant.riskCeiling] ?? 0;
+      if (grantRiskRank < requestedRiskRank) continue;
+    }
+    return structuredClone(grant);
+  }
+  return undefined;
+}
+
+export function listCanonicalGrants(controllerHome: string, filter?: { principalId?: string; ownerScope?: string }): Grant[] {
+  const store = loadStore(controllerHome);
+  return store.grants
+    .filter((grant) => {
+      if (filter?.principalId && grant.principalId !== filter.principalId.trim()) return false;
+      if (filter?.ownerScope && grant.ownerScope !== filter.ownerScope.trim()) return false;
+      return true;
+    })
+    .map((grant) => structuredClone(grant));
+}
+
+export function reconcileCanonicalGrants(controllerHome: string, input: ReconcileGrantsInput = {}): ReconcileGrantsResult {
+  const retiredOwnerScopes = new Set((input.retiredOwnerScopes ?? []).map((s) => s.trim()).filter(Boolean));
+  const nowMs = (input.now ?? new Date()).getTime();
+  const store = loadStore(controllerHome);
+  let removedRetiredOwner = 0;
+  let removedRevoked = 0;
+  let removedExpired = 0;
+
+  const grants = store.grants.filter((grant) => {
+    if (grant.ownerScope && retiredOwnerScopes.has(grant.ownerScope)) {
+      removedRetiredOwner += 1;
+      return false;
+    }
+    if (grant.revokedAt) {
+      removedRevoked += 1;
+      return false;
+    }
+    if (Date.parse(grant.expiresAt) <= nowMs) {
+      removedExpired += 1;
+      return false;
+    }
+    return true;
+  });
+
+  const removedTotal = removedRetiredOwner + removedRevoked + removedExpired;
+  if (removedTotal > 0) {
+    store.grants = grants;
+    saveStore(controllerHome, store);
+  }
+  return {
+    removedRetiredOwner,
+    removedRevoked,
+    removedExpired,
+    removedTotal,
+    remaining: grants.length,
+    changed: removedTotal > 0,
+  };
+}

package/packages/kernel/identity/infrastructure/identity-store.ts

@@ -0,0 +1,75 @@
+import { randomUUID } from 'crypto';
+import { closeSync, existsSync, fsyncSync, linkSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import type { ForgeInstanceIdentity } from '../domain/types';
+
+export interface ForgeIdentityStoreOptions {
+  controllerHome: string;
+  now?: () => string;
+  preferredInstanceId?: string;
+  label?: string;
+}
+
+function normalizedInstanceId(value: string | undefined): string | undefined {
+  const id = value?.trim();
+  if (!id) return undefined;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{2,191}$/.test(id)) throw new Error('FORGE_INSTANCE_ID_INVALID');
+  return id;
+}
+
+export function forgeInstanceIdentityPath(controllerHome: string): string {
+  return join(resolve(controllerHome), 'identity', 'forge-instance.json');
+}
+
+export function readForgeInstanceIdentity(controllerHome: string): ForgeInstanceIdentity | undefined {
+  const path = forgeInstanceIdentityPath(controllerHome);
+  if (!existsSync(path)) return undefined;
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8')) as ForgeInstanceIdentity;
+    if (value.schemaVersion !== 1 || !normalizedInstanceId(value.instanceId) || typeof value.createdAt !== 'string') return undefined;
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
+export function ensureForgeInstanceIdentity(options: ForgeIdentityStoreOptions): ForgeInstanceIdentity {
+  const existing = readForgeInstanceIdentity(options.controllerHome);
+  const preferred = normalizedInstanceId(options.preferredInstanceId);
+  if (existing) {
+    if (preferred && existing.instanceId !== preferred) {
+      throw new Error(`FORGE_INSTANCE_ID_MISMATCH: existing=${existing.instanceId} requested=${preferred}`);
+    }
+    return existing;
+  }
+  const path = forgeInstanceIdentityPath(options.controllerHome);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const identity: ForgeInstanceIdentity = {
+    schemaVersion: 1,
+    instanceId: preferred ?? `forge_${randomUUID().replaceAll('-', '')}`,
+    createdAt: (options.now ?? (() => new Date().toISOString()))(),
+    ...(options.label?.trim() ? { label: options.label.trim().slice(0, 160) } : {}),
+  };
+  const temporary = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    writeFileSync(fd, `${JSON.stringify(identity, null, 2)}\n`, 'utf8');
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  try {
+    // link() is atomic and refuses to replace an existing semantic identity.
+    linkSync(temporary, path);
+    unlinkSync(temporary);
+    return identity;
+  } catch (error) {
+    try { unlinkSync(temporary); } catch { /* best effort */ }
+    const raced = readForgeInstanceIdentity(options.controllerHome);
+    if (raced) {
+      if (preferred && raced.instanceId !== preferred) throw new Error(`FORGE_INSTANCE_ID_MISMATCH: existing=${raced.instanceId} requested=${preferred}`);
+      return raced;
+    }
+    throw error;
+  }
+}