@agentunion/fastaun 0.5.17 → 0.5.19

package/dist/ownership-workflow.js

@@ -0,0 +1,872 @@
+import { randomUUID } from 'node:crypto';
+import { isScalar, parseDocument } from 'yaml';
+import { StateError, ValidationError } from './errors.js';
+import { OWNERSHIP_UUID_V4_RE, ownershipAid, ownershipFailure, ownershipInteger, ownershipSha256, parseOwnershipFile, requireOwnershipApplicable } from './ownership-v21.js';
+export const OWNERSHIP_SDK_MESSAGE_TYPE = 'aun.ownership.sdk.v1';
+function participants(task) {
+    return [...new Set([task.owner_aid, task.sub_aid, ...(task.new_owner_aid ? [task.new_owner_aid] : [])])];
+}
+function targetOwner(task) {
+    return task.operation === 'transfer' ? task.new_owner_aid : task.owner_aid;
+}
+export function parseOwnershipMessage(content, context) {
+    let value = content;
+    if (typeof content === 'string') {
+        try {
+            value = JSON.parse(content);
+        }
+        catch {
+            throw new ValidationError('ownership message must be JSON');
+        }
+        const document = parseDocument(content, { uniqueKeys: true });
+        if (document.errors.length)
+            throw new ValidationError('ownership message has duplicate or invalid fields');
+        for (const field of ['base_relation_version', 'target_relation_version']) {
+            const node = document.get(field, true);
+            if (!isScalar(node) || !/^(?:0|[1-9][0-9]*)$/.test(node.source ?? ''))
+                throw new ValidationError(`${field} must use an integer`);
+        }
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ValidationError('ownership message must be an object');
+    const message = value;
+    const required = ['type', 'operation_id', 'operation', 'action', 'sub_aid', 'owner_aid', 'base_relation_version', 'target_relation_version'];
+    const optional = ['new_owner_aid', 'reason'];
+    if (required.some((key) => !(key in message)) || Object.keys(message).some((key) => !required.includes(key) && !optional.includes(key)))
+        throw new ValidationError('ownership message contains unknown or missing fields');
+    if (message.type !== OWNERSHIP_SDK_MESSAGE_TYPE)
+        throw ownershipFailure('unsupported_protocol', 'legacy ownership control is unsupported');
+    if (!OWNERSHIP_UUID_V4_RE.test(message.operation_id))
+        throw new ValidationError('operation_id must be a UUIDv4');
+    if (!['bind', 'release', 'transfer'].includes(message.operation))
+        throw new ValidationError('ownership operation is invalid');
+    ownershipAid(message.sub_aid, 'sub_aid');
+    ownershipAid(message.owner_aid, 'owner_aid');
+    ownershipInteger(message.base_relation_version, 'base_relation_version', 0);
+    if (ownershipInteger(message.target_relation_version, 'target_relation_version') !== message.base_relation_version + 1)
+        throw new ValidationError('ownership target version must be base plus one');
+    if (message.operation === 'transfer') {
+        if (ownershipAid(message.new_owner_aid, 'new_owner_aid') === message.owner_aid)
+            throw new ValidationError('transfer target must differ from current owner');
+    }
+    else if ('new_owner_aid' in message)
+        throw new ValidationError('new_owner_aid is only allowed for transfer');
+    const allowed = {
+        bind: ['bind.request', 'bind.accept', 'bind.reject', 'owner.ready', 'relation.confirmed', 'operation.stopped'],
+        release: ['relation.confirmed', 'sub.cleaned', 'operation.stopped'],
+        transfer: ['transfer.request', 'transfer.accept', 'transfer.reject', 'transfer.ready', 'owner.ready', 'relation.confirmed', 'operation.stopped'],
+    };
+    if (!allowed[message.operation].includes(message.action))
+        throw new ValidationError('ownership action does not match operation');
+    if ('reason' in message && (typeof message.reason !== 'string' || !['bind.reject', 'transfer.reject', 'operation.stopped'].includes(message.action)))
+        throw new ValidationError('ownership reason is only allowed for reject or stopped');
+    const from = ownershipAid(context.authenticated_from_aid, 'authenticated_from_aid');
+    const local = ownershipAid(context.local_aid, 'local_aid');
+    if (from === local || !participants(message).includes(from) || !participants(message).includes(local))
+        throw ownershipFailure('forbidden', 'ownership sender or receiver is not a remote participant');
+    const task = context.task;
+    if (task && ['operation_id', 'operation', 'sub_aid', 'owner_aid', 'new_owner_aid', 'base_relation_version', 'target_relation_version'].some((key) => task[key] !== message[key]))
+        throw ownershipFailure('conflict', 'ownership fixed task context changed');
+    const initiator = task?.initiator_aid;
+    let direction = false;
+    switch (message.action) {
+        case 'bind.request':
+            direction = (!initiator || from === initiator) && [message.owner_aid, message.sub_aid].includes(from);
+            break;
+        case 'bind.accept':
+        case 'bind.reject':
+            direction = Boolean(initiator && local === initiator && from !== initiator);
+            break;
+        case 'transfer.request':
+        case 'transfer.ready':
+            direction = from === message.owner_aid && [message.sub_aid, message.new_owner_aid].includes(local);
+            break;
+        case 'transfer.accept':
+        case 'transfer.reject':
+            direction = Boolean(task && local === message.owner_aid && [message.sub_aid, message.new_owner_aid].includes(from));
+            break;
+        case 'owner.ready':
+            direction = Boolean(task && from === targetOwner(message) && local === message.sub_aid);
+            break;
+        case 'relation.confirmed':
+            direction = message.operation === 'release' ? from === message.owner_aid && local === message.sub_aid : Boolean(task && from === message.sub_aid && local !== message.sub_aid);
+            break;
+        case 'sub.cleaned':
+            direction = Boolean(task && from === message.sub_aid && local === message.owner_aid);
+            break;
+        case 'operation.stopped':
+            direction = Boolean(task);
+            break;
+    }
+    if (!direction)
+        throw ownershipFailure('forbidden', 'ownership action has an invalid authenticated direction');
+    if (['owner.ready', 'transfer.ready'].includes(message.action) && task?.local_decision !== 'accept')
+        throw ownershipFailure('forbidden', 'ownership local approval is required');
+    if (context.ns) {
+        const ns = context.ns;
+        if (ns.protocol !== '2.1')
+            throw ownershipFailure('unsupported_protocol', 'NS ownership protocol is unavailable');
+        const base = ns.relation_version === message.base_relation_version && (message.operation === 'bind' ? ns.lock === 'unlocked' && !ns.owner_aid : ns.lock === 'locked' && ns.owner_aid === message.owner_aid);
+        const target = ns.relation_version === message.target_relation_version && (message.operation === 'release' ? ns.lock === 'unlocked' && !ns.owner_aid : ns.lock === 'locked' && ns.owner_aid === targetOwner(message));
+        if (['relation.confirmed', 'sub.cleaned'].includes(message.action) ? !target : !base && !target)
+            throw ownershipFailure('conflict', 'ownership current NS relation does not match this task');
+    }
+    return message;
+}
+function localRoles(task, local) {
+    const roles = [];
+    if (task.owner_aid === local)
+        roles.push('owner');
+    if (task.sub_aid === local)
+        roles.push('sub');
+    if (task.new_owner_aid === local)
+        roles.push('new_owner');
+    return roles;
+}
+export function ownershipTaskResult(task) {
+    const result = {
+        operation_id: task.operation_id, operation: task.operation, sub_aid: task.sub_aid, owner_aid: task.owner_aid,
+        base_relation_version: task.base_relation_version, target_relation_version: task.target_relation_version, status: task.status, step: task.step,
+    };
+    if (task.operation === 'transfer')
+        result.new_owner_aid = task.new_owner_aid;
+    for (const field of ['code', 'reason', 'retryable'])
+        if (task[field] !== undefined)
+            Object.assign(result, { [field]: task[field] });
+    return result;
+}
+export class OwnershipWorkflow {
+    deps;
+    static serial = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async bindOwneraid(ownerAid) {
+        return this.start('bind', this.local(), ownershipAid(ownerAid, 'owner_aid'));
+    }
+    async bindSubaid(subAid) {
+        return this.start('bind', ownershipAid(subAid, 'sub_aid'), this.local());
+    }
+    async releaseSubaid(subAid) {
+        return this.start('release', ownershipAid(subAid, 'sub_aid'), this.local());
+    }
+    async transferSubaid(subAid, newOwnerAid) {
+        return this.start('transfer', ownershipAid(subAid, 'sub_aid'), this.local(), ownershipAid(newOwnerAid, 'new_owner_aid'));
+    }
+    async resumeRegistration(ownerAid, operationId) {
+        if (!OWNERSHIP_UUID_V4_RE.test(operationId))
+            throw ownershipFailure('invalid', 'registration operation_id is invalid');
+        return this.start('bind', this.local(), ownershipAid(ownerAid, 'owner_aid'), undefined, operationId);
+    }
+    async acceptOwnershipRequest(operationId) {
+        return this.decide(operationId, 'accept');
+    }
+    async rejectOwnershipRequest(operationId, reason) {
+        if (reason !== undefined && typeof reason !== 'string')
+            throw ownershipFailure('invalid', 'ownership rejection reason must be a string');
+        return this.decide(operationId, 'reject', reason);
+    }
+    async checkOwnershipConsensus(subAid = this.local()) {
+        return this.deps.files.checkConsensus(ownershipAid(subAid, 'sub_aid'));
+    }
+    async receive(from, content) {
+        let body = content;
+        if (typeof content === 'string') {
+            try {
+                body = JSON.parse(content);
+            }
+            catch {
+                return false;
+            }
+        }
+        if (!body || typeof body !== 'object' || Array.isArray(body))
+            return false;
+        const type = body.type;
+        if (typeof type !== 'string' || !type.startsWith('aun.ownership.'))
+            return false;
+        if (type !== OWNERSHIP_SDK_MESSAGE_TYPE)
+            return true;
+        let message;
+        try {
+            message = parseOwnershipMessage(content, { authenticated_from_aid: from, local_aid: this.local(),
+                task: ['bind.request', 'transfer.request'].includes(String(body.action)) || body.operation === 'release' && body.action === 'relation.confirmed' ? undefined : this.load(String(body.operation_id))?.record });
+        }
+        catch (error) {
+            if (error instanceof StateError && error.stringCode === 'persistence_unavailable')
+                throw error;
+            return true;
+        }
+        let observationError;
+        try {
+            this.requireApplicable(message.sub_aid);
+            await this.deps.files.readAgent(message.sub_aid);
+        }
+        catch (error) {
+            if (error instanceof StateError && error.stringCode === 'not_applicable')
+                return true;
+            observationError = error;
+        }
+        return this.runSerialized(message.sub_aid, async () => {
+            let handle = this.load(message.operation_id);
+            if (handle) {
+                try {
+                    parseOwnershipMessage(content, { authenticated_from_aid: from, local_aid: this.local(), task: handle.record });
+                }
+                catch {
+                    return true;
+                }
+            }
+            else {
+                if (!['bind.request', 'transfer.request'].includes(message.action) && !(message.operation === 'release' && message.action === 'relation.confirmed'))
+                    return true;
+                handle = { record: this.newRecord(message, from, 'pending'), revision: null };
+                if (message.operation === 'release') {
+                    const authorization = this.cleanupAuthorization(handle.record);
+                    if (authorization) {
+                        handle.record.local_decision = 'accept';
+                        handle.record.approvals[this.local()] = 'accept';
+                        handle.record.cleanup_authorization_id = authorization.operation_id;
+                    }
+                }
+            }
+            if (message.action === 'sub.cleaned') {
+                const began = Date.now();
+                const before = await this.readNs(message.sub_aid), after = await this.readNs(message.sub_aid);
+                if (Date.now() - began > 30_000 || before.exists !== after.exists || before.etag !== after.etag || before.relation_version !== after.relation_version || before.lock !== after.lock || before.owner_aid !== after.owner_aid || ownershipSha256(before.content) !== ownershipSha256(after.content))
+                    throw ownershipFailure('unavailable', 'NS changed during sub cleanup verification', true);
+                if (!before.exists || before.relation_version !== message.target_relation_version || before.lock !== 'unlocked' || before.owner_aid || !before.etag)
+                    return true;
+                const file = parseOwnershipFile(before.content, 'agent', { expectedSubAid: message.sub_aid });
+                if (Object.hasOwn(file.frontmatter, 'owner') || Object.hasOwn(file.frontmatter, 'ownership'))
+                    return true;
+            }
+            const key = `${from}|${message.operation_id}|${message.action}`;
+            if (!handle.record.received.includes(key) && !handle.record.inbox.some((item) => `${item.from}|${item.payload.operation_id}|${item.payload.action}` === key)) {
+                handle.record.inbox.push({ from, payload: message });
+                await this.save(handle);
+            }
+            if (observationError)
+                await this.recordError(handle, observationError);
+            else
+                await this.drive(handle);
+            return true;
+        });
+    }
+    async resume() {
+        for (const snapshot of this.list()) {
+            const record = this.decode(snapshot).record;
+            await this.runSerialized(record.sub_aid, async () => {
+                const handle = this.load(record.operation_id);
+                await this.drive(handle);
+                if (handle.record.request_verified && handle.record.local_decision === 'pending' && handle.record.status === 'pending' && handle.record.operation !== 'release')
+                    this.emit(handle.record, 'ownership.request');
+            });
+        }
+    }
+    local() { return ownershipAid(this.deps.currentAid(), 'local_aid'); }
+    requireApplicable(subAid) {
+        if (subAid === this.local())
+            requireOwnershipApplicable(this.deps.currentType?.());
+    }
+    store() {
+        if (!this.deps.store.loadOwnershipTask || !this.deps.store.listOwnershipTasks || !this.deps.store.compareAndSwapOwnershipTask)
+            throw ownershipFailure('persistence_unavailable', 'atomic ownership task storage is unavailable');
+        return this.deps.store;
+    }
+    list() {
+        try {
+            return this.store().listOwnershipTasks(this.local());
+        }
+        catch (error) {
+            throw ownershipFailure('persistence_unavailable', error instanceof Error ? error.message : String(error));
+        }
+    }
+    load(operationId) {
+        try {
+            const snapshot = this.store().loadOwnershipTask(this.local(), operationId);
+            return snapshot ? this.decode(snapshot) : null;
+        }
+        catch (error) {
+            throw ownershipFailure('persistence_unavailable', error instanceof Error ? error.message : String(error));
+        }
+    }
+    decode(snapshot) {
+        const record = snapshot.task;
+        try {
+            if (record.protocol !== '2.1' || !OWNERSHIP_UUID_V4_RE.test(record.operation_id) || record.operation_id !== snapshot.operation_id || !['bind', 'release', 'transfer'].includes(record.operation) || !['pending', 'completed', 'rejected', 'stopped', 'error'].includes(record.status) || typeof record.step !== 'string')
+                throw new Error('invalid ownership task');
+            ownershipAid(record.sub_aid, 'sub_aid');
+            ownershipAid(record.owner_aid, 'owner_aid');
+            ownershipAid(record.initiator_aid, 'initiator_aid');
+            if (record.operation === 'transfer') {
+                if (ownershipAid(record.new_owner_aid, 'new_owner_aid') === record.owner_aid)
+                    throw new Error('invalid transfer task');
+            }
+            else if (record.new_owner_aid !== undefined)
+                throw new Error('unexpected transfer target');
+            if (ownershipInteger(record.target_relation_version, 'target_relation_version') !== ownershipInteger(record.base_relation_version, 'base_relation_version', 0) + 1 || !participants(record).includes(record.initiator_aid) || record.operation !== 'bind' && record.initiator_aid !== record.owner_aid)
+                throw new Error('invalid fixed ownership context');
+            if (JSON.stringify(record.local_roles) !== JSON.stringify(localRoles(record, this.local())) || !record.local_roles.length || !['pending', 'accept', 'reject'].includes(record.local_decision) || !record.approvals || participants(record).some((aid) => !['pending', 'accept', 'reject'].includes(record.approvals[aid])) || record.approvals[this.local()] !== record.local_decision || !record.files || typeof record.files !== 'object' || Array.isArray(record.files) || !Array.isArray(record.inbox) || !Array.isArray(record.outbox) || !Array.isArray(record.received) || !Array.isArray(record.notices) || typeof record.request_verified !== 'boolean' || typeof record.request_notified !== 'boolean')
+                throw new Error('ownership approval or pending state is corrupt');
+            if (Object.keys(record.approvals).length !== participants(record).length || record.approvals[record.initiator_aid] !== 'accept' || record.initiator_aid === this.local() && record.local_decision !== 'accept')
+                throw new Error('ownership initiator or approval participants are corrupt');
+            if (record.status === 'completed' && (record.verified_relation_version !== record.target_relation_version || record.operation !== 'release' && record.local_decision !== 'accept'))
+                throw new Error('ownership completion evidence or local approval is corrupt');
+            const transferEvidenceRequired = record.operation === 'transfer' && (record.authorization_sha256 !== undefined || record.expires_at !== undefined || (record.status === 'completed' || ['owner', 'agent'].includes(record.step) || record.files.agent || record.files.owner) && record.local_roles.some((role) => role === 'sub' || role === 'new_owner'));
+            if (transferEvidenceRequired && (!/^[0-9a-f]{64}$/.test(record.authorization_sha256 ?? '') || !Number.isSafeInteger(record.expires_at) || (record.expires_at ?? 0) <= 0))
+                throw new Error('ownership transfer authorization evidence is corrupt');
+            for (const [key, saved] of Object.entries(record.files)) {
+                if (!['agent', 'owner', 'release', 'transfer', 'cleanup'].includes(key) || !saved || typeof saved.raw !== 'string' || saved.hash !== ownershipSha256(saved.raw) || !saved.condition || typeof saved.condition !== 'object' || Object.keys(saved.condition).length !== 1 || saved.published_revision !== undefined && (typeof saved.published_revision !== 'string' || !saved.published_revision))
+                    throw new Error('ownership saved file is corrupt');
+                if (key === 'agent' ? !(typeof saved.condition.if_match === 'string' && saved.condition.if_match || saved.condition.if_none_match === '*') : !(typeof saved.condition.expected_revision === 'string' && saved.condition.expected_revision))
+                    throw new Error('ownership original file condition is corrupt');
+                const owner = ['agent', 'owner'].includes(key) ? targetOwner(record) : record.owner_aid;
+                const file = parseOwnershipFile(saved.raw, key === 'agent' ? 'agent' : 'owner', { expectedSubAid: record.sub_aid, expectedOwnerAid: owner });
+                const version = ['release', 'transfer', 'cleanup'].includes(key) ? record.base_relation_version : record.target_relation_version;
+                if (key === 'agent' && record.operation === 'release' ? Boolean(file.statement) : file.statement?.relation_version !== version)
+                    throw new Error('ownership saved file relation is corrupt');
+                if (key === 'owner' && file.action !== 'declare' || key === 'release' && file.action !== 'release' || key === 'transfer' && (file.action !== 'transfer_owner' || file.transfer?.new_owner_aid !== record.new_owner_aid || file.transfer?.target_relation_version !== record.target_relation_version || file.transfer?.expires_at !== saved.expires_at))
+                    throw new Error('ownership saved file action is corrupt');
+            }
+            if (record.release_cleanup !== undefined) {
+                const cleanup = record.release_cleanup;
+                if (!['bind', 'transfer'].includes(record.operation) || record.status !== 'completed' || !record.local_roles.includes('sub') || record.local_decision !== 'accept' || typeof cleanup.cleaned !== 'boolean' || !cleanup.files || typeof cleanup.files !== 'object' || Array.isArray(cleanup.files))
+                    throw new Error('ownership historical cleanup context is corrupt');
+                for (const [key, saved] of Object.entries(cleanup.files)) {
+                    if (key !== 'agent' || !saved || saved.hash !== ownershipSha256(saved.raw) || typeof saved.condition?.if_match !== 'string' || !saved.condition.if_match || Object.keys(saved.condition).length !== 1 || parseOwnershipFile(saved.raw, 'agent', { expectedSubAid: record.sub_aid }).statement)
+                        throw new Error('ownership historical cleanup file is corrupt');
+                }
+            }
+            if (record.status === 'completed') {
+                const evidence = record.completion_evidence;
+                if (!evidence || evidence.sub_aid !== record.sub_aid || evidence.relation_version !== record.target_relation_version || evidence.status !== (record.operation === 'release' ? 'released' : 'consensus') || evidence.lock !== (record.operation === 'release' ? 'unlocked' : 'locked') || evidence.owner_aid !== (record.operation === 'release' ? null : targetOwner(record)) || typeof evidence.agent_md_etag !== 'string' || !evidence.agent_md_etag || !/^[0-9a-f]{64}$/.test(evidence.agent_md_sha256) || typeof evidence.owner_md_revision !== 'string' || typeof evidence.owner_md_sha256 !== 'string' || record.operation !== 'release' && (!evidence.owner_md_revision || !/^[0-9a-f]{64}$/.test(evidence.owner_md_sha256)))
+                    throw new Error('ownership target acceptance evidence is corrupt');
+                if (record.operation !== 'release' && (record.local_roles.includes('sub') && record.files.agent?.hash !== evidence.agent_md_sha256 || this.local() === targetOwner(record) && record.files.owner?.hash !== evidence.owner_md_sha256 || record.operation === 'transfer' && record.local_roles.includes('owner') && !record.files.transfer))
+                    throw new Error('ownership target file evidence is missing');
+                if (record.operation === 'release' && record.local_roles.includes('owner') && !record.files.release)
+                    throw new Error('ownership release file evidence is missing');
+            }
+            return { record, revision: snapshot.revision };
+        }
+        catch (error) {
+            throw ownershipFailure('persistence_unavailable', error instanceof Error ? error.message : String(error));
+        }
+    }
+    async save(handle) {
+        try {
+            const snapshot = this.store().compareAndSwapOwnershipTask(this.local(), handle.record.operation_id, handle.revision, handle.record);
+            handle.revision = snapshot.revision;
+        }
+        catch (error) {
+            throw ownershipFailure('persistence_unavailable', error instanceof Error ? error.message : String(error));
+        }
+    }
+    async recordError(handle, error) {
+        if (error instanceof StateError && error.stringCode === 'persistence_unavailable')
+            throw error;
+        const record = handle.record;
+        if (record.status === 'error' && record.retryable)
+            record.status = 'pending';
+        let code = error instanceof ValidationError ? 'invalid' : error instanceof StateError && error.stringCode ? error.stringCode : 'unavailable';
+        if (record.status === 'pending' && ['conflict', 'owner_locked', 'forbidden'].includes(code)) {
+            try {
+                if (await this.confirm(handle)) {
+                    await this.flush(handle);
+                    await this.cleanup(handle);
+                    return;
+                }
+            }
+            catch (confirmationError) {
+                if (confirmationError instanceof StateError && confirmationError.stringCode === 'persistence_unavailable')
+                    throw confirmationError;
+                error = confirmationError;
+                code = error instanceof ValidationError ? 'invalid' : error instanceof StateError && error.stringCode ? error.stringCode : 'unavailable';
+            }
+        }
+        record.code = code;
+        record.reason = error instanceof Error ? error.message : String(error);
+        record.retryable = record.status === 'pending' && ['unavailable', 'unsupported_protocol'].includes(code);
+        if (record.status === 'pending' && code === 'invalid')
+            record.status = 'error';
+        else if (record.status === 'pending' && ['conflict', 'owner_locked', 'forbidden'].includes(code))
+            record.status = 'stopped';
+        await this.save(handle);
+        this.emit(record, record.status === 'stopped' ? 'ownership.stopped' : 'ownership.error');
+    }
+    async runSerialized(subAid, work) {
+        const key = `${this.local()}|${subAid}`;
+        const before = OwnershipWorkflow.serial.get(key) ?? Promise.resolve();
+        const next = before.catch(() => { }).then(work);
+        OwnershipWorkflow.serial.set(key, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (OwnershipWorkflow.serial.get(key) === next)
+                OwnershipWorkflow.serial.delete(key);
+        }
+    }
+    newRecord(context, initiator, decision) {
+        const record = {
+            protocol: '2.1', operation_id: context.operation_id, operation: context.operation, sub_aid: context.sub_aid, owner_aid: context.owner_aid,
+            base_relation_version: context.base_relation_version, target_relation_version: context.target_relation_version, status: 'pending', step: 'approval', retryable: true,
+            initiator_aid: initiator, local_roles: localRoles(context, this.local()), local_decision: decision,
+            approvals: Object.fromEntries(participants(context).map((name) => [name, name === initiator ? 'accept' : 'pending'])),
+            files: {}, inbox: [], received: [], outbox: [], notices: [], request_verified: initiator === this.local(), request_notified: false,
+        };
+        if (context.operation === 'transfer')
+            record.new_owner_aid = context.new_owner_aid;
+        record.approvals[this.local()] = decision;
+        return record;
+    }
+    async start(operation, subAid, ownerAid, newOwnerAid, operationId) {
+        this.requireApplicable(subAid);
+        return this.runSerialized(subAid, async () => {
+            const existing = operationId ? this.load(operationId) : null;
+            if (existing) {
+                const record = existing.record;
+                if (record.operation !== operation || record.sub_aid !== subAid || record.owner_aid !== ownerAid || record.new_owner_aid !== newOwnerAid || record.initiator_aid !== this.local())
+                    throw ownershipFailure('conflict', 'saved registration task context changed');
+                await this.drive(existing);
+                return ownershipTaskResult(record);
+            }
+            let ns;
+            for (const snapshot of this.list()) {
+                const active = this.decode(snapshot), record = active.record;
+                if (record.sub_aid !== subAid || record.status !== 'pending' && !(record.status === 'error' && record.retryable))
+                    continue;
+                const same = record.operation === operation && record.owner_aid === ownerAid && record.new_owner_aid === newOwnerAid && record.initiator_aid === this.local();
+                try {
+                    ns = await this.readNs(subAid);
+                }
+                catch (error) {
+                    if (!same)
+                        throw error;
+                    await this.recordError(active, error);
+                    return ownershipTaskResult(record);
+                }
+                const base = ns.relation_version === record.base_relation_version && (record.operation === 'bind' ? ns.lock === 'unlocked' && !ns.owner_aid : ns.lock === 'locked' && ns.owner_aid === record.owner_aid);
+                const target = ns.relation_version === record.target_relation_version && (record.operation === 'release' ? ns.lock === 'unlocked' && !ns.owner_aid : ns.lock === 'locked' && ns.owner_aid === targetOwner(record));
+                if (!base && !target) {
+                    await this.recordError(active, ownershipFailure('conflict', 'the operation was superseded by a different relation result'));
+                    const result = ownershipTaskResult(record);
+                    if (same && result.status !== 'stopped')
+                        return result;
+                    if (result.status !== 'stopped' && result.status !== 'completed')
+                        throw ownershipFailure(record.code ?? 'unavailable', record.reason ?? 'the original target cannot be confirmed', record.retryable);
+                    continue;
+                }
+                if (!same || operationId && operationId !== record.operation_id)
+                    throw ownershipFailure('conflict', 'a different active ownership intent already exists');
+                await this.drive(active);
+                return ownershipTaskResult(record);
+            }
+            if (operation === 'transfer' && newOwnerAid === ownerAid)
+                throw ownershipFailure('invalid', 'new owner must differ from original owner');
+            ns = await this.readNs(subAid);
+            if (operation === 'bind' && ns.lock !== 'unlocked')
+                throw ownershipFailure('owner_locked', 'the current owner relation is locked');
+            if (!ns.exists)
+                throw ownershipFailure('unavailable', 'initial agent.md is not published', true);
+            if (operation === 'bind' && parseOwnershipFile(ns.content, 'agent', { expectedSubAid: subAid }).frontmatter.type === 'human')
+                throw ownershipFailure('invalid', 'human cannot declare an owner');
+            if (operation !== 'bind') {
+                const consensus = await this.deps.files.checkConsensus(subAid);
+                if (consensus.status !== 'consensus' || consensus.owner_aid !== ownerAid || consensus.relation_version !== ns.relation_version)
+                    throw ownershipFailure(consensus.status === 'invalid' ? 'invalid' : consensus.status === 'unavailable' ? consensus.code ?? 'unavailable' : 'forbidden', 'the current original owner consensus cannot be verified', consensus.status === 'unavailable');
+            }
+            ownershipInteger(ns.relation_version + 1, 'target_relation_version');
+            const record = this.newRecord({ operation_id: operationId ?? randomUUID(), operation, sub_aid: subAid, owner_aid: ownerAid, new_owner_aid: newOwnerAid, base_relation_version: ns.relation_version, target_relation_version: ns.relation_version + 1 }, this.local(), 'accept');
+            if (operation !== 'release')
+                for (const to of participants(record))
+                    if (to !== this.local())
+                        this.enqueue(record, to, operation === 'bind' ? 'bind.request' : 'transfer.request');
+            const handle = { record, revision: null };
+            await this.save(handle);
+            await this.drive(handle);
+            return ownershipTaskResult(record);
+        });
+    }
+    async decide(operationId, decision, reason) {
+        const initial = this.load(operationId);
+        if (!initial)
+            throw ownershipFailure('operation_not_found', 'no local ownership request matches operation_id');
+        return this.runSerialized(initial.record.sub_aid, async () => {
+            const handle = this.load(operationId);
+            const record = handle.record;
+            if (record.operation === 'release' || record.initiator_aid === this.local() || !record.request_verified)
+                throw ownershipFailure('forbidden', 'this task is not a verified local approval request');
+            if (record.local_decision !== 'pending') {
+                if (record.local_decision !== decision)
+                    throw ownershipFailure('conflict', 'the persisted local approval cannot be changed');
+                await this.drive(handle);
+                return ownershipTaskResult(record);
+            }
+            if (record.status === 'error' && record.retryable)
+                record.status = 'pending';
+            if (record.status !== 'pending')
+                throw ownershipFailure('conflict', 'ownership approval stage has ended');
+            const ns = await this.readNs(record.sub_aid);
+            if (ns.relation_version !== record.base_relation_version || (record.operation === 'bind' ? ns.lock !== 'unlocked' : ns.lock !== 'locked' || ns.owner_aid !== record.owner_aid))
+                throw ownershipFailure('conflict', 'the original relation changed before approval');
+            record.local_decision = decision;
+            record.approvals[this.local()] = decision;
+            this.enqueue(record, record.initiator_aid, `${record.operation}.${decision === 'accept' ? 'accept' : 'reject'}`, reason);
+            if (decision === 'reject') {
+                record.status = 'rejected';
+                record.step = 'approval';
+                record.retryable = false;
+                if (reason !== undefined)
+                    record.reason = reason;
+            }
+            await this.save(handle);
+            this.emit(record, decision === 'reject' ? 'ownership.rejected' : 'ownership.progress');
+            await this.drive(handle);
+            return ownershipTaskResult(record);
+        });
+    }
+    enqueue(record, to, action, reason) {
+        if (to === this.local())
+            return;
+        const key = `${to}|${action}`;
+        if (record.notices.includes(key))
+            return;
+        const payload = { type: OWNERSHIP_SDK_MESSAGE_TYPE, operation_id: record.operation_id, operation: record.operation, action,
+            sub_aid: record.sub_aid, owner_aid: record.owner_aid, base_relation_version: record.base_relation_version, target_relation_version: record.target_relation_version };
+        if (record.operation === 'transfer')
+            payload.new_owner_aid = record.new_owner_aid;
+        if (reason !== undefined)
+            payload.reason = reason;
+        record.outbox.push({ to, payload });
+        record.notices.push(key);
+    }
+    async flush(handle) {
+        while (handle.record.outbox.length) {
+            const message = handle.record.outbox[0];
+            const ns = await this.readNs(handle.record.sub_aid);
+            const record = handle.record;
+            const base = ns.relation_version === record.base_relation_version && (record.operation === 'bind' ? ns.lock === 'unlocked' && !ns.owner_aid : ns.lock === 'locked' && ns.owner_aid === record.owner_aid);
+            const target = ns.relation_version === record.target_relation_version && (record.operation === 'release' ? ns.lock === 'unlocked' && !ns.owner_aid : ns.lock === 'locked' && ns.owner_aid === targetOwner(record));
+            const requiresTarget = ['relation.confirmed', 'sub.cleaned'].includes(message.payload.action);
+            if (requiresTarget ? !target : !base) {
+                record.outbox.shift();
+                await this.save(handle);
+                continue;
+            }
+            if (message.payload.action === 'transfer.ready' && record.status !== 'completed') {
+                const expiresAt = record.files.transfer?.expires_at;
+                if (typeof expiresAt !== 'number' || !Number.isSafeInteger(expiresAt) || expiresAt <= 0)
+                    throw ownershipFailure('persistence_unavailable', 'persisted transfer authorization expiry is missing or invalid');
+                if (expiresAt <= Math.trunc(Date.now() / 1000))
+                    throw ownershipFailure('conflict', 'transfer authorization expired');
+            }
+            await this.deps.send(message.to, message.payload);
+            handle.record.outbox.shift();
+            await this.save(handle);
+        }
+    }
+    async readNs(subAid) {
+        const ns = await this.deps.files.readAgent(subAid);
+        const file = ns.exists && !(ns.lock === 'unlocked' && ns.relation_version > 0) ? await this.deps.files.verifyFile(ns.content, 'agent', subAid) : undefined;
+        if (ns.lock === 'unlocked' && ns.relation_version === 0 && file?.statement)
+            throw ownershipFailure('unavailable', 'NS relation metadata does not match agent.md', true);
+        const currentOwner = ns.lock === 'locked' ? file?.statement?.owner_aid : null;
+        if (ns.lock === 'locked' && (!file?.statement || file.statement.relation_version !== ns.relation_version) || ns.owner_aid !== undefined && ns.owner_aid !== currentOwner)
+            throw ownershipFailure('unavailable', 'NS owner metadata and signed agent.md do not agree', true);
+        return { ...ns, owner_aid: currentOwner };
+    }
+    async processInbox(handle) {
+        const record = handle.record;
+        while (record.inbox.length) {
+            const item = record.inbox[0];
+            const ns = await this.readNs(record.sub_aid);
+            try {
+                parseOwnershipMessage(item.payload, { authenticated_from_aid: item.from, local_aid: this.local(), task: record, ns });
+            }
+            catch (error) {
+                record.inbox.shift();
+                record.received.push(`${item.from}|${item.payload.operation_id}|${item.payload.action}`);
+                if (record.status === 'pending' && ['bind.request', 'transfer.request'].includes(item.payload.action)) {
+                    record.status = 'stopped';
+                    record.step = 'conflict';
+                    record.retryable = false;
+                }
+                await this.save(handle);
+                this.emit(record, 'ownership.error', { code: error instanceof StateError ? error.stringCode : 'invalid', reason: error instanceof Error ? error.message : String(error), retryable: false });
+                continue;
+            }
+            const action = item.payload.action;
+            if (['bind.request', 'transfer.request'].includes(action))
+                record.request_verified = true;
+            if (['bind.accept', 'transfer.accept', 'bind.reject', 'transfer.reject'].includes(action)) {
+                if (record.approvals[item.from] === 'pending' && record.status === 'pending') {
+                    const rejected = action.endsWith('.reject');
+                    record.approvals[item.from] = rejected ? 'reject' : 'accept';
+                    if (rejected) {
+                        record.status = 'rejected';
+                        record.step = 'approval';
+                        record.retryable = false;
+                        if (item.payload.reason !== undefined)
+                            record.reason = item.payload.reason;
+                        if (record.operation === 'transfer')
+                            for (const to of participants(record))
+                                if (to !== item.from)
+                                    this.enqueue(record, to, 'operation.stopped', item.payload.reason);
+                    }
+                }
+            }
+            if (action === 'operation.stopped' && record.status === 'pending' && !(await this.confirm(handle))) {
+                record.status = 'stopped';
+                record.step = 'stopped';
+                record.retryable = false;
+            }
+            if (action === 'sub.cleaned') {
+                const file = parseOwnershipFile(ns.content, 'agent', { expectedSubAid: record.sub_aid });
+                if (!file.statement)
+                    record.cleanup_status = 'cleaned';
+            }
+            if (record.operation === 'release')
+                record.request_verified = true;
+            record.inbox.shift();
+            record.received.push(`${item.from}|${item.payload.operation_id}|${action}`);
+            const request = record.request_verified && record.local_decision === 'pending' && record.operation !== 'release' && !record.request_notified;
+            if (request)
+                record.request_notified = true;
+            await this.save(handle);
+            if (request)
+                this.emit(record, 'ownership.request');
+            if (record.status === 'rejected')
+                this.emit(record, 'ownership.rejected');
+            if (record.status === 'stopped')
+                this.emit(record, 'ownership.stopped');
+        }
+    }
+    fileTask(handle) {
+        const record = handle.record;
+        const task = { operation_id: record.operation_id, operation: record.operation, sub_aid: record.sub_aid, owner_aid: record.owner_aid,
+            new_owner_aid: record.new_owner_aid, base_relation_version: record.base_relation_version, target_relation_version: record.target_relation_version,
+            files: record.files, authorization_sha256: record.authorization_sha256, expires_at: record.expires_at,
+            persist: async () => {
+                record.authorization_sha256 = task.authorization_sha256;
+                record.expires_at = task.expires_at;
+                if (record.operation === 'transfer' && task.authorization_sha256 !== undefined && task.expires_at !== undefined && record.step === 'approval')
+                    record.step = this.local() === targetOwner(record) ? 'owner' : 'agent';
+                await this.save(handle);
+            } };
+        return task;
+    }
+    async drive(handle) {
+        const record = handle.record;
+        if (record.status === 'error' && record.retryable) {
+            record.status = 'pending';
+            await this.save(handle);
+        }
+        try {
+            await this.processInbox(handle);
+            await this.flush(handle);
+            if (record.status === 'rejected' || record.status === 'stopped' || record.status === 'error')
+                return;
+            if (!record.request_verified)
+                return;
+            if (record.status === 'completed') {
+                const observed = await this.deps.files.checkConsensus(record.sub_aid);
+                await this.resumeSubCleanup(handle, observed);
+                if (await this.confirm(handle, observed))
+                    await this.cleanup(handle);
+                await this.flush(handle);
+                return;
+            }
+            if (record.operation === 'release') {
+                if (await this.confirm(handle)) {
+                    await this.cleanup(handle);
+                    await this.flush(handle);
+                    return;
+                }
+                if (this.local() === record.owner_aid) {
+                    record.step = 'release';
+                    await this.save(handle);
+                    await this.deps.files.revokeSubaid(this.fileTask(handle));
+                }
+                if (await this.confirm(handle))
+                    await this.cleanup(handle);
+                await this.flush(handle);
+                return;
+            }
+            if (record.local_decision !== 'accept')
+                return;
+            if (await this.confirm(handle)) {
+                await this.cleanup(handle);
+                await this.flush(handle);
+                return;
+            }
+            const ns = await this.readNs(record.sub_aid);
+            if (ns.relation_version !== record.base_relation_version || record.operation === 'bind' && ns.lock !== 'unlocked' || record.operation === 'transfer' && (ns.lock !== 'locked' || ns.owner_aid !== record.owner_aid)) {
+                throw ownershipFailure('conflict', 'the original relation was replaced');
+            }
+            if (record.expires_at !== undefined && record.expires_at <= Math.trunc(Date.now() / 1000))
+                throw ownershipFailure('conflict', 'transfer authorization expired');
+            const approved = participants(record).every((name) => record.approvals[name] === 'accept');
+            if (record.operation === 'bind' && !approved || record.operation === 'transfer' && this.local() === record.owner_aid && !approved)
+                return;
+            delete record.code;
+            delete record.reason;
+            record.retryable = true;
+            if (record.operation === 'transfer' && this.local() === record.owner_aid) {
+                record.step = 'transfer';
+                await this.save(handle);
+                await this.deps.files.transferOwneraid(this.fileTask(handle));
+                for (const to of participants(record))
+                    this.enqueue(record, to, 'transfer.ready');
+                await this.save(handle);
+                await this.flush(handle);
+            }
+            if (record.operation === 'transfer') {
+                const original = await this.deps.files.readOwner(record.owner_aid, record.sub_aid);
+                if (original.exists && (await this.deps.files.verifyFile(original.content, 'owner', record.sub_aid, record.owner_aid)).action === 'declare')
+                    return;
+                await this.deps.files.requireTransfer(this.fileTask(handle));
+            }
+            if (this.local() === targetOwner(record)) {
+                record.step = 'owner';
+                await this.save(handle);
+                await this.deps.files.declareSubaid(this.fileTask(handle));
+                this.enqueue(record, record.sub_aid, 'owner.ready');
+                await this.save(handle);
+                await this.flush(handle);
+            }
+            if (this.local() === record.sub_aid) {
+                record.step = 'agent';
+                await this.save(handle);
+                await this.deps.files.declareOwneraid(this.fileTask(handle));
+            }
+            const completed = await this.confirm(handle);
+            await this.flush(handle);
+            if (completed)
+                await this.cleanup(handle);
+        }
+        catch (error) {
+            await this.recordError(handle, error);
+        }
+    }
+    async confirm(handle, observed) {
+        const record = handle.record;
+        const result = observed ?? await this.deps.files.checkConsensus(record.sub_aid, record.operation === 'release' ? undefined : { owner_aid: targetOwner(record), relation_version: record.target_relation_version });
+        if (result.status === 'invalid' || result.status === 'unavailable')
+            throw ownershipFailure(result.code ?? result.status, result.reason ?? 'ownership consensus cannot be verified', result.retryable);
+        const reached = result.relation_version === record.target_relation_version && (record.operation === 'release' ? result.status === 'released' && result.lock === 'unlocked' : result.status === 'consensus' && result.owner_aid === targetOwner(record));
+        if (!reached)
+            return false;
+        if (record.operation === 'release' && record.local_roles.includes('owner') && !record.files.release)
+            throw ownershipFailure('conflict', 'local release file evidence is missing');
+        if (record.operation === 'transfer' && record.local_roles.includes('owner') && !record.files.transfer)
+            throw ownershipFailure('conflict', 'local transfer file evidence is missing');
+        if (record.operation === 'release' && this.local() === record.sub_aid && record.local_decision !== 'accept') {
+            const ns = await this.deps.files.readAgent(record.sub_aid);
+            if (parseOwnershipFile(ns.content, 'agent', { expectedSubAid: record.sub_aid }).statement) {
+                record.step = 'cleanup';
+                if (record.cleanup_status !== 'action_required') {
+                    record.cleanup_status = 'action_required';
+                    await this.save(handle);
+                    this.emit(record, 'ownership.action_required');
+                }
+                return false;
+            }
+        }
+        if (record.operation !== 'release' && (record.local_decision !== 'accept' || this.local() === record.sub_aid && (!record.files.agent || record.files.agent.hash !== result.agent_md_sha256) || this.local() === targetOwner(record) && (!record.files.owner || record.files.owner.hash !== result.owner_md_sha256)))
+            return false;
+        if (record.status !== 'completed' && record.operation !== 'release' && (this.local() === record.sub_aid && record.files.agent?.published_revision !== undefined && record.files.agent.published_revision !== result.agent_md_etag || this.local() === targetOwner(record) && record.files.owner?.published_revision !== undefined && record.files.owner.published_revision !== result.owner_md_revision))
+            throw ownershipFailure('conflict', 'published ownership file revision changed');
+        if (record.status !== 'completed') {
+            record.status = 'completed';
+            record.step = 'confirmed';
+            record.verified_relation_version = result.relation_version;
+            record.completion_evidence = { ...result };
+            delete record.code;
+            delete record.reason;
+            record.retryable = false;
+            if (record.operation === 'release' && this.local() === record.owner_aid)
+                this.enqueue(record, record.sub_aid, 'relation.confirmed');
+            else if (record.operation !== 'release' && this.local() === record.sub_aid)
+                for (const to of participants(record))
+                    this.enqueue(record, to, 'relation.confirmed');
+            await this.save(handle);
+            this.emit(record, 'ownership.completed');
+        }
+        return true;
+    }
+    async resumeSubCleanup(handle, observed) {
+        const record = handle.record;
+        if (!['bind', 'transfer'].includes(record.operation) || !record.local_roles.includes('sub') || record.local_decision !== 'accept' || observed.status !== 'released' || observed.relation_version !== record.target_relation_version + 1 || record.release_cleanup?.cleaned)
+            return;
+        const ns = await this.readNs(record.sub_aid);
+        if (!ns.exists || ns.lock !== 'unlocked' || ns.relation_version !== observed.relation_version || ns.etag !== observed.agent_md_etag || ownershipSha256(ns.content) !== observed.agent_md_sha256)
+            throw ownershipFailure('unavailable', 'NS changed during historical cleanup observation', true);
+        const statement = parseOwnershipFile(ns.content, 'agent', { expectedSubAid: record.sub_aid }).statement;
+        if (statement && (statement.owner_aid !== targetOwner(record) || statement.relation_version !== record.target_relation_version))
+            throw ownershipFailure('conflict', 'historical cleanup fields belong to another relation');
+        if (!record.release_cleanup) {
+            record.release_cleanup = { files: {}, cleaned: false };
+            await this.save(handle);
+        }
+        await this.deps.files.revokeOwneraid({ operation: 'release', sub_aid: record.sub_aid, owner_aid: targetOwner(record),
+            base_relation_version: record.target_relation_version, target_relation_version: observed.relation_version,
+            files: record.release_cleanup.files, persist: () => this.save(handle) });
+        record.release_cleanup.cleaned = true;
+        await this.save(handle);
+        this.emit(record, 'ownership.progress');
+    }
+    cleanupAuthorization(task) {
+        for (const snapshot of this.list()) {
+            const candidate = this.decode(snapshot).record;
+            if (['bind', 'transfer'].includes(candidate.operation) && candidate.local_decision === 'accept' && candidate.local_roles.includes('sub') && candidate.sub_aid === task.sub_aid && targetOwner(candidate) === task.owner_aid && candidate.target_relation_version === task.base_relation_version)
+                return candidate;
+        }
+        return undefined;
+    }
+    async cleanup(handle) {
+        const record = handle.record;
+        if (record.operation === 'bind')
+            return;
+        if (record.operation === 'release' && this.local() === record.sub_aid && record.cleanup_status !== 'cleaned') {
+            const ns = await this.readNs(record.sub_aid);
+            if (ns.exists && ns.lock === 'unlocked' && ns.relation_version === record.target_relation_version && !parseOwnershipFile(ns.content, 'agent', { expectedSubAid: record.sub_aid }).statement) {
+                record.cleanup_status = 'cleaned';
+                await this.save(handle);
+            }
+            else {
+                const authorization = this.cleanupAuthorization(record);
+                if (!authorization || record.cleanup_authorization_id && authorization.operation_id !== record.cleanup_authorization_id) {
+                    if (record.cleanup_status !== 'action_required') {
+                        record.cleanup_status = 'action_required';
+                        await this.save(handle);
+                        this.emit(record, 'ownership.action_required');
+                    }
+                }
+                else {
+                    record.cleanup_authorization_id = authorization.operation_id;
+                    await this.save(handle);
+                    await this.deps.files.revokeOwneraid(this.fileTask(handle));
+                    record.cleanup_status = 'cleaned';
+                    this.enqueue(record, record.owner_aid, 'sub.cleaned');
+                    await this.save(handle);
+                }
+            }
+        }
+        if (this.local() === record.owner_aid && !record.files.cleanup?.deleted)
+            await this.deps.files.cleanupOwnerFile(this.fileTask(handle));
+    }
+    emit(record, event, extra = {}) {
+        const payload = { ...ownershipTaskResult(record), local_roles: [...record.local_roles], ...extra };
+        if (event === 'ownership.request')
+            payload.requester_aid = record.initiator_aid;
+        if (record.verified_relation_version !== undefined)
+            payload.relation_version = record.verified_relation_version;
+        queueMicrotask(() => { try {
+            const pending = this.deps.emit(event, payload);
+            if (pending)
+                void pending.catch(() => { });
+        }
+        catch { } });
+    }
+}
+//# sourceMappingURL=ownership-workflow.js.map