evolcore 0.0.35 → 0.0.36

package/dist/core/ownership/owner-resolver.js

@@ -0,0 +1,687 @@
+import fs from 'fs';
+import path from 'path';
+import { resolvePaths } from '../../paths.js';
+import { isValidAid } from '../../aun/aid/validation.js';
+import { atomicReadJson, atomicWriteJson } from '../../utils/atomic-write.js';
+import { configuredOwnerList as readConfiguredOwnerList } from '../../config/owner-config.js';
+import { logger } from '../../utils/logger.js';
+import { hasTrustedPrincipal } from '../auth/authenticated-actor.js';
+export const OWNERSHIP_CACHE_MAX_AGE_MS = 30 * 60_000;
+export const OWNERSHIP_AUTHORIZATION_MAX_AGE_MS = 5 * 60_000;
+const OWNERSHIP_PENDING_REFRESH_MS = 5_000;
+const CREATION_BIND_OPERATION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Only use the task returned by this create's bind call. Never select a latest task. */
+export function creationOwnershipBinding(task, subjectAid, ownerAid) {
+    if (!isValidAid(subjectAid) || !isValidAid(ownerAid)
+        || !task || typeof task !== 'object' || Array.isArray(task))
+        return undefined;
+    const t = task;
+    if (t.operation !== 'bind' || t.sub_aid !== subjectAid || t.owner_aid !== ownerAid
+        || t.new_owner_aid !== undefined || subjectAid === ownerAid
+        || typeof t.operation_id !== 'string' || !CREATION_BIND_OPERATION_ID.test(t.operation_id)
+        || t.base_relation_version !== 0 || t.target_relation_version !== 1
+        || (t.status !== 'pending' && t.status !== 'completed'))
+        return undefined;
+    return {
+        source: 'agent_create', operation: 'bind', operationId: t.operation_id,
+        subjectAid, ownerAid, baseRelationVersion: 0, targetRelationVersion: 1,
+    };
+}
+export class OwnershipError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'OwnershipError';
+    }
+}
+export class OwnerResolver {
+    options;
+    subjects = new Map();
+    daemonAid;
+    /** Local owner configuration remains an independent authorization source during rollout. */
+    configuredOwners = new Map();
+    configuredOwnerFileRevision = new Map();
+    listeners = new Set();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    setDaemonAid(aid) {
+        this.assertAid(aid);
+        this.daemonAid = aid;
+    }
+    getDaemonAid() {
+        return this.daemonAid;
+    }
+    setConfiguredOwners(subjectAid, owners) {
+        this.assertAid(subjectAid);
+        const normalized = [...new Set(owners
+                .map(owner => String(owner || '').trim())
+                .filter(owner => isValidAid(owner) && owner !== subjectAid))];
+        const previous = this.configuredOwners.get(subjectAid) ?? [];
+        if (JSON.stringify(previous) === JSON.stringify(normalized))
+            return;
+        if (normalized.length > 0)
+            this.configuredOwners.set(subjectAid, normalized);
+        else
+            this.configuredOwners.delete(subjectAid);
+        const subject = this.subjects.get(subjectAid);
+        if (subject) {
+            this.invalidate(subject, 'Configured Owners changed; fresh consensus is required');
+            this.schedule(subjectAid, subject);
+        }
+    }
+    setAgentConfiguredOwners(subjectAid, owners) {
+        this.assertAid(subjectAid);
+        if (subjectAid === this.daemonAid)
+            return;
+        this.setConfiguredOwners(subjectAid, owners);
+    }
+    configuredOwnerList(subjectAid) {
+        if (!subjectAid)
+            return [];
+        this.refreshConfiguredOwnersFromDisk(subjectAid);
+        return [...(this.configuredOwners.get(subjectAid) ?? [])];
+    }
+    isOwner(subjectAid, ownerAid) {
+        if (!subjectAid || !ownerAid)
+            return false;
+        return this.owners(subjectAid).includes(ownerAid);
+    }
+    assertLocalSubject(subjectAid) {
+        this.assertAid(subjectAid);
+        if (!this.subjects.get(subjectAid)?.client) {
+            throw new OwnershipError('SUBJECT_UNAVAILABLE', 'Subject must have local credentials and an existing SDK client');
+        }
+    }
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    attachClient(subjectAid, client, connected = false) {
+        this.assertAid(subjectAid);
+        const clientAid = client.currentAid;
+        if (!clientAid || clientAid.aid !== subjectAid
+            || !clientAid.isCertValid() || !clientAid.isPrivateKeyValid()) {
+            throw new OwnershipError('SUBJECT_MISMATCH', 'Ownership client identity does not match the subject AID');
+        }
+        this.detachClient(subjectAid);
+        const subject = this.subject(subjectAid);
+        subject.client = client;
+        const connectionState = String(client.state ?? '');
+        subject.view.connected = connected || client.isReady === true || connectionState === 'ready' || connectionState === 'connected';
+        const generation = subject.generation;
+        for (const event of ['ownership.request', 'ownership.pending', 'ownership.progress', 'ownership.completed',
+            'ownership.rejected', 'ownership.stopped', 'ownership.error', 'ownership.action_required']) {
+            subject.subscriptions.push(client.on(event, payload => {
+                if (subject.client !== client || subject.generation !== generation)
+                    return;
+                const record = this.record(payload);
+                if (!record || record.sub_aid !== subjectAid)
+                    return;
+                if (typeof record.operation_id === 'string') {
+                    const key = JSON.stringify([event, record.operation_id, record.step, record.status,
+                        record.owner_aid, record.relation_version, record.code, record.reason]);
+                    if (subject.taskEvents.has(key))
+                        return;
+                    subject.taskEvents.add(key);
+                    if (subject.taskEvents.size > 256)
+                        subject.taskEvents.delete(subject.taskEvents.values().next().value);
+                }
+                this.invalidate(subject, 'Ownership changed; fresh consensus is required');
+                const task = this.task(record);
+                logger.info(`[ownership] ${event} ${JSON.stringify({ subjectAid, ownerAid: task?.owner_aid,
+                    operationId: task?.operation_id, taskStatus: task?.status, step: task?.step,
+                    code: task?.code, reason: task?.reason })}`);
+                if (task && subject.view.requestedOwnerAid === task.owner_aid
+                    && (!subject.view.task || (subject.view.task.operation_id === task.operation_id
+                        && (subject.view.task.status === 'pending' || subject.view.task.status === task.status)))) {
+                    subject.view.task = task;
+                    subject.view.requestStatus = 'submitted';
+                }
+                try {
+                    this.persist(subjectAid, subject);
+                }
+                catch { }
+                this.schedule(subjectAid, subject);
+            }));
+        }
+        subject.subscriptions.push(client.on('agentmd.changed', payload => {
+            if (subject.client !== client || subject.generation !== generation
+                || typeof payload !== 'string' || !isValidAid(payload))
+                return;
+            this.invalidateRelatedSubjects(payload);
+        }));
+        subject.subscriptions.push(client.on('storage.object_changed', payload => {
+            if (subject.client !== client || subject.generation !== generation)
+                return;
+            const record = this.record(payload);
+            if (!record || record.owner_aid !== subjectAid || typeof record.object_key !== 'string')
+                return;
+            const objectKey = record.object_key.replace(/^\/+/, '');
+            if (objectKey === 'agent.md')
+                this.invalidateRelatedSubjects(subjectAid);
+            else {
+                const match = /^sub_aids\/([^/]+)\/owner\.md$/.exec(objectKey);
+                if (match)
+                    this.invalidateRelatedSubjects(subjectAid, match[1]);
+            }
+        }));
+        for (const event of ['state_change', 'connection.state']) {
+            subject.subscriptions.push(client.on(event, payload => {
+                if (subject.client !== client || subject.generation !== generation)
+                    return;
+                const record = this.record(payload);
+                const state = typeof payload === 'string' ? payload : record?.state ?? record?.status;
+                if (state === 'ready' || state === 'connected')
+                    this.setConnected(subjectAid, client, true);
+                else if (typeof state === 'string')
+                    this.setConnected(subjectAid, client, false);
+            }));
+        }
+        if (subject.view.connected)
+            this.schedule(subjectAid, subject);
+    }
+    setConnected(subjectAid, client, connected) {
+        const subject = this.subjects.get(subjectAid);
+        if (!subject || subject.client !== client)
+            return;
+        if (subject.view.connected === connected)
+            return;
+        if (!connected) {
+            // Transport loss does not revoke unexpired consensus. Retire work from
+            // the old connection without clearing the cached authorization.
+            subject.epoch += 1;
+            if (subject.timer)
+                clearTimeout(subject.timer);
+            subject.timer = undefined;
+            if (subject.pendingRefreshTimer)
+                clearTimeout(subject.pendingRefreshTimer);
+            subject.pendingRefreshTimer = undefined;
+        }
+        subject.view.connected = connected;
+        if (connected)
+            this.schedule(subjectAid, subject);
+    }
+    detachClient(subjectAid, client) {
+        const subject = this.subjects.get(subjectAid);
+        if (!subject || (client && subject.client !== client))
+            return;
+        subject.generation += 1;
+        if (subject.timer)
+            clearTimeout(subject.timer);
+        subject.timer = undefined;
+        if (subject.pendingRefreshTimer)
+            clearTimeout(subject.pendingRefreshTimer);
+        subject.pendingRefreshTimer = undefined;
+        subject.taskEvents.clear();
+        for (const subscription of subject.subscriptions.splice(0)) {
+            try {
+                subscription.unsubscribe();
+            }
+            catch { }
+        }
+        subject.client = undefined;
+        subject.view.connected = false;
+        this.invalidate(subject, 'AUN client is unavailable');
+    }
+    owner(subjectAid) {
+        if (!subjectAid)
+            return undefined;
+        const view = this.subjects.get(subjectAid)?.view;
+        return view?.consensusStatus === 'consensus'
+            && (view.validUntil ?? 0) > this.now() ? view.ownerAid : undefined;
+    }
+    owners(subjectAid) {
+        if (!subjectAid)
+            return [];
+        return [...new Set([
+                ...this.configuredOwnerList(subjectAid),
+                ...this.protocolOwners(subjectAid),
+            ])];
+    }
+    protocolOwners(subjectAid) {
+        const owner = this.owner(subjectAid);
+        return owner ? [owner] : [];
+    }
+    primaryOwner(subjectAid) {
+        return this.owners(subjectAid)[0];
+    }
+    knownOwners(subjectAid) {
+        if (!subjectAid)
+            return [];
+        const configuredOwners = this.configuredOwnerList(subjectAid);
+        const ownerAid = this.subjects.get(subjectAid)?.view.relation?.ownerAid;
+        return [...new Set([...configuredOwners, ...(ownerAid ? [ownerAid] : [])])];
+    }
+    knownOwner(subjectAid) {
+        return this.knownOwners(subjectAid)[0];
+    }
+    daemonOwners() {
+        return this.owners(this.daemonAid);
+    }
+    configuredRevision(subjectAid) {
+        return JSON.stringify(this.configuredOwnerList(subjectAid));
+    }
+    revision(subjectAid) {
+        const view = this.subjects.get(subjectAid)?.view;
+        return JSON.stringify([
+            view?.revision ?? 0,
+            this.owner(subjectAid),
+            view?.consensusStatus ?? 'unavailable',
+            this.configuredOwnerList(subjectAid),
+        ]);
+    }
+    snapshot(subjectAid) {
+        const subject = this.subject(subjectAid);
+        const view = JSON.parse(JSON.stringify(subject.view));
+        if (view.consensusStatus === 'consensus' && !this.owner(subjectAid)) {
+            view.ownerAid = undefined;
+            view.synchronization = { status: 'unavailable' };
+        }
+        const now = this.now();
+        view.authorizationStatus = view.consensusStatus === 'consensus'
+            && view.checkedAt !== undefined && view.checkedAt <= now
+            ? view.ownerAid && now - view.checkedAt < OWNERSHIP_AUTHORIZATION_MAX_AGE_MS ? 'verified' : 'expired'
+            : 'unavailable';
+        if (subject.persistenceError) {
+            view.requestStatus = 'error';
+            view.reason = subject.persistenceError;
+            view.synchronization.status = 'unavailable';
+            view.authorizationStatus = 'unavailable';
+        }
+        return view;
+    }
+    async refresh(subjectAid, options = {}) {
+        const subject = this.subject(subjectAid);
+        this.refreshConfiguredOwnersFromDisk(subjectAid);
+        if (subject.timer)
+            clearTimeout(subject.timer);
+        subject.timer = undefined;
+        const refreshing = subject.refreshing?.epoch === subject.epoch ? subject.refreshing.promise : undefined;
+        const maxAgeMs = options.maxAgeMs ?? this.options.lifetimeMs ?? OWNERSHIP_CACHE_MAX_AGE_MS;
+        const isFresh = () => {
+            const { checkedAt, validUntil, consensusStatus } = subject.view;
+            const now = this.now();
+            return consensusStatus !== 'unavailable' && consensusStatus !== 'not_applicable'
+                && checkedAt !== undefined && checkedAt <= now && (validUntil ?? 0) > now
+                && now - checkedAt < maxAgeMs;
+        };
+        if (!refreshing && !options.force && isFresh()) {
+            return this.snapshot(subjectAid);
+        }
+        const promise = refreshing ?? this.refreshSubject(subjectAid, subject);
+        subject.refreshing = { epoch: subject.epoch, promise };
+        try {
+            await promise;
+            if (!subject.view.connected && subject.view.consensusStatus === 'consensus' && !isFresh()) {
+                this.invalidate(subject, 'Ownership cache expired while disconnected');
+            }
+            return this.snapshot(subjectAid);
+        }
+        finally {
+            if (subject.refreshing?.promise === promise)
+                subject.refreshing = undefined;
+            this.schedulePendingRefresh(subjectAid, subject);
+        }
+    }
+    async refreshSubject(subjectAid, subject) {
+        const client = subject.client;
+        if (!client || !subject.view.connected) {
+            this.invalidate(subject, 'Subject AID has no connected SDK client');
+            return this.snapshot(subjectAid);
+        }
+        const generation = subject.generation;
+        const epoch = subject.epoch;
+        const query = ++subject.query;
+        let timeout;
+        try {
+            const consensus = await Promise.race([
+                client.checkOwnershipConsensus(subjectAid),
+                new Promise((_resolve, reject) => {
+                    timeout = setTimeout(() => reject(new Error('Ownership consensus check timed out')), this.options.timeoutMs ?? 8_000);
+                    timeout.unref?.();
+                }),
+            ]);
+            if (subject.client !== client || subject.generation !== generation || subject.epoch !== epoch
+                || subject.query !== query || !subject.view.connected)
+                return this.snapshot(subjectAid);
+            const ownerAid = consensus.status === 'consensus' && consensus.sub_aid === subjectAid
+                && typeof consensus.owner_aid === 'string' && isValidAid(consensus.owner_aid)
+                && consensus.owner_aid !== subjectAid ? consensus.owner_aid : undefined;
+            if (consensus.sub_aid !== subjectAid || (consensus.status === 'consensus' && !ownerAid)) {
+                throw new Error('Ownership consensus contains a mismatched subject or invalid owner');
+            }
+            const previousOwner = this.owner(subjectAid);
+            const previousStatus = subject.view.consensusStatus;
+            const checkedAt = this.now();
+            const pending = subject.view.task?.status === 'pending' || subject.view.requestStatus === 'requesting';
+            subject.view = {
+                ...subject.view,
+                ownerAid,
+                relation: consensus.status === 'consensus' || consensus.status === 'unbound' || consensus.status === 'released'
+                    ? { consensusStatus: consensus.status, ownerAid, checkedAt, relationVersion: consensus.relation_version }
+                    : subject.view.relation,
+                authorizationStatus: ownerAid ? 'verified' : 'unavailable',
+                consensusStatus: consensus.status,
+                consensus: JSON.parse(JSON.stringify(consensus)),
+                checkedAt,
+                validUntil: checkedAt + (this.options.lifetimeMs ?? OWNERSHIP_CACHE_MAX_AGE_MS),
+                revision: subject.view.revision + (previousOwner !== ownerAid
+                    || subject.view.consensusStatus !== consensus.status
+                    || subject.view.consensus?.relation_version !== consensus.relation_version
+                    || subject.view.consensus?.lock !== consensus.lock ? 1 : 0),
+                reason: consensus.reason,
+                synchronization: {
+                    status: consensus.status === 'unavailable' || consensus.status === 'not_applicable' ? 'unavailable'
+                        : consensus.status === 'invalid' ? 'conflict'
+                            : ownerAid && subject.view.requestedOwnerAid && subject.view.requestedOwnerAid !== ownerAid ? 'conflict'
+                                : consensus.status === 'single_sided' || (!ownerAid && pending) ? 'pending' : 'synced',
+                    runtimeOwnerAid: ownerAid,
+                },
+            };
+            if (previousOwner !== ownerAid || previousStatus !== consensus.status)
+                this.notify(subjectAid, ownerAid);
+            if (ownerAid === subject.view.requestedOwnerAid && subject.view.requestStatus === 'interrupted') {
+                subject.view.requestStatus = 'submitted';
+                this.persist(subjectAid, subject);
+            }
+        }
+        catch (error) {
+            if (subject.client === client && subject.generation === generation && subject.epoch === epoch && subject.query === query) {
+                this.invalidate(subject, error instanceof Error ? error.message : String(error));
+            }
+        }
+        finally {
+            if (timeout)
+                clearTimeout(timeout);
+        }
+        return this.snapshot(subjectAid);
+    }
+    async bind(subjectAid, ownerAid) {
+        this.assertLocalSubject(subjectAid);
+        this.assertAid(ownerAid);
+        if (ownerAid === subjectAid)
+            throw new OwnershipError('INVALID_OWNER', 'Subject cannot own itself');
+        const subject = this.subject(subjectAid);
+        if (subject.persistenceError)
+            throw new OwnershipError('persistence_unavailable', subject.persistenceError);
+        if (subject.binding) {
+            if (subject.binding.ownerAid !== ownerAid)
+                throw new OwnershipError('BIND_CONFLICT', 'Another owner binding is in progress');
+            return subject.binding.promise;
+        }
+        const promise = this.submitBinding(subjectAid, ownerAid, subject);
+        subject.binding = { ownerAid, promise };
+        try {
+            return await promise;
+        }
+        finally {
+            if (subject.binding?.promise === promise)
+                subject.binding = undefined;
+        }
+    }
+    stop() {
+        for (const subjectAid of this.subjects.keys())
+            this.detachClient(subjectAid);
+        this.configuredOwners.clear();
+    }
+    async submitBinding(subjectAid, ownerAid, subject) {
+        const current = await this.refresh(subjectAid, { force: true });
+        if (current.consensusStatus === 'consensus') {
+            if (current.ownerAid === ownerAid)
+                return current;
+            throw new OwnershipError('OWNER_ALREADY_BOUND', 'Subject already has a protocol owner; transfer is not supported');
+        }
+        const recovering = (subject.view.task?.status === 'pending' || subject.view.requestStatus === 'interrupted')
+            && subject.view.requestedOwnerAid === ownerAid;
+        if (!['unbound', 'released'].includes(current.consensusStatus)
+            && !(recovering && current.consensusStatus === 'single_sided')) {
+            throw new OwnershipError('CONSENSUS_REQUIRED', 'Binding requires a fresh unbound or released consensus result');
+        }
+        if (subject.view.task?.status === 'pending') {
+            if (subject.view.task.owner_aid !== ownerAid)
+                throw new OwnershipError('BIND_CONFLICT', 'A different binding task is pending');
+        }
+        if (subject.view.requestStatus === 'interrupted' && subject.view.requestedOwnerAid !== ownerAid) {
+            throw new OwnershipError('BIND_UNCERTAIN', 'Retry the interrupted request with its original owner before changing the target');
+        }
+        const client = subject.client;
+        if (!client || !subject.view.connected)
+            throw new OwnershipError('SUBJECT_UNAVAILABLE', 'Subject AID SDK client is not ready');
+        const generation = subject.generation;
+        subject.view = { ...subject.view, requestedOwnerAid: ownerAid, requestStatus: 'requesting', task: undefined };
+        this.persist(subjectAid, subject);
+        try {
+            const task = this.task(await client.bindOwneraid(ownerAid));
+            if (subject.client !== client || subject.generation !== generation) {
+                throw new OwnershipError('CLIENT_REPLACED', 'Subject SDK client changed during binding; the request may have been submitted');
+            }
+            if (!task || task.sub_aid !== subjectAid || task.owner_aid !== ownerAid || task.operation !== 'bind') {
+                throw new OwnershipError('TASK_MISMATCH', 'SDK returned a binding task for a different subject or owner');
+            }
+            subject.view.task = task;
+            subject.view.requestStatus = 'submitted';
+            this.persist(subjectAid, subject);
+            this.invalidate(subject, 'Binding submitted; waiting for explicit owner approval and fresh consensus');
+            this.schedule(subjectAid, subject);
+            return this.snapshot(subjectAid);
+        }
+        catch (error) {
+            if (subject.client === client && subject.generation === generation) {
+                subject.view.requestStatus = 'interrupted';
+                subject.view.reason = error instanceof Error ? error.message : String(error);
+                this.persist(subjectAid, subject);
+            }
+            throw error;
+        }
+    }
+    subject(subjectAid) {
+        this.assertAid(subjectAid);
+        let subject = this.subjects.get(subjectAid);
+        if (subject)
+            return subject;
+        let saved = null;
+        let persistenceError;
+        try {
+            const filename = this.statePath(subjectAid);
+            saved = atomicReadJson(filename);
+            const savedTask = saved?.task !== undefined ? this.task(saved.task) : undefined;
+            if ((saved === null && fs.existsSync(filename)) || (saved && (saved.version !== 1 || saved.subjectAid !== subjectAid
+                || (saved.requestedOwnerAid !== undefined && (typeof saved.requestedOwnerAid !== 'string' || !isValidAid(saved.requestedOwnerAid)))
+                || (saved.task !== undefined && (!savedTask || savedTask.sub_aid !== subjectAid || savedTask.owner_aid !== saved.requestedOwnerAid))
+                || (saved.requestStatus !== undefined && !['requesting', 'submitted', 'interrupted', 'error'].includes(String(saved.requestStatus)))))) {
+                throw new Error('Invalid persisted ownership task');
+            }
+        }
+        catch (error) {
+            saved = null;
+            persistenceError = `Ownership task storage is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        const task = saved?.subjectAid === subjectAid ? this.task(saved.task) : undefined;
+        subject = {
+            generation: 0, epoch: 0, query: 0, subscriptions: [], taskEvents: new Set(), persistenceError,
+            view: {
+                subjectAid, consensusStatus: 'unavailable', authorizationStatus: 'unavailable', connected: false, revision: 0,
+                task: task?.sub_aid === subjectAid ? task : undefined,
+                requestedOwnerAid: saved?.subjectAid === subjectAid && typeof saved.requestedOwnerAid === 'string'
+                    && isValidAid(saved.requestedOwnerAid) ? saved.requestedOwnerAid : undefined,
+                requestStatus: saved?.requestStatus === 'requesting' || saved?.requestStatus === 'interrupted' ? 'interrupted'
+                    : task ? 'submitted' : undefined,
+                synchronization: { status: 'unavailable' },
+            },
+        };
+        this.subjects.set(subjectAid, subject);
+        return subject;
+    }
+    invalidate(subject, reason) {
+        const previousOwner = subject.view.ownerAid;
+        subject.epoch += 1;
+        subject.view = {
+            ...subject.view, ownerAid: undefined, consensusStatus: 'unavailable', authorizationStatus: 'unavailable', validUntil: undefined,
+            revision: subject.view.revision + 1, reason, synchronization: { status: 'unavailable' },
+        };
+        if (previousOwner)
+            this.notify(subject.view.subjectAid);
+    }
+    notify(subjectAid, ownerAid) {
+        for (const listener of this.listeners) {
+            queueMicrotask(() => { try {
+                listener(subjectAid, ownerAid);
+            }
+            catch { } });
+        }
+    }
+    invalidateRelatedSubjects(changedAid, targetAid) {
+        for (const [subjectAid, subject] of this.subjects) {
+            if (!subject.client || !subject.view.connected || (targetAid && targetAid !== subjectAid))
+                continue;
+            const ownerAid = subject.view.relation?.ownerAid;
+            if ((!targetAid && changedAid === subjectAid) || changedAid === ownerAid
+                || changedAid === subject.view.requestedOwnerAid) {
+                this.invalidate(subject, 'Ownership material changed; fresh consensus is required');
+                this.schedule(subjectAid, subject);
+            }
+        }
+    }
+    schedule(subjectAid, subject) {
+        if (subject.timer || !subject.client || !subject.view.connected)
+            return;
+        subject.timer = setTimeout(() => {
+            subject.timer = undefined;
+            void this.refresh(subjectAid, { force: true }).catch(error => {
+                logger.warn(`[ownership] Event refresh failed for ${subjectAid}: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }, 0);
+        subject.timer.unref?.();
+    }
+    schedulePendingRefresh(subjectAid, subject) {
+        // The owner's final publication can become readable after the last SDK
+        // event. A cached unbound/single-sided observation must not strand an
+        // approved creation in ownerpending until the next connection or command.
+        // Only fresh SDK consensus can authorize the existing owner-bound handler;
+        // this never resubmits a binding or infers ownership from task completion.
+        const needsRefresh = subject.client && subject.view.connected
+            && subject.view.requestedOwnerAid && subject.view.consensusStatus !== 'consensus'
+            && (subject.view.task?.status === 'pending' || subject.view.task?.status === 'completed'
+                || subject.view.requestStatus === 'requesting' || subject.view.requestStatus === 'interrupted');
+        if (!needsRefresh) {
+            if (subject.pendingRefreshTimer)
+                clearTimeout(subject.pendingRefreshTimer);
+            subject.pendingRefreshTimer = undefined;
+            return;
+        }
+        if (subject.pendingRefreshTimer)
+            return;
+        subject.pendingRefreshTimer = setTimeout(() => {
+            subject.pendingRefreshTimer = undefined;
+            void this.refresh(subjectAid, { force: true }).catch(error => {
+                logger.warn(`[ownership] Pending consensus refresh failed for ${subjectAid}: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }, OWNERSHIP_PENDING_REFRESH_MS);
+        subject.pendingRefreshTimer.unref?.();
+    }
+    statePath(subjectAid) {
+        return path.join(this.options.stateDirectory?.() ?? path.join(resolvePaths().root, 'data', 'ownership'), `${subjectAid}.json`);
+    }
+    persist(subjectAid, subject) {
+        if (!subject.persistenceError) {
+            try {
+                const filename = this.statePath(subjectAid);
+                fs.mkdirSync(path.dirname(filename), { recursive: true });
+                atomicWriteJson(filename, {
+                    version: 1, subjectAid, requestedOwnerAid: subject.view.requestedOwnerAid,
+                    requestStatus: subject.view.requestStatus, task: subject.view.task,
+                });
+                return;
+            }
+            catch (error) {
+                subject.persistenceError = `Ownership task storage is unavailable: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        throw new OwnershipError('persistence_unavailable', subject.persistenceError);
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    refreshConfiguredOwnersFromDisk(subjectAid) {
+        const file = subjectAid === this.daemonAid
+            ? resolvePaths().daemonConfig
+            : path.join(resolvePaths().agentsDir, subjectAid, 'config.json');
+        let revision = 'missing';
+        try {
+            const stat = fs.statSync(file);
+            revision = `${stat.size}:${stat.mtimeMs}`;
+        }
+        catch { }
+        if (this.configuredOwnerFileRevision.get(subjectAid) === revision)
+            return;
+        const hadFileRevision = this.configuredOwnerFileRevision.has(subjectAid);
+        this.configuredOwnerFileRevision.set(subjectAid, revision);
+        if (revision === 'missing') {
+            if (hadFileRevision)
+                this.setConfiguredOwners(subjectAid, []);
+            return;
+        }
+        try {
+            const raw = atomicReadJson(file);
+            this.setConfiguredOwners(subjectAid, readConfiguredOwnerList(raw));
+        }
+        catch {
+            // The regular config loader reports malformed files; keep this optional
+            // compatibility read fail-closed without interrupting ownership checks.
+        }
+    }
+    assertAid(aid) {
+        if (!isValidAid(aid) || aid.trim() !== aid)
+            throw new OwnershipError('INVALID_AID', `Invalid AID: ${aid}`);
+    }
+    record(value) {
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    }
+    task(value) {
+        const record = this.record(value);
+        if (!record || typeof record.operation_id !== 'string' || !record.operation_id
+            || record.operation !== 'bind' || typeof record.sub_aid !== 'string' || !isValidAid(record.sub_aid)
+            || typeof record.owner_aid !== 'string' || !isValidAid(record.owner_aid)
+            || !['pending', 'completed', 'rejected', 'stopped', 'error'].includes(String(record.status))
+            || typeof record.step !== 'string')
+            return undefined;
+        return JSON.parse(JSON.stringify(record));
+    }
+}
+export const ownerResolver = new OwnerResolver();
+export const getProtocolOwner = (subjectAid) => ownerResolver.owner(subjectAid);
+export const getPrimaryOwner = (subjectAid) => ownerResolver.primaryOwner(subjectAid);
+export const getProtocolOwners = (subjectAid) => ownerResolver.protocolOwners(subjectAid);
+export const getOwners = (subjectAid) => ownerResolver.owners(subjectAid);
+export const getConfiguredOwners = (subjectAid) => ownerResolver.configuredOwnerList(subjectAid);
+export const getDaemonOwners = () => ownerResolver.daemonOwners();
+export async function refreshOwnershipForAuthorization(subjectAid, options = {}) {
+    const daemonAid = ownerResolver.getDaemonAid();
+    const ownershipSubjectAid = daemonAid && subjectAid === `${daemonAid}#daemon` ? daemonAid : subjectAid;
+    const subjects = new Set([ownershipSubjectAid, ...(!ownershipSubjectAid || options.includeDaemon !== false ? [daemonAid] : [])]
+        .filter((aid) => !!aid));
+    await Promise.all([...subjects].map(aid => ownerResolver.refresh(aid, {
+        maxAgeMs: options.maxAgeMs ?? OWNERSHIP_AUTHORIZATION_MAX_AGE_MS,
+        force: options.force,
+    })));
+}
+export async function assertOwnershipAuthorization(context) {
+    const authorization = context?.executionPermission;
+    const ownerRole = context?.role === 'owner' && context.actor?.operatorChannelType !== 'daemon';
+    const ownerActor = hasTrustedPrincipal(context?.actor) ? context.actor.principalId : undefined;
+    if (!authorization && !ownerRole)
+        return;
+    await refreshOwnershipForAuthorization(context?.selfAid ?? authorization?.agentAid);
+    if (authorization) {
+        if (!getDaemonOwners().includes(authorization.authorizedBy)
+            || (authorization.source === 'agent-policy'
+                && !ownerResolver.isOwner(authorization.agentAid ?? '', authorization.authorizedBy))) {
+            throw new OwnershipError('OWNER_UNAVAILABLE', 'Current Owner no longer authorizes this execution');
+        }
+    }
+    else if (!context?.selfAid || !ownerResolver.isOwner(context.selfAid, ownerActor)) {
+        throw new OwnershipError('OWNER_UNAVAILABLE', 'Current Owner could not be verified; start a new task with the current role');
+    }
+}