@moretea-labs/forge 1.8.0 → 1.8.2

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/owned-resource-store.ts

@@ -0,0 +1,259 @@
+import { createHash, randomUUID } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync, readdirSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import {
+  ownedResourceLocator,
+  type OwnedResource,
+  type OwnedResourceKind,
+  type OwnedResourceLocator,
+  type RecordOwnedResourceInput,
+} from '../domain/owned-resource';
+import { ensureForgeInstanceIdentity } from './identity-store';
+
+function resourcesDir(controllerHome: string): string {
+  const dir = resolve(controllerHome, 'owned-resources');
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function resourcePath(controllerHome: string, resourceId: string): string {
+  const sanitized = resourceId.replace(/[^a-zA-Z0-9._-]/g, '_');
+  return join(resourcesDir(controllerHome), `${sanitized}.json`);
+}
+
+function validateOwnedResource(value: unknown): OwnedResource {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('record must be an object');
+  const resource = value as OwnedResource;
+  if (resource.schemaVersion !== 1 || !resource.resourceId || !resource.kind || !resource.targetRef) {
+    throw new Error('required resource identity is missing');
+  }
+  if (!resource.provenance?.creator || !resource.provenance.createdAt || !resource.retention?.intent || !resource.status || !resource.updatedAt) {
+    throw new Error('required ownership metadata is missing');
+  }
+  if (resource.cleanupCapable === true
+    && (!resource.ownerForgeInstanceId || !resource.locator?.kind || !resource.locator.value || !resource.identityFingerprint)) {
+    throw new Error('cleanup-capable resource lacks owner/locator/fingerprint');
+  }
+  return resource;
+}
+
+function readResourceFile(filePath: string): OwnedResource | undefined {
+  if (!existsSync(filePath)) return undefined;
+  try {
+    return validateOwnedResource(JSON.parse(readFileSync(filePath, 'utf8')));
+  } catch (error) {
+    throw new Error(`OWNED_RESOURCE_STORE_CORRUPT: ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function writeResourceFile(controllerHome: string, resource: OwnedResource): void {
+  const filePath = resourcePath(controllerHome, resource.resourceId);
+  const tmpPath = `${filePath}.${randomUUID()}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(resource, null, 2), 'utf8');
+  renameSync(tmpPath, filePath);
+}
+
+export function ownedResourceLocatorFingerprint(ownerForgeInstanceId: string, locator: OwnedResourceLocator): string {
+  const owner = ownerForgeInstanceId.trim();
+  if (!owner || !locator.kind || !locator.value.trim()) throw new Error('OWNED_RESOURCE_FINGERPRINT_IDENTITY_REQUIRED');
+  return createHash('sha256').update(`${owner}\0${locator.kind}\0${locator.value.trim()}`).digest('hex');
+}
+
+export function ownedFilesystemIdentityFingerprint(ownerForgeInstanceId: string, pathInput: string): string {
+  const path = resolve(pathInput);
+  if (!existsSync(path)) throw new Error(`OWNED_RESOURCE_FILESYSTEM_TARGET_MISSING: ${path}`);
+  const canonicalPath = realpathSync(path);
+  const stat = lstatSync(canonicalPath);
+  const kind = stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : stat.isSymbolicLink() ? 'symlink' : 'other';
+  return createHash('sha256').update([
+    ownerForgeInstanceId.trim(),
+    'filesystem_path',
+    canonicalPath,
+    String(stat.dev),
+    String(stat.ino),
+    kind,
+  ].join('\0')).digest('hex');
+}
+
+function resolvedIdentityFingerprint(
+  ownerForgeInstanceId: string,
+  locator: OwnedResourceLocator,
+  explicitFingerprint?: string,
+): string {
+  const explicit = explicitFingerprint?.trim();
+  if (explicit) return explicit;
+  if (locator.kind === 'filesystem_path') return ownedFilesystemIdentityFingerprint(ownerForgeInstanceId, locator.value);
+  return ownedResourceLocatorFingerprint(ownerForgeInstanceId, locator);
+}
+
+export interface OwnedResourceCleanupTargetInput {
+  resourceId: string;
+  kind: OwnedResourceKind;
+  targetRef?: string;
+  locator?: OwnedResourceLocator;
+  identityFingerprint?: string;
+}
+
+/**
+ * Cleanup authorization is an exact OwnedResource fact, never path shape or caller possession.
+ * Filesystem targets are re-fingerprinted immediately before mutation so a recycled path cannot
+ * inherit an older Forge ownership record.
+ */
+export function assertOwnedResourceCleanupTarget(
+  controllerHome: string,
+  input: OwnedResourceCleanupTargetInput,
+): OwnedResource {
+  const resource = getOwnedResource(controllerHome, input.resourceId);
+  if (!resource) throw new Error(`OWNED_RESOURCE_CLEANUP_AUTHORITY_MISSING: ${input.resourceId}`);
+  const currentInstance = ensureForgeInstanceIdentity({ controllerHome }).instanceId;
+  if (resource.ownerForgeInstanceId !== currentInstance) {
+    throw new Error(`OWNED_RESOURCE_OWNER_INSTANCE_MISMATCH: ${input.resourceId}`);
+  }
+  if (resource.cleanupCapable !== true) throw new Error(`OWNED_RESOURCE_NOT_CLEANUP_CAPABLE: ${input.resourceId}`);
+  if (resource.status === 'released') throw new Error(`OWNED_RESOURCE_ALREADY_RELEASED: ${input.resourceId}`);
+  if (resource.kind !== input.kind) throw new Error(`OWNED_RESOURCE_KIND_MISMATCH: ${input.resourceId}`);
+  if (input.targetRef?.trim() && resource.targetRef !== input.targetRef.trim()) {
+    throw new Error(`OWNED_RESOURCE_TARGET_MISMATCH: ${input.resourceId}`);
+  }
+  if (!resource.locator || !resource.identityFingerprint) throw new Error(`OWNED_RESOURCE_CLEANUP_IDENTITY_MISSING: ${input.resourceId}`);
+  const expectedLocator = input.locator ?? resource.locator;
+  if (expectedLocator.kind !== resource.locator.kind || expectedLocator.value.trim() !== resource.locator.value) {
+    throw new Error(`OWNED_RESOURCE_LOCATOR_MISMATCH: ${input.resourceId}`);
+  }
+  const observedFingerprint = input.identityFingerprint?.trim()
+    || (resource.locator.kind === 'filesystem_path'
+      ? ownedFilesystemIdentityFingerprint(currentInstance, resource.locator.value)
+      : ownedResourceLocatorFingerprint(currentInstance, expectedLocator));
+  if (observedFingerprint !== resource.identityFingerprint) {
+    throw new Error(`OWNED_RESOURCE_IDENTITY_FINGERPRINT_MISMATCH: ${input.resourceId}`);
+  }
+  return resource;
+}
+
+export function recordOwnedResource(controllerHome: string, input: RecordOwnedResourceInput): OwnedResource {
+  const now = new Date().toISOString();
+  const resourceId = input.resourceId || `res-${randomUUID()}`;
+  // Cleanup authority is target-safe: ownership is pinned to the ForgeInstance
+  // that created/adopted the resource, and the locator fingerprint follows the
+  // resource kind so a recycled path/id cannot be reclaimed as the same resource.
+  const ownerForgeInstanceId = input.ownerForgeInstanceId?.trim()
+    || ensureForgeInstanceIdentity({ controllerHome }).instanceId;
+  const locator = input.locator ?? ownedResourceLocator(input.kind, input.targetRef);
+  const identityFingerprint = resolvedIdentityFingerprint(ownerForgeInstanceId, locator, input.identityFingerprint);
+  const cleanupCapable = input.cleanupCapable ?? true;
+  const existing = readResourceFile(resourcePath(controllerHome, resourceId));
+  if (existing) {
+    const sameLocator = existing.kind === input.kind
+      && existing.ownerForgeInstanceId === ownerForgeInstanceId
+      && existing.locator?.kind === locator.kind
+      && existing.locator?.value === locator.value;
+    const sameIdentity = sameLocator && existing.identityFingerprint === identityFingerprint;
+    const legacyWeakFilesystemFingerprint = sameLocator
+      && locator.kind === 'filesystem_path'
+      && existing.identityFingerprint === ownedResourceLocatorFingerprint(ownerForgeInstanceId, locator)
+      && existing.identityFingerprint !== identityFingerprint;
+    if (legacyWeakFilesystemFingerprint) {
+      // Never bless a pre-upgrade path-only fingerprint as the identity of the
+      // currently observed inode. Preserve the historical record but retire its
+      // destructive authority; a newly created resource gets a new strong witness.
+      const downgraded: OwnedResource = { ...existing, cleanupCapable: false, updatedAt: now };
+      writeResourceFile(controllerHome, downgraded);
+      return downgraded;
+    }
+    if (!sameIdentity) throw new Error(`OWNED_RESOURCE_IDENTITY_CONFLICT: ${resourceId}`);
+    if (existing.cleanupCapable !== true && cleanupCapable === true) {
+      throw new Error(`OWNED_RESOURCE_CLEANUP_AUTHORITY_ESCALATION_FORBIDDEN: ${resourceId}`);
+    }
+    if (existing.status === 'released') throw new Error(`OWNED_RESOURCE_REUSE_REQUIRES_NEW_ID: ${resourceId}`);
+  }
+  const resource: OwnedResource = {
+    schemaVersion: 1,
+    resourceId,
+    kind: input.kind,
+    targetRef: input.targetRef,
+    ownerForgeInstanceId,
+    locator,
+    identityFingerprint,
+    cleanupCapable,
+    provenance: {
+      creator: input.creator,
+      createdAt: now,
+      associatedWorkId: input.associatedWorkId,
+      associatedRequirementId: input.associatedRequirementId,
+      repoId: input.repoId,
+    },
+    retention: {
+      intent: input.retentionIntent ?? 'temporary',
+      expiresAt: input.expiresAt,
+    },
+    status: 'active',
+    updatedAt: now,
+  };
+
+  writeResourceFile(controllerHome, resource);
+  return resource;
+}
+
+export function getOwnedResource(controllerHome: string, resourceId: string): OwnedResource | undefined {
+  return readResourceFile(resourcePath(controllerHome, resourceId));
+}
+
+export function listOwnedResources(controllerHome: string, filter?: { kind?: string; status?: string; repoId?: string }): OwnedResource[] {
+  const dir = resourcesDir(controllerHome);
+  const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const results: OwnedResource[] = [];
+
+  for (const file of files) {
+    const resource = readResourceFile(join(dir, file));
+    if (!resource) continue;
+    if (filter?.kind && resource.kind !== filter.kind) continue;
+    if (filter?.status && resource.status !== filter.status) continue;
+    if (filter?.repoId && resource.provenance.repoId !== filter.repoId) continue;
+    results.push(resource);
+  }
+
+  return results.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+/** Mark an owned resource as intentionally retained without changing cleanup authority. */
+export function markOwnedResourceRetained(
+  controllerHome: string,
+  resourceId: string,
+): OwnedResource | undefined {
+  const existing = getOwnedResource(controllerHome, resourceId);
+  if (!existing) return undefined;
+  const updated: OwnedResource = {
+    ...existing,
+    status: 'retained',
+    updatedAt: new Date().toISOString(),
+  };
+  writeResourceFile(controllerHome, updated);
+  return updated;
+}
+
+export function markOwnedResourceCleaned(
+  controllerHome: string,
+  resourceId: string,
+  cleanedBy: string,
+  receiptRef?: string,
+): OwnedResource | undefined {
+  const existing = getOwnedResource(controllerHome, resourceId);
+  if (!existing) return undefined;
+
+  const now = new Date().toISOString();
+  const updated: OwnedResource = {
+    ...existing,
+    status: 'released',
+    updatedAt: now,
+    cleanupProof: {
+      cleanedAt: now,
+      cleanedBy,
+      receiptRef,
+    },
+  };
+
+  writeResourceFile(controllerHome, updated);
+  return updated;
+}