@agentunion/fastaun 0.5.19 → 0.5.21

package/dist/agent-md.js

@@ -3,15 +3,26 @@ import * as fs from 'node:fs';
 import * as http from 'node:http';
 import * as https from 'node:https';
 import * as path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 import { parseDocument } from 'yaml';
 import { AID } from './aid.js';
-import { certMatchesFingerprint, parseAgentMdTailSignature } from './cert-utils.js';
-import { parseFileFrontmatter, validateAgentMdDocument, verifyAgentMdUpload } from './agent-md-schema.js';
+import { certMatchesFingerprint, normalizeFingerprintHex, parseAgentMdTailSignature, publicKeyMatchesFingerprint, verifyDocument } from './cert-utils.js';
+import { parseFileFrontmatter, validateAgentMdDocument, validateAgentMdReadDocument, verifyAgentMdBodyUpdate, verifyAgentMdUpload } from './agent-md-schema.js';
 import { validateOwnershipFrontmatter, verifyOwnershipFrontmatterStatus } from './ownership-proof.js';
 import { AUNError, ClientSignatureError, NotFoundError, StateError, ValidationError, } from './errors.js';
 import { isJsonObject } from './types.js';
-import { ownershipFailure, parseOwnershipFile } from './ownership-v21.js';
+import { ownershipAid, ownershipFailure, parseOwnershipFile } from './ownership-v21.js';
+import { resultOk } from './result.js';
 const DEFAULT_HTTP_TIMEOUT_MS = 30_000;
+function relationshipFields(meta) {
+    return Object.fromEntries(['owner', 'ownership', 'ownership_proof', 'ownership_release'].filter((key) => Object.hasOwn(meta, key)).map((key) => [key, meta[key]]));
+}
+function legacyRelationship(meta) {
+    if (['group', 'org'].includes(String(meta.type)))
+        return undefined;
+    const fields = relationshipFields(meta);
+    return Object.keys(fields).length ? fields : undefined;
+}
 const AGENT_MD_NEGATIVE_CACHE_TTL_MS = 60_000;
 export function buildOwnershipReleaseAgentMd(content, release) {
     return updateOwnershipAgentMd(content, { ownership_release: release });
@@ -21,7 +32,7 @@ export function buildOwnershipAgentMd(content, owner, proof) {
 }
 export function updateOwnershipAgentMd(content, fields) {
     const payload = parseAgentMdTailSignature(String(content ?? '')).payload;
-    const match = /^---(?:\r\n|\n|\r)([\s\S]*?)(?:\r\n|\n|\r)---([\s\S]*)$/.exec(payload);
+    const match = /^\ufeff?---(?:\r\n|\n|\r)([\s\S]*?)(?:\r\n|\n|\r)---([\s\S]*)$/.exec(payload);
     if (!match)
         throw new ValidationError('agent.md must start with YAML frontmatter');
     const document = parseDocument(match[1], { uniqueKeys: true });
@@ -37,7 +48,7 @@ export function updateOwnershipAgentMd(content, fields) {
     for (const [name, value] of Object.entries(fields))
         document.set(name, value);
     const yamlText = document.toString().replace(/\r\n/g, '\n');
-    const updated = `---\n${yamlText.endsWith('\n') ? yamlText : `${yamlText}\n`}---${match[2]}`;
+    const updated = `${payload.startsWith('\ufeff') ? '\ufeff' : ''}---\n${yamlText.endsWith('\n') ? yamlText : `${yamlText}\n`}---${match[2]}`;
     validateAgentMdDocument(updated, { expectedAid: String(frontmatter.aid ?? '') });
     return updated;
 }
@@ -251,12 +262,12 @@ export class AgentMdManager {
         this._atomicWriteText(filePath, String(content ?? ''));
         return filePath;
     }
-    loadRecord(aid) {
+    _loadRecord(aid, strict = false) {
         const target = String(aid ?? '').trim();
         if (!target)
             return null;
         try {
-            const record = this._withRecordLock(target, () => this._readRecordUnlocked(target));
+            const record = this._withRecordLock(target, () => this._readRecordUnlocked(target, strict));
             const loaded = Object.keys(record).length > 0 ? { ...record, aid: target } : { aid: target };
             try {
                 const content = this.readContent(target);
@@ -270,7 +281,7 @@ export class AgentMdManager {
             }
             if (Object.keys(loaded).length <= 1)
                 return null;
-            if (Object.keys(record).length === 0 && typeof loaded.content === 'string') {
+            if (Object.keys(record).length === 0 && typeof loaded.content === 'string' && !fs.existsSync(this.metaPath(target))) {
                 this._withRecordLock(target, () => this._writeRecordUnlocked(target, {
                     aid: target,
                     local_etag: loaded.local_etag,
@@ -281,11 +292,16 @@ export class AgentMdManager {
             return { ...loaded };
         }
         catch (err) {
+            if (strict)
+                throw err;
             this._log.debug(`agent.md cache load skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
             return null;
         }
     }
-    saveRecord(aid, fields) {
+    loadRecord(aid) {
+        return this._loadRecord(aid);
+    }
+    _saveRecord(aid, fields, strict = false) {
         const target = String(aid ?? '').trim();
         if (!target)
             return {};
@@ -294,6 +310,7 @@ export class AgentMdManager {
             const hasContent = Object.prototype.hasOwnProperty.call(inputFields, 'content') && inputFields.content !== undefined && inputFields.content !== null;
             let savedTo = '';
             const record = this._withRecordLock(target, () => {
+                const next = { ...this._readRecordUnlocked(target, true), aid: target };
                 if (hasContent) {
                     const content = String(inputFields.content ?? '');
                     savedTo = this.writeContent(target, content);
@@ -303,7 +320,6 @@ export class AgentMdManager {
                         inputFields.fetched_at = Date.now();
                 }
                 delete inputFields.content;
-                const next = { ...this._readRecordUnlocked(target), aid: target };
                 for (const [key, value] of Object.entries(inputFields)) {
                     if (value !== undefined && value !== null)
                         next[key] = value;
@@ -319,7 +335,7 @@ export class AgentMdManager {
                     loaded.saved_to = savedTo;
             }
             else {
-                const current = this.loadRecord(target);
+                const current = this._loadRecord(target, strict);
                 if (current && typeof current.content === 'string')
                     loaded.content = current.content;
             }
@@ -327,11 +343,27 @@ export class AgentMdManager {
             return { ...loaded };
         }
         catch (err) {
+            if (strict)
+                throw err;
             this._log.debug(`agent.md cache save skipped: aid=${target} err=${err instanceof Error ? err.message : String(err)}`);
             return {};
         }
     }
-    async upload(content) {
+    saveRecord(aid, fields) {
+        return this._saveRecord(aid, fields, Object.prototype.hasOwnProperty.call(fields, 'local_draft_content'));
+    }
+    _clearConfirmedDraft(aid, content) {
+        this._withRecordLock(aid, () => {
+            const record = this._readRecordUnlocked(aid, true);
+            if (record.local_draft_content !== content)
+                return;
+            record.local_draft_content = '';
+            record.updated_at = Date.now();
+            this._writeRecordUnlocked(aid, record);
+        });
+        this._cache.delete(aid);
+    }
+    async upload(content, originalCondition) {
         const target = this._ownerAid();
         if (!target)
             throw new ValidationError('uploadAgentMd requires local AID');
@@ -339,28 +371,57 @@ export class AgentMdManager {
         if (!current?.isPrivateKeyValid()) {
             throw new StateError('uploadAgentMd requires loaded AID with a valid private key');
         }
-        const rawContent = content === undefined || content === null ? this.readContent(target) : String(content);
+        const rawContent = content === undefined || content === null ? String(this._loadRecord(target, true)?.local_draft_content ?? '') || this.readContent(target) : String(content);
         if (!rawContent.trim())
             throw new ValidationError('uploadAgentMd requires non-empty content');
-        const parsed = validateAgentMdDocument(rawContent, { expectedAid: target });
+        const parsed = validateAgentMdDocument(rawContent, { expectedAid: target, validateOwnership: false });
         if (['group', 'org'].includes(String(parsed.frontmatter.type)))
             return await this.uploadAs(target, rawContent, current);
+        if (parseAgentMdTailSignature(rawContent).signatures.length > 1) {
+            await this._verifyDocument(rawContent, target, current, true, true);
+            return await this._uploadPrepared(target, rawContent, current, originalCondition);
+        }
         const signed = current.signAgentMd(rawContent);
         if (!signed.ok || !signed.data) {
             const message = signed.error?.message ?? 'agent.md signing failed';
             throw new ClientSignatureError(message);
         }
         const signedContent = signed.data.signed;
-        verifyAgentMdUpload(signedContent, current.certPem, target);
-        return await this._uploadPrepared(target, signedContent, current);
+        verifyAgentMdBodyUpdate(signedContent, current.certPem, target);
+        return await this._uploadPrepared(target, signedContent, current, originalCondition);
+    }
+    async readAgentMdFresh(aid) {
+        const target = this.safeAid(aid), gateway = await this._resolveGateway(target);
+        const response = await requestText(this._url(target, gateway, this._uploadViaGatewayHost), {
+            method: 'GET', verifySsl: this._verifySsl,
+            headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache', ...(this._uploadViaGatewayHost ? { Host: target } : {}) },
+            timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true,
+        });
+        if (response.status === 404)
+            return { exists: false, content: '', etag: '' };
+        if (response.status !== 200)
+            throw ownershipFailure('unavailable', `agent.md fresh read failed: HTTP ${response.status}`, true);
+        const etag = headerValue(response.headers, 'ETag');
+        if (!etag)
+            throw ownershipFailure('unavailable', 'agent.md fresh read has no ETag', true);
+        return { exists: true, content: response.text, etag };
     }
     async readOwnershipFresh(aid) {
         const target = this.safeAid(aid);
         const response = await this._ownershipRequest(target, 'GET');
+        if ([200, 400, 404].includes(response.status) && headerValue(response.headers, 'X-AUN-Ownership-Status') === 'not_applicable')
+            throw ownershipFailure('not_applicable', 'group/org uses its lifecycle owner relationship');
+        if (response.status === 400) {
+            let value;
+            try {
+                value = JSON.parse(response.text);
+            }
+            catch { }
+            if (isJsonObject(value) && value.error === 'invalid')
+                throw ownershipFailure('invalid', 'NS rejected the current agent.md: HTTP 400');
+        }
         if (response.status !== 200 && response.status !== 404)
             throw ownershipFailure('unavailable', `NS fresh read failed: HTTP ${response.status}`, true);
-        if (headerValue(response.headers, 'X-AUN-Ownership-Status') === 'not_applicable')
-            throw ownershipFailure('not_applicable', 'group/org uses its lifecycle owner relationship');
         let type;
         if (response.status === 200) {
             try {
@@ -380,7 +441,7 @@ export class AgentMdManager {
             throw ownershipFailure('unavailable', 'NS fresh metadata is incomplete', true);
         return { sub_aid: target, exists: response.status === 200, content: response.status === 200 ? response.text : '', etag, protocol, relation_version: Number(version), lock: lock, observed_at: Math.floor(Date.now() / 1000) };
     }
-    async submitOwnershipRaw(aid, raw, condition) {
+    async submitOwnershipRaw(aid, raw, condition, assertActive) {
         const target = this.safeAid(aid), current = this._currentAid();
         if (!current?.isPrivateKeyValid() || current.aid !== target || this._ownerAid() !== target)
             throw ownershipFailure('forbidden', 'raw agent.md submission requires its own authenticated identity');
@@ -388,24 +449,25 @@ export class AgentMdManager {
             throw new ValidationError('raw agent.md requires one original condition');
         parseOwnershipFile(raw, 'agent', { expectedSubAid: target });
         verifyAgentMdUpload(raw, current.certPem, target);
-        const response = await this._ownershipRequest(target, 'PUT', raw, condition);
+        const response = await this._ownershipRequest(target, 'PUT', raw, condition, false, assertActive);
         if (response.status === 409 || response.status === 412)
             throw ownershipFailure('conflict', `NS original condition failed: HTTP ${response.status}`);
         if (response.status === 428)
             throw ownershipFailure('unsupported_protocol', 'NS does not support the required original document condition');
         if (response.status === 401 || response.status === 403)
             throw ownershipFailure('forbidden', `NS self submission denied: HTTP ${response.status}`);
+        if (response.status === 400)
+            throw ownershipFailure('invalid', 'NS rejected the submitted agent.md: HTTP 400');
         if (response.status < 200 || response.status >= 300)
             throw ownershipFailure('unavailable', `NS raw submission failed: HTTP ${response.status}`, true);
         const fresh = await this.readOwnershipFresh(target);
         if (fresh.content !== raw)
             throw ownershipFailure('unavailable', 'NS raw submission cannot be confirmed from the current document', true);
-        this.saveRecord(target, { content: raw, local_etag: AgentMdManager.contentEtag(raw), remote_etag: fresh.etag, fetched_at: Date.now(), checked_at: Date.now(), remote_status: 'found' });
         return fresh;
     }
-    async _ownershipRequest(target, method, raw, condition) {
+    async _ownershipRequest(target, method, raw, condition, legacyRead = false, assertActive) {
         const gatewayUrl = await this._resolveGateway(target);
-        const headers = { Accept: 'text/markdown', 'Cache-Control': 'no-cache', 'X-AUN-Ownership-Check': '1' };
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown', 'Cache-Control': 'no-cache', ...(!legacyRead ? { 'X-AUN-Ownership-Check': '1' } : {}) };
         if (method === 'PUT') {
             headers['Content-Type'] = 'text/markdown; charset=utf-8';
             headers.Authorization = `Bearer ${await this._uploadAccessToken(target, gatewayUrl)}`;
@@ -417,11 +479,13 @@ export class AgentMdManager {
         const viaGateway = this._uploadViaGatewayHost;
         if (viaGateway)
             headers.Host = target;
-        const request = (url) => requestText(url, { method, verifySsl: this._verifySsl, headers, body: raw, timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true });
-        let response = await request(this._url(target, gatewayUrl, viaGateway));
+        const request = (url) => { if (method === 'PUT')
+            assertActive?.(); return requestText(url, { method, verifySsl: this._verifySsl, headers, body: raw, timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true }); };
+        const primary = this._url(target, gatewayUrl, viaGateway);
+        let response = await request(primary);
         if (response.status === 404 && !headerValue(response.headers, 'X-AUN-Ownership-Protocol') && headerValue(response.headers, 'X-AUN-Ownership-Status') !== 'not_applicable') {
             const fallback = nameServiceAgentMdUrl(target, gatewayUrl);
-            if (fallback && fallback !== this._url(target, gatewayUrl, viaGateway)) {
+            if (fallback && fallback !== primary) {
                 headers.Host = target;
                 response = await request(fallback);
             }
@@ -433,31 +497,42 @@ export class AgentMdManager {
         const rawContent = String(content ?? '');
         if (!rawContent.trim())
             throw new ValidationError('uploadAgentMd requires non-empty content');
-        const parsed = validateAgentMdDocument(rawContent, { expectedAid: target });
+        const parsed = validateAgentMdDocument(rawContent, { expectedAid: target, validateOwnership: false });
         if (['group', 'org'].includes(String(parsed.frontmatter.type)) && parsed.signature) {
             const identity = await this._entitySigningIdentity(target, parsed.frontmatter, parsed.signature, signer);
-            verifyAgentMdUpload(rawContent, identity.certPem, target);
+            await this._verifyDocument(rawContent, target, identity, true);
             return await this._uploadPrepared(target, rawContent, identity);
         }
+        if (['group', 'org'].includes(String(parsed.frontmatter.type)) && signer.aid !== target) {
+            const identity = await this._entityIdentityGetter?.(target, String(parsed.frontmatter.type));
+            if (!identity?.isPrivateKeyValid())
+                throw new StateError('entity agent.md signing requires its local private key');
+            signer = identity;
+        }
         if (!signer?.isPrivateKeyValid())
             throw new StateError('uploadAgentMd requires a valid signer identity');
-        if (['group', 'org'].includes(String(parsed.frontmatter.type)))
-            await this._entityContext(target, parsed.frontmatter, signer);
+        if (parseAgentMdTailSignature(rawContent).signatures.length > 1) {
+            await this._verifyDocument(rawContent, target, signer, true, true);
+            return await this._uploadPrepared(target, rawContent, signer);
+        }
         const signed = signer.signAgentMd(rawContent);
         if (!signed.ok || !signed.data) {
             const message = signed.error?.message ?? 'agent.md signing failed';
             throw new ClientSignatureError(message);
         }
         const signedContent = signed.data.signed;
-        verifyAgentMdUpload(signedContent, signer.certPem, target);
+        verifyAgentMdBodyUpdate(signedContent, signer.certPem, target);
         return await this._uploadPrepared(target, signedContent, signer);
     }
-    pendingUpload(aid) {
-        const record = this.loadRecord(aid);
+    _pendingUpload(aid, strict = false) {
+        const record = this._loadRecord(aid, strict);
         if (record?.pending_operation !== 'replace' || !String(record.pending_content ?? '').trim())
             return null;
         return { content: String(record.pending_content), content_etag: String(record.pending_content_etag ?? ''), last_error: String(record.pending_error ?? ''), condition: record.pending_condition, relation: record.pending_relation, authorization: record.pending_authorization };
     }
+    pendingUpload(aid) {
+        return this._pendingUpload(aid, true);
+    }
     async resumePendingUpload(aid, signer) {
         const pending = this.pendingUpload(aid);
         if (!pending)
@@ -467,9 +542,32 @@ export class AgentMdManager {
             throw ownershipFailure('persistence_unavailable', 'pending agent.md requires its original document condition');
         const parsed = validateAgentMdDocument(pending.content, { expectedAid: aid, validateOwnership: false });
         const meta = parsed.frontmatter;
-        if ('ownership_proof' in meta || 'ownership_release' in meta)
-            throw ownershipFailure('unsupported_protocol', 'legacy ownership pending agent.md cannot be recovered through ordinary upload');
         try {
+            if (pending.relation?.legacy === true)
+                return await this._resumeLegacyBodyUpload(aid, pending, signer ?? this._currentAid());
+            if (legacyRelationship(meta) && pending.relation && Object.keys(pending.relation).length === 4 && ['relation_version', 'lock', 'owner_aid', 'statement'].every((field) => Object.hasOwn(pending.relation, field))) {
+                const relation = pending.relation, statement = parseOwnershipFile(pending.content, 'agent', { expectedSubAid: aid }).statement;
+                if (!statement || !isDeepStrictEqual(statement, relation.statement) || statement.relation_version !== relation.relation_version || statement.owner_aid !== relation.owner_aid || !['locked', 'unlocked'].includes(String(relation.lock)) || pending.content_etag !== AgentMdManager.contentEtag(pending.content))
+                    throw ownershipFailure('persistence_unavailable', 'pending original relationship context is corrupt');
+                const identity = signer ?? this._currentAid();
+                if (!identity || identity.aid !== aid || this._currentAid()?.aid !== aid || this._ownerAid() !== aid)
+                    throw ownershipFailure('forbidden', 'body recovery requires its current subject identity');
+                await this._verifyDocument(pending.content, aid, identity, true, true);
+                const remote = await this.readAgentMdFresh(aid);
+                if (!remote.exists || !isDeepStrictEqual(legacyRelationship(meta), legacyRelationship(validateAgentMdReadDocument(remote.content, { expectedAid: aid }).frontmatter)))
+                    throw ownershipFailure('conflict', 'pending agent.md relationship material changed');
+                if (remote.etag === pending.content_etag && remote.content === pending.content) {
+                    this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+                    this._clearConfirmedDraft(aid, pending.content);
+                    return true;
+                }
+                if (!condition.if_match || remote.etag !== condition.if_match)
+                    throw ownershipFailure('conflict', 'pending agent.md original document condition changed');
+                await this._uploadPrepared(aid, pending.content, identity, condition);
+                return true;
+            }
+            if (legacyRelationship(meta))
+                throw ownershipFailure('unsupported_protocol', 'legacy ownership pending agent.md requires its original relationship snapshot');
             if (['group', 'org'].includes(String(meta.type))) {
                 if (!parsed.signature)
                     throw ownershipFailure('invalid', 'pending entity agent.md requires a signature');
@@ -483,13 +581,13 @@ export class AgentMdManager {
                     throw ownershipFailure('conflict', 'pending entity upload belongs to an old rekey generation');
                 if (pending.content_etag !== AgentMdManager.contentEtag(pending.content))
                     throw ownershipFailure('persistence_unavailable', 'pending entity original bytes are corrupt');
-                verifyAgentMdUpload(pending.content, identity.certPem, aid);
-                const uploader = this._currentAid();
-                if (uploader.aid.toLowerCase() !== aid.toLowerCase())
-                    this._validateEntityUploadAuthorization(pending.authorization, aid, pending.content, uploader, String(context.entity_cert_fingerprint));
+                await this._verifyDocument(pending.content, aid, identity, true);
                 const remote = await this._readEntityFresh(aid);
                 if (remote.exists && remote.content === pending.content && remote.etag === pending.content_etag) {
-                    this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+                    const saved = this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+                    if (!saved.aid)
+                        throw new StateError('agent.md pending completion persistence failed');
+                    this._clearConfirmedDraft(aid, pending.content);
                     return true;
                 }
                 if (condition.if_match && (!remote.exists || remote.etag !== condition.if_match) || condition.if_none_match === '*' && remote.exists)
@@ -497,38 +595,31 @@ export class AgentMdManager {
                 await this._uploadPrepared(aid, pending.content, identity, condition);
                 return true;
             }
-            const remote = await this.readOwnershipFresh(aid);
-            const fail = (code, reason, retryable = false) => ownershipFailure(code, reason, retryable);
-            const candidate = parseOwnershipFile(pending.content, 'agent', { expectedSubAid: aid });
-            const relation = pending.relation && Object.keys(pending.relation).length ? pending.relation : undefined;
-            const sameStatement = (first, second) => first == null && second == null || first !== null && second !== null && typeof first === 'object' && typeof second === 'object' && ['version', 'declaration_id', 'owner_aid', 'sub_aid', 'relation_version', 'declared_at'].every((field) => first[field] === second[field]);
-            if (candidate.statement && !relation)
-                throw fail('persistence_unavailable', 'pending ownership body update requires its original relationship context');
-            if (relation) {
-                if (remote.relation_version !== relation.relation_version || remote.lock !== relation.lock)
-                    throw fail('conflict', 'pending agent.md original relationship changed');
-                if (!sameStatement(candidate.statement, relation.statement))
-                    throw fail('unsupported_protocol', 'ownership changes require their persisted 2.1 task');
-                if (remote.exists && (remote.relation_version > 0 || candidate.statement)) {
-                    const current = parseOwnershipFile(remote.content, 'agent', { expectedSubAid: aid });
-                    if (!sameStatement(current.statement, relation.statement) || (remote.owner_aid ?? current.statement?.owner_aid ?? null) !== relation.owner_aid)
-                        throw fail('conflict', 'pending agent.md relationship statement changed');
-                }
+            const multipleSignatures = parseAgentMdTailSignature(pending.content).signatures.length > 1;
+            const identity = signer ?? this._currentAid();
+            if (multipleSignatures) {
+                if (!identity)
+                    throw new StateError('pending agent.md requires a signer identity');
+                await this._verifyDocument(pending.content, aid, identity, true, true);
             }
-            if (!relation && (remote.relation_version !== 0 || remote.lock !== 'unlocked'))
-                throw fail('unavailable', 'pending agent.md cannot overwrite relationship history', true);
+            if (pending.content_etag !== AgentMdManager.contentEtag(pending.content))
+                throw ownershipFailure('persistence_unavailable', 'pending agent.md original bytes are corrupt');
+            if (!identity)
+                throw new StateError('pending agent.md requires a signer identity');
+            if (!multipleSignatures)
+                verifyAgentMdBodyUpdate(pending.content, identity.certPem, aid);
+            const remote = await this.readAgentMdFresh(aid);
             if (remote.exists && remote.etag === pending.content_etag && remote.content === pending.content) {
                 const saved = this.saveRecord(aid, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
                 if (!saved.aid)
                     throw new StateError('agent.md pending completion persistence failed');
+                this._clearConfirmedDraft(aid, pending.content);
                 return true;
             }
             if (condition.if_match && (!remote.exists || remote.etag !== condition.if_match) || condition.if_none_match === '*' && remote.exists)
                 throw ownershipFailure('conflict', 'pending agent.md original document condition changed');
-            const identity = signer ?? this._currentAid();
-            if (!identity)
-                throw new StateError('pending agent.md requires a signer identity');
-            verifyAgentMdUpload(pending.content, identity.certPem, aid);
+            if (remote.exists && legacyRelationship(validateAgentMdReadDocument(remote.content, { expectedAid: aid }).frontmatter))
+                throw ownershipFailure('conflict', 'legacy relationship material cannot be removed or replaced');
             await this._uploadPrepared(aid, pending.content, identity, condition);
             return true;
         }
@@ -538,32 +629,38 @@ export class AgentMdManager {
         }
     }
     async _uploadPrepared(target, signedContent, signer, originalCondition) {
-        const meta = validateAgentMdDocument(signedContent, { expectedAid: target }).frontmatter;
+        const meta = validateAgentMdDocument(signedContent, { expectedAid: target, validateOwnership: false }).frontmatter;
         const entity = ['group', 'org'].includes(String(meta.type));
+        const legacy = legacyRelationship(meta);
+        const draftStrict = !originalCondition || !this._pendingUpload(target, true);
+        if (legacy && (signer.aid !== target || this._currentAid()?.aid !== target || this._ownerAid() !== target))
+            throw ownershipFailure('forbidden', 'legacy relationship body updates require current subject identity');
+        if (draftStrict && this._saveRecord(target, { local_draft_content: signedContent }, true).local_draft_content !== signedContent)
+            throw new StateError('agent.md local draft persistence failed');
         const entityContext = entity ? await this._entityContext(target, meta, signer) : undefined;
         let condition = originalCondition;
-        let relation = entityContext ?? (this.pendingUpload(target))?.relation;
+        let relation = entityContext ?? (this._pendingUpload(target, draftStrict))?.relation;
         if (!condition) {
-            const fresh = entity ? await this._readEntityFresh(target) : await this.readOwnershipFresh(target);
+            const fresh = entity ? await this._readEntityFresh(target) : legacy ? await this._readLegacyBodyBase(target) : await this.readAgentMdFresh(target);
             condition = fresh.exists ? { if_match: fresh.etag } : { if_none_match: '*' };
             if (!entity) {
-                const authority = fresh;
-                const candidate = parseOwnershipFile(signedContent, 'agent', { expectedSubAid: target });
-                const statement = fresh.exists && (authority.relation_version > 0 || candidate.statement) ? parseOwnershipFile(fresh.content, 'agent', { expectedSubAid: target }).statement : undefined;
-                relation = { relation_version: authority.relation_version, lock: authority.lock, owner_aid: authority.owner_aid ?? statement?.owner_aid ?? null, statement: statement ?? null };
+                if (legacy) {
+                    if (!fresh.exists || !fresh.etag || !isDeepStrictEqual(legacy, legacyRelationship(validateAgentMdReadDocument(fresh.content, { expectedAid: target }).frontmatter)))
+                        throw ownershipFailure('conflict', 'legacy relationship material must remain unchanged');
+                    relation = { legacy: true, base_content: fresh.content, base_content_etag: AgentMdManager.contentEtag(fresh.content), base_etag: fresh.etag, fields: legacy };
+                }
+                else {
+                    if (fresh.exists && legacyRelationship(validateAgentMdReadDocument(fresh.content, { expectedAid: target }).frontmatter))
+                        throw ownershipFailure('conflict', 'legacy relationship material cannot be removed or replaced');
+                    relation = undefined;
+                }
             }
         }
         const uploader = this._currentAid();
-        const entityOwnerUpload = entity && uploader.aid.toLowerCase() !== target.toLowerCase();
-        const entityAuthorization = entityOwnerUpload ? originalCondition ? (this.pendingUpload(target))?.authorization : this._ownerUploadAuthorization(target, signedContent, uploader, String(entityContext.entity_cert_fingerprint)) : '';
-        if (entityOwnerUpload) {
-            const timestamp = this._validateEntityUploadAuthorization(entityAuthorization, target, signedContent, uploader, String(entityContext.entity_cert_fingerprint));
-            if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > 300)
-                throw ownershipFailure('conflict', 'pending entity V2 authorization expired; explicit upload is required');
-        }
-        const pending = this.saveRecord(target, { pending_operation: 'replace', pending_target_aid: target, pending_content: signedContent, pending_content_etag: AgentMdManager.contentEtag(signedContent), pending_error: '', pending_condition: condition, pending_relation: relation, pending_authorization: entityAuthorization });
+        const entityAuthorization = '';
+        const pending = this._saveRecord(target, { pending_operation: 'replace', pending_target_aid: target, pending_content: signedContent, pending_content_etag: AgentMdManager.contentEtag(signedContent), pending_error: '', pending_condition: condition, pending_relation: relation, pending_authorization: entityAuthorization }, draftStrict);
         const savedCondition = pending.pending_condition;
-        if (pending.pending_content !== signedContent || savedCondition?.if_match !== condition.if_match || savedCondition?.if_none_match !== condition.if_none_match || pending.pending_authorization !== entityAuthorization)
+        if (pending.pending_content !== signedContent || savedCondition?.if_match !== condition.if_match || savedCondition?.if_none_match !== condition.if_none_match || pending.pending_authorization !== entityAuthorization || legacy && !isDeepStrictEqual(pending.pending_relation, relation))
             throw new StateError('agent.md pending upload persistence failed');
         try {
             const owner = this._currentAid();
@@ -573,24 +670,71 @@ export class AgentMdManager {
             const authorization = entity ? entityAuthorization : delegated ? this._ownerUploadAuthorization(target, signedContent, owner) : '';
             const result = await this._uploadHttp(target, signedContent, authorization, condition);
             const remoteEtag = String(result.etag ?? '').trim();
-            const saved = this.saveRecord(target, {
+            const saved = this._saveRecord(target, {
                 content: signedContent, local_etag: AgentMdManager.contentEtag(signedContent), remote_etag: remoteEtag || undefined,
                 last_modified: String(result.last_modified ?? result.lastModified ?? '').trim(), fetched_at: Date.now(), checked_at: Date.now(),
                 remote_status: remoteEtag ? 'found' : 'unknown', last_error: '',
                 pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '',
-            });
+            }, draftStrict);
             if (!saved.aid)
                 throw new StateError('agent.md upload completion persistence failed');
+            if (remoteEtag === AgentMdManager.contentEtag(signedContent))
+                this._clearConfirmedDraft(target, signedContent);
             return { ...result };
         }
         catch (error) {
-            this.saveRecord(target, { pending_error: error instanceof Error ? error.message : String(error) });
+            this._saveRecord(target, { pending_error: error instanceof Error ? error.message : String(error) }, draftStrict);
             throw error;
         }
     }
+    async _verifyLegacyBodyContent(target, content) {
+        const parsed = validateAgentMdReadDocument(content, { expectedAid: target, requireSignature: true });
+        if (!legacyRelationship(parsed.frontmatter))
+            throw ownershipFailure('unsupported_protocol', 'stored agent.md does not contain a legacy relationship');
+        const peer = await this._resolvePeer(target, parsed.signature.cert_fingerprint, Number(parsed.signature.timestamp));
+        const verified = await this._verifyDocument(content, target, peer);
+        if (verified.status !== 'verified')
+            throw ownershipFailure('invalid', 'stored legacy agent.md signature is invalid');
+        return parsed;
+    }
+    async _readLegacyBodyBase(target) {
+        const response = await this.readAgentMdFresh(target);
+        if (response.exists)
+            await this._verifyLegacyBodyContent(target, response.content);
+        return response;
+    }
+    async _resumeLegacyBodyUpload(target, pending, identity) {
+        const relation = pending.relation;
+        if (!identity || identity.aid !== target || this._currentAid()?.aid !== target || this._ownerAid() !== target)
+            throw ownershipFailure('forbidden', 'legacy relationship recovery requires current subject identity');
+        if (typeof relation.base_content !== 'string' || relation.base_content_etag !== AgentMdManager.contentEtag(relation.base_content) || typeof relation.base_etag !== 'string' || !relation.base_etag || pending.condition?.if_match !== relation.base_etag || pending.content_etag !== AgentMdManager.contentEtag(pending.content))
+            throw ownershipFailure('persistence_unavailable', 'pending legacy relationship original bytes or condition are missing');
+        if (parseAgentMdTailSignature(pending.content).signatures.length > 1)
+            await this._verifyDocument(pending.content, target, identity, true, true);
+        else
+            verifyAgentMdBodyUpdate(pending.content, identity.certPem, target);
+        const base = await this._verifyLegacyBodyContent(target, relation.base_content);
+        const candidate = validateAgentMdDocument(pending.content, { expectedAid: target, validateOwnership: false });
+        if (!isDeepStrictEqual(legacyRelationship(base.frontmatter), relation.fields) || !isDeepStrictEqual(relationshipFields(candidate.frontmatter), relation.fields))
+            throw ownershipFailure('persistence_unavailable', 'pending legacy relationship material changed');
+        const remote = await this._readLegacyBodyBase(target);
+        if (!remote.exists)
+            throw ownershipFailure('conflict', 'pending legacy agent.md original document is missing');
+        if (remote.content === pending.content && remote.etag === pending.content_etag) {
+            const saved = this.saveRecord(target, { content: pending.content, remote_etag: remote.etag, pending_operation: '', pending_content: '', pending_content_etag: '', pending_error: '', pending_condition: {}, pending_relation: {}, pending_authorization: '' });
+            if (!saved.aid)
+                throw new StateError('agent.md pending completion persistence failed');
+            this._clearConfirmedDraft(target, pending.content);
+            return true;
+        }
+        if (remote.content !== relation.base_content || remote.etag !== relation.base_etag)
+            throw ownershipFailure('conflict', 'pending legacy agent.md original document changed');
+        await this._uploadPrepared(target, pending.content, identity, pending.condition);
+        return true;
+    }
     async _readEntityFresh(target) {
         const gateway = await this._resolveGateway(target);
-        const headers = { 'Cache-Control': 'no-cache', ...(this._uploadViaGatewayHost ? { Host: target } : {}) };
+        const headers = { 'X-AUN-Ownership-Check': '1', 'X-AUN-Signature-Format': 'multi-v1', 'Cache-Control': 'no-cache', ...(this._uploadViaGatewayHost ? { Host: target } : {}) };
         const request = (url) => requestText(url, { method: 'GET', verifySsl: this._verifySsl, headers, timeoutMs: DEFAULT_HTTP_TIMEOUT_MS, redirectsLeft: 0, strictUtf8: true });
         const response = await request(this._url(target, gateway, this._uploadViaGatewayHost));
         if (response.status !== 200 && response.status !== 404)
@@ -604,19 +748,23 @@ export class AgentMdManager {
     }
     async readEntityAuthorityFresh(target) {
         const observed = await this._readEntityFresh(this.safeAid(target));
-        if (!observed.owner_aid || !/^sha256:[0-9a-f]{64}$/.test(observed.entity_cert_fingerprint))
+        try {
+            ownershipAid(observed.owner_aid, 'owner_aid');
+        }
+        catch {
+            throw ownershipFailure('unavailable', 'entity owner authority metadata is unavailable', true);
+        }
+        if (!/^sha256:[0-9a-f]{64}$/.test(observed.entity_cert_fingerprint))
             throw ownershipFailure('unavailable', 'entity owner authority metadata is unavailable', true);
         return { owner_aid: observed.owner_aid, entity_cert_fingerprint: observed.entity_cert_fingerprint };
     }
     async _entityContext(target, meta, signer) {
         const owner = String(meta.owner ?? '').trim().toLowerCase();
         const uploader = this._currentAid();
-        if (![owner, target.toLowerCase()].includes(signer.aid.toLowerCase()) || !uploader || ![owner, target.toLowerCase()].includes(uploader.aid.toLowerCase()) || uploader.aid.toLowerCase() !== this._ownerAid().toLowerCase())
-            throw ownershipFailure('forbidden', 'group/org agent.md requires entity or current owner identity');
+        if (signer.aid.toLowerCase() !== target.toLowerCase() || !uploader || uploader.aid.toLowerCase() !== owner || uploader.aid.toLowerCase() !== this._ownerAid().toLowerCase())
+            throw ownershipFailure('forbidden', 'group/org agent.md requires current owner identity');
         const context = await this._entityCurrentContext(target, meta, true);
-        if (signer.aid.toLowerCase() === owner)
-            await this._verifyEntityOwnerSigner(signer);
-        else if (signer.certFingerprint !== context.entity_cert_fingerprint)
+        if (signer.certFingerprint !== context.entity_cert_fingerprint)
             throw ownershipFailure('conflict', 'entity signing certificate changed');
         if (uploader.aid.toLowerCase() === target.toLowerCase()) {
             if (uploader.certFingerprint !== context.entity_cert_fingerprint)
@@ -636,6 +784,25 @@ export class AgentMdManager {
             throw ownershipFailure('unavailable', 'entity owner signing certificate resolver is unavailable', true);
         return await this._entitySignerResolver(signer, signature.cert_fingerprint);
     }
+    async _verifyDocument(content, target, identity, current = false, bodyUpdate = false) {
+        const certificates = new Map();
+        const parsed = parseAgentMdTailSignature(content, !current);
+        const meta = validateAgentMdReadDocument(content, { expectedAid: target }).frontmatter;
+        const historicalEntityOwner = !current && ['group', 'org'].includes(String(meta.type)) && parsed.signatures.length === 1 && parsed.fields?.signer_aid !== undefined && parsed.fields.signer_aid === meta.owner && parsed.fields.signer_aid !== meta.aid;
+        const readCompatibility = !current && (!['group', 'org'].includes(String(meta.type)) || meta.type === 'group' && !Object.hasOwn(meta, 'entity_cert_fingerprint') && parsed.signatures.length === 1 && (parsed.fields?.signer_aid === undefined || parsed.fields.signer_aid === meta.aid));
+        for (const item of parsed.signatures.slice(1)) {
+            const fields = item.fields;
+            const peer = current && this._entitySignerResolver ? await this._entitySignerResolver(fields.signer_aid, fields.cert_fingerprint) : await this._resolvePeer(fields.signer_aid, fields.cert_fingerprint, Number(fields.timestamp));
+            certificates.set(`${fields.signer_aid};${fields.cert_fingerprint}`, peer.certPem);
+        }
+        const resolver = (aid, fingerprint) => certificates.get(`${aid};${fingerprint}`);
+        if (current)
+            (bodyUpdate ? verifyAgentMdBodyUpdate : verifyAgentMdUpload)(content, identity.certPem, target, undefined, resolver);
+        const result = verifyDocument(content, { expectedAid: historicalEntityOwner ? String(meta.owner) : target, primaryCertPem: identity.certPem, requireCurrentValidity: current, readCompatibility, certificateResolver: resolver });
+        if (result.status === 'invalid')
+            throw ownershipFailure('invalid', result.reason ?? 'document signature verification failed');
+        return result;
+    }
     async _verifyEntityOwnerSigner(owner) {
         if (!this._entitySignerResolver)
             throw ownershipFailure('unavailable', 'entity owner signing certificate resolver is unavailable', true);
@@ -663,52 +830,21 @@ export class AgentMdManager {
             throw ownershipFailure('conflict', 'entity agent.md certificate generation changed');
         return { type: meta.type, owner_aid: owner, entity_cert_fingerprint: entity.certFingerprint };
     }
-    _validateEntityUploadAuthorization(authorization, target, content, owner, entityFingerprint) {
-        const invalid = ownershipFailure('persistence_unavailable', 'pending entity original V2 authorization is missing or invalid');
-        try {
-            if (typeof authorization !== 'string' || !/^[A-Za-z0-9_-]+={0,2}$/.test(authorization) || authorization.includes('=') && authorization.length % 4 !== 0)
-                throw invalid;
-            const raw = Buffer.from(authorization, 'base64url');
-            if (raw.toString('base64url') !== authorization.replace(/=+$/, ''))
-                throw invalid;
-            const text = new TextDecoder('utf-8', { fatal: true }).decode(raw);
-            const value = JSON.parse(text);
-            const lexical = parseDocument(text, { uniqueKeys: true });
-            if (lexical.errors.length || lexical.get('version', true)?.source !== '2' || !/^[1-9][0-9]*$/.test(lexical.get('timestamp', true)?.source ?? ''))
-                throw invalid;
-            const fields = ['version', 'target_aid', 'uploader_aid', 'body_sha256', 'entity_cert_fingerprint', 'timestamp', 'nonce', 'cert_fingerprint', 'signature'];
-            if (!isJsonObject(value) || Object.keys(value).length !== fields.length || fields.some(field => !(field in value)) || value.version !== 2)
-                throw invalid;
-            const timestamp = value.timestamp, nonce = value.nonce;
-            if (typeof timestamp !== 'number' || !Number.isSafeInteger(timestamp) || timestamp <= 0 || typeof nonce !== 'string' || !nonce.trim() || Buffer.byteLength(nonce, 'utf8') > 128)
-                throw invalid;
-            if (value.target_aid !== target.toLowerCase() || value.uploader_aid !== owner.aid.toLowerCase() || value.body_sha256 !== crypto.createHash('sha256').update(content, 'utf-8').digest('hex') || value.entity_cert_fingerprint !== entityFingerprint || value.cert_fingerprint !== owner.certFingerprint || typeof value.signature !== 'string')
-                throw invalid;
-            const verified = owner.verify(`AUN-AGENTMD-OWNER-AUTH-V2;${value.uploader_aid};${value.target_aid};${value.body_sha256};${entityFingerprint};${timestamp};${nonce}`, value.signature);
-            if (!verified.ok || !verified.data?.valid)
-                throw invalid;
-            return timestamp;
-        }
-        catch {
-            throw invalid;
-        }
-    }
-    _ownerUploadAuthorization(target, signedContent, owner, entityFingerprint = '') {
+    _ownerUploadAuthorization(target, signedContent, owner) {
         const bodySha256 = crypto.createHash('sha256').update(signedContent, 'utf-8').digest('hex');
         const timestamp = Math.floor(Date.now() / 1000);
         const nonce = crypto.randomBytes(16).toString('hex');
-        const canonical = entityFingerprint ? `AUN-AGENTMD-OWNER-AUTH-V2;${owner.aid.toLowerCase()};${target.toLowerCase()};${bodySha256};${entityFingerprint};${timestamp};${nonce}` : `AUN-AGENT-MD-UPLOAD-V1;${owner.aid.toLowerCase()};${target.toLowerCase()};${bodySha256};${timestamp};${nonce}`;
+        const canonical = `AUN-AGENT-MD-UPLOAD-V1;${owner.aid.toLowerCase()};${target.toLowerCase()};${bodySha256};${timestamp};${nonce}`;
         const signed = owner.sign(canonical);
         if (!signed.ok || !signed.data) {
             const message = signed.error?.message ?? 'owner authorization signing failed';
             throw new ClientSignatureError(message);
         }
         const payload = {
-            version: entityFingerprint ? 2 : 1,
+            version: 1,
             target_aid: target.toLowerCase(),
             uploader_aid: owner.aid.toLowerCase(),
             body_sha256: bodySha256,
-            ...(entityFingerprint ? { entity_cert_fingerprint: entityFingerprint } : {}),
             timestamp,
             nonce,
             cert_fingerprint: owner.certFingerprint,
@@ -721,13 +857,14 @@ export class AgentMdManager {
             throw ownershipFailure('persistence_unavailable', 'agent.md upload requires its original document condition');
         const gatewayUrl = await this._resolveGateway(target);
         const authorization = String(ownerAuthorization ?? '').trim();
-        const entity = ['group', 'org'].includes(String(validateAgentMdDocument(signedContent, { expectedAid: target }).frontmatter.type));
+        const meta = validateAgentMdDocument(signedContent, { expectedAid: target, validateOwnership: false }).frontmatter;
+        const entity = ['group', 'org'].includes(String(meta.type));
         const uploadHeaders = {
+            'X-AUN-Signature-Format': 'multi-v1',
             'Content-Type': 'text/markdown; charset=utf-8',
-            ...(!entity ? { 'X-AUN-Ownership-Check': '1' } : {}),
             ...(condition.if_match ? { 'If-Match': condition.if_match } : { 'If-None-Match': '*' }),
             ...(this._uploadViaGatewayHost ? { Host: target } : {}),
-            ...(authorization ? { [entity ? 'AUN-AGENTMD-OWNER-AUTHORIZATION' : 'X-AUN-AgentMD-Owner-Authorization']: authorization } : {}),
+            ...(authorization && !entity ? { 'X-AUN-AgentMD-Owner-Authorization': authorization } : {}),
         };
         if (!authorization || entity) {
             const token = await this._uploadAccessToken(entity ? this._ownerAid() : target, gatewayUrl);
@@ -985,14 +1122,14 @@ export class AgentMdManager {
         return String(await this._gatewayResolver?.(aid) ?? '');
     }
     async _resolvePeer(aid, certFingerprint, signedAt) {
-        const expectedFp = String(certFingerprint ?? '').trim().toLowerCase();
+        const expectedFp = certFingerprint ? `sha256:${normalizeFingerprintHex(certFingerprint)}` : '';
         const current = this._currentAid();
-        if (current && current.aid.toLowerCase() === aid.toLowerCase()) {
-            if (!expectedFp || certMatchesFingerprint(current.certPem, expectedFp))
+        if (signedAt === undefined && current && current.aid.toLowerCase() === aid.toLowerCase()) {
+            if (!expectedFp || certMatchesFingerprint(current.certPem, expectedFp) || publicKeyMatchesFingerprint(current.certPem, expectedFp))
                 return current;
         }
         const peer = await this._peerResolver?.(aid, expectedFp || null, signedAt);
-        if (!(peer instanceof AID)) {
+        if (!(peer instanceof AID) || peer.aid.toLowerCase() !== aid.toLowerCase()) {
             throw new StateError(`agent.md peer resolver did not return AID for ${aid}`);
         }
         return peer;
@@ -1016,7 +1153,7 @@ export class AgentMdManager {
         const response = await requestText(this._url(target, gatewayUrl), {
             method: 'HEAD',
             verifySsl: this._verifySsl,
-            headers: { Accept: 'text/markdown' },
+            headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown' },
             timeoutMs: HEAD_HTTP_TIMEOUT_MS,
         });
         if (response.status === 404) {
@@ -1054,7 +1191,7 @@ export class AgentMdManager {
         this._log.debug(`downloadAgentMd enter: aid=${target}`);
         const gatewayUrl = await this._resolveGateway(target);
         const cached = this.loadRecord(target) ?? {};
-        const headers = { Accept: 'text/markdown' };
+        const headers = { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown' };
         const etag = String(cached.remote_etag ?? cached.etag ?? cached.local_etag ?? '').trim();
         const lastModified = String(cached.last_modified ?? '').trim();
         let response = await requestText(this._url(target, gatewayUrl), {
@@ -1062,6 +1199,7 @@ export class AgentMdManager {
             verifySsl: this._verifySsl,
             headers,
             timeoutMs,
+            redirectsLeft: 0,
             strictUtf8: true,
         });
         let reusedCachedNotModified = false;
@@ -1081,8 +1219,9 @@ export class AgentMdManager {
             response = await requestText(this._url(target, gatewayUrl), {
                 method: 'GET',
                 verifySsl: this._verifySsl,
-                headers: { Accept: 'text/markdown' },
+                headers: { 'X-AUN-Signature-Format': 'multi-v1', Accept: 'text/markdown' },
                 timeoutMs,
+                redirectsLeft: 0,
                 strictUtf8: true,
             });
         }
@@ -1095,29 +1234,24 @@ export class AgentMdManager {
             throw new AUNError(`download agent.md failed: HTTP ${response.status}${message ? ` - ${message}` : ''}`);
         }
         const content = response.text;
-        if (headerValue(response.headers, 'X-AUN-Entity-Verification-Status') === 'stale')
-            throw ownershipFailure('conflict', 'entity agent.md is not from the current lifecycle generation');
-        const parsed = parseAgentMdTailSignature(content);
+        const parsed = parseAgentMdTailSignature(content, true);
         let entity = false;
         let frontmatter = {};
         try {
-            frontmatter = parseFileFrontmatter(parsed.payload);
+            frontmatter = validateAgentMdReadDocument(content).frontmatter;
             entity = ['group', 'org'].includes(String(frontmatter.type));
         }
         catch { }
-        if (entity) {
-            try {
-                frontmatter = validateAgentMdDocument(content, { expectedAid: target, validateOwnership: false, requireSignature: true }).frontmatter;
-            }
-            catch (error) {
-                throw ownershipFailure('invalid', error instanceof Error ? error.message : String(error));
-            }
+        try {
+            frontmatter = validateAgentMdReadDocument(content, { expectedAid: target, requireSignature: entity }).frontmatter;
+        }
+        catch (error) {
+            throw ownershipFailure('invalid', error instanceof Error ? error.message : String(error));
         }
-        if (entity)
-            await this._entityCurrentContext(target, frontmatter);
         const expectedFp = parsed.fields?.cert_fingerprint || parsed.fields?.public_key_fingerprint || null;
-        const peer = entity ? await this._entitySigningIdentity(target, frontmatter, parsed.fields) : await this._resolvePeer(target, expectedFp, parsed.fields?.timestamp ? Number(parsed.fields.timestamp) : undefined);
-        const verified = peer.verifyAgentMd(content);
+        const peer = await this._resolvePeer(entity ? parsed.fields.signer_aid ?? target : target, expectedFp, parsed.fields?.timestamp ? Number(parsed.fields.timestamp) : undefined);
+        const generic = await this._verifyDocument(content, target, peer);
+        const verified = resultOk({ ...generic, aid: target, cert_fingerprint: parsed.fields?.cert_fingerprint, timestamp: Number(parsed.fields?.timestamp) });
         if (!verified.ok || !verified.data) {
             const message = verified.error?.message ?? 'agent.md verification failed';
             throw new AUNError(message);
@@ -1128,8 +1262,6 @@ export class AgentMdManager {
         if (statusText === 'invalid') {
             throw new ClientSignatureError(`agent.md verification failed for ${target}${reason ? `: ${reason}` : ''}`, entity ? { stringCode: 'invalid' } : {});
         }
-        if (!entity)
-            frontmatter = validateAgentMdDocument(content, { expectedAid: target, validateOwnership: false }).frontmatter;
         let ownershipStatus;
         if (entity)
             ownershipStatus = 'not_applicable';
@@ -1180,6 +1312,7 @@ export class AgentMdManager {
         return {
             aid: target,
             content,
+            frontmatter,
             verification,
             signature,
             cert_pem: peer.certPem,
@@ -1328,14 +1461,17 @@ export class AgentMdManager {
         payload.aid = this.safeAid(aid);
         this._atomicWriteText(this.metaPath(aid), `${JSON.stringify(payload, null, 2)}\n`);
     }
-    _readRecordUnlocked(aid) {
+    _readRecordUnlocked(aid, strict = false) {
         const filePath = this.metaPath(aid);
         if (!fs.existsSync(filePath))
             return {};
         try {
             const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-            if (!isJsonObject(parsed))
+            if (!isJsonObject(parsed)) {
+                if (strict)
+                    throw ownershipFailure('persistence_unavailable', `agent.md metadata is not a mapping: aid=${aid}`);
                 return {};
+            }
             const record = {};
             for (const [key, value] of Object.entries(parsed)) {
                 if (key !== 'content')
@@ -1348,6 +1484,11 @@ export class AgentMdManager {
             return record;
         }
         catch (err) {
+            if (strict) {
+                if (err instanceof AUNError && err.stringCode === 'persistence_unavailable')
+                    throw err;
+                throw ownershipFailure('persistence_unavailable', `agent.md metadata is damaged: aid=${aid}`);
+            }
             this._log.warn(`agent.md metadata damaged, ignoring: aid=${aid} err=${err instanceof Error ? err.message : String(err)}`);
             return {};
         }