@hivemagnus/ardent 0.0.0-stage → 1.0.2

package/dist/team-artifacts.d.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import type { ArdentRuntime } from './runtime.js';
+import type { ArdentConfig } from './config.js';
+declare const Manifest: z.ZodObject<{
+    schema_version: z.ZodLiteral<"1.0">;
+    revision: z.ZodNumber;
+    source_revision: z.ZodString;
+    visibility: z.ZodEnum<{
+        private: "private";
+        gm: "gm";
+        player: "player";
+    }>;
+    license: z.ZodString;
+    preview: z.ZodObject<{
+        mode: z.ZodEnum<{
+            none: "none";
+            inline: "inline";
+            thumbnail: "thumbnail";
+            download_only: "download_only";
+        }>;
+        mime: z.ZodString;
+    }, z.core.$strict>;
+    supersedes_sha256: z.ZodNullable<z.ZodString>;
+    acceptance_status: z.ZodEnum<{
+        rejected: "rejected";
+        partial: "partial";
+        unreviewed: "unreviewed";
+        approved: "approved";
+    }>;
+    name: z.ZodString;
+    mime: z.ZodString;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+    created_at: z.ZodNumber;
+    expires_at: z.ZodNumber;
+    provenance: z.ZodObject<{
+        producer: z.ZodString;
+        source_id: z.ZodString;
+        producer_task_id: z.ZodString;
+        lineage: z.ZodArray<z.ZodObject<{
+            producer: z.ZodString;
+            source_id: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    recovery: z.ZodObject<{
+        on_expiry: z.ZodLiteral<"request_verified_reexport">;
+    }, z.core.$strict>;
+    artifact_id: z.ZodString;
+}, z.core.$strict>;
+export type TeamArtifactManifest = z.infer<typeof Manifest>;
+export declare const TeamArtifactDescriptorSchema: z.ZodObject<{
+    artifact_id: z.ZodString;
+    name: z.ZodString;
+    mime: z.ZodString;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+    producer_task_id: z.ZodString;
+    artifact_manifest: z.ZodObject<{
+        schema_version: z.ZodLiteral<"1.0">;
+        revision: z.ZodNumber;
+        source_revision: z.ZodString;
+        visibility: z.ZodEnum<{
+            private: "private";
+            gm: "gm";
+            player: "player";
+        }>;
+        license: z.ZodString;
+        preview: z.ZodObject<{
+            mode: z.ZodEnum<{
+                none: "none";
+                inline: "inline";
+                thumbnail: "thumbnail";
+                download_only: "download_only";
+            }>;
+            mime: z.ZodString;
+        }, z.core.$strict>;
+        supersedes_sha256: z.ZodNullable<z.ZodString>;
+        acceptance_status: z.ZodEnum<{
+            rejected: "rejected";
+            partial: "partial";
+            unreviewed: "unreviewed";
+            approved: "approved";
+        }>;
+        name: z.ZodString;
+        mime: z.ZodString;
+        sha256: z.ZodString;
+        size: z.ZodNumber;
+        created_at: z.ZodNumber;
+        expires_at: z.ZodNumber;
+        provenance: z.ZodObject<{
+            producer: z.ZodString;
+            source_id: z.ZodString;
+            producer_task_id: z.ZodString;
+            lineage: z.ZodArray<z.ZodObject<{
+                producer: z.ZodString;
+                source_id: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        recovery: z.ZodObject<{
+            on_expiry: z.ZodLiteral<"request_verified_reexport">;
+        }, z.core.$strict>;
+        artifact_id: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TeamArtifactDescriptor = z.infer<typeof TeamArtifactDescriptorSchema>;
+/** Peer artifact receipts. A transfer is retained evidence, never a delivery claim. */
+export declare class TeamArtifacts {
+    readonly runtime: ArdentRuntime;
+    readonly config: ArdentConfig;
+    readonly env: NodeJS.ProcessEnv;
+    constructor(runtime: ArdentRuntime, config?: ArdentConfig, env?: NodeJS.ProcessEnv);
+    registerResearch(a2aTaskId: string): Promise<TeamArtifactDescriptor[]>;
+    serve(peer: string, id: string, contextId: string): Promise<{
+        status: number;
+        bytes?: Uint8Array;
+        descriptor?: TeamArtifactDescriptor;
+    }>;
+    revokeLocal(peer: string, a2aTaskId: string, id: string): void;
+    fetchHermes(input: {
+        owner: string;
+        localTaskId: string;
+        peer: string;
+        remoteTaskId: string;
+        remoteContextId: string;
+        artifactId: string;
+        sha256: string;
+    }): Promise<TeamArtifactDescriptor & {
+        local_artifact_id: string;
+    }>;
+    project(owner: string, localTaskId: string): Array<{
+        local_artifact_id: string;
+        peer: string;
+        remote_task_id: string;
+        artifact_manifest: TeamArtifactManifest;
+        delivery: 'unverified';
+    }>;
+}
+export {};

package/dist/team-artifacts.js

@@ -0,0 +1,241 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+import { TaskState } from '@a2a-js/sdk';
+import { ArdentA2AClient } from './a2a-client.js';
+import { TeamEnvelope } from './team-contract.js';
+const digest = z.string().regex(/^[a-f0-9]{64}$/);
+const identifier = z.string().regex(/^[a-f0-9]{32}$/);
+const safeName = z.string().regex(/^[A-Za-z0-9._-]{1,128}$/);
+const Manifest = z.object({
+    schema_version: z.literal('1.0'), revision: z.number().int().min(1), source_revision: z.string().min(1),
+    visibility: z.enum(['private', 'gm', 'player']), license: z.string().min(1),
+    preview: z.object({ mode: z.enum(['inline', 'thumbnail', 'download_only', 'none']), mime: z.string().min(1) }).strict(),
+    supersedes_sha256: digest.nullable(), acceptance_status: z.enum(['unreviewed', 'approved', 'partial', 'rejected']),
+    name: safeName, mime: z.string().min(1), sha256: digest, size: z.number().int().min(0).max(2 * 1024 * 1024),
+    created_at: z.number().finite(), expires_at: z.number().finite(),
+    provenance: z.object({ producer: z.string().min(1), source_id: z.string(), producer_task_id: z.string().min(1),
+        lineage: z.array(z.object({ producer: z.string().min(1), source_id: z.string() }).strict()).min(1).max(4) }).strict(),
+    recovery: z.object({ on_expiry: z.literal('request_verified_reexport') }).strict(), artifact_id: identifier
+}).strict();
+export const TeamArtifactDescriptorSchema = z.object({ artifact_id: identifier, name: safeName, mime: z.string().min(1), sha256: digest,
+    size: z.number().int().min(0).max(2 * 1024 * 1024), producer_task_id: z.string().min(1), artifact_manifest: Manifest }).strict();
+const LocalRow = z.object({ id: identifier, peer: z.string(), context_id: z.string(), a2a_task_id: z.string(),
+    digest, name: safeName, mime: z.string(), size: z.number(), manifest_json: z.string(), status: z.string(), expires: z.number() });
+const TransferRow = z.object({ id: digest, owner: z.string(), local_task_id: z.string(), peer: z.string(),
+    remote_task_id: z.string(), remote_context_id: z.string(), remote_artifact_id: identifier,
+    digest, manifest_json: z.string(), status: z.string() });
+const MAX_BYTES = 2 * 1024 * 1024;
+const TTL_SECONDS = 7 * 24 * 3600;
+function sha(bytes) { return createHash('sha256').update(bytes).digest('hex'); }
+function textParts(task) {
+    return task.artifacts.flatMap(artifact => artifact.parts.flatMap(part => part.content?.$case === 'text' && typeof part.content.value === 'string' ? [part.content.value] : []));
+}
+/** Peer artifact receipts. A transfer is retained evidence, never a delivery claim. */
+export class TeamArtifacts {
+    runtime;
+    config;
+    env;
+    constructor(runtime, config = runtime.config, env = process.env) {
+        this.runtime = runtime;
+        this.config = config;
+        this.env = env;
+        runtime.store.db.exec(`CREATE TABLE IF NOT EXISTS a2a_team_artifacts (
+      id TEXT PRIMARY KEY, peer TEXT NOT NULL, context_id TEXT NOT NULL, a2a_task_id TEXT NOT NULL,
+      digest TEXT NOT NULL, name TEXT NOT NULL, mime TEXT NOT NULL, size INTEGER NOT NULL,
+      manifest_json TEXT NOT NULL, status TEXT NOT NULL, expires REAL NOT NULL);
+      CREATE TABLE IF NOT EXISTS a2a_team_artifact_transfers (
+      id TEXT PRIMARY KEY, owner TEXT NOT NULL, local_task_id TEXT NOT NULL, peer TEXT NOT NULL,
+      remote_task_id TEXT NOT NULL, remote_context_id TEXT NOT NULL, remote_artifact_id TEXT NOT NULL,
+      digest TEXT NOT NULL, manifest_json TEXT NOT NULL, status TEXT NOT NULL);`);
+    }
+    async registerResearch(a2aTaskId) {
+        const db = this.runtime.store.db;
+        const row = db.prepare(`SELECT t.caller,t.context_id,o.tenant,o.operation_id,m.envelope_json FROM a2a_tasks t
+      JOIN a2a_operation_map o ON o.a2a_task_id=t.id JOIN a2a_team_missions m ON m.a2a_task_id=t.id
+      WHERE t.id=? AND t.caller=o.caller AND t.caller=m.caller`)
+            .get(a2aTaskId);
+        const bound = z.object({ caller: z.string(), context_id: z.string(), tenant: z.string(),
+            operation_id: z.string(), envelope_json: z.string() }).parse(row);
+        const operation = this.runtime.store.get(bound.operation_id);
+        if (operation?.state !== 'completed' || operation.context !== 'peer' ||
+            operation.caller !== `a2a:${bound.tenant}:${bound.caller}`)
+            return [];
+        const envelope = TeamEnvelope.parse(JSON.parse(bound.envelope_json));
+        if (!envelope.mission.allowed_actions.includes('create_artifact'))
+            return [];
+        const events = this.runtime.store.events(bound.operation_id, 0, 500);
+        const event = events.find(item => item.kind === 'research_artifacts');
+        const actual = z.object({ report: z.object({ id: digest }), markdown: z.object({ id: digest }) }).safeParse(event?.detail);
+        const entries = actual.success ? [
+            { name: 'research-brief.json', mime: 'application/json', digest: actual.data.report.id, producer: 'ardent-research', sourceId: '' },
+            { name: 'research-brief.md', mime: 'text/markdown', digest: actual.data.markdown.id, producer: 'ardent-research', sourceId: '' }
+        ] : [];
+        const result = [];
+        for (const entry of entries) {
+            const bytes = await this.runtime.artifacts.get(entry.digest);
+            const size = bytes.byteLength;
+            if (size > MAX_BYTES)
+                throw new Error('Team artifact exceeds the byte limit');
+            const previous = db.prepare(`SELECT * FROM a2a_team_artifacts WHERE a2a_task_id=? AND digest=? AND name=? AND status='available' AND expires>?`)
+                .get(a2aTaskId, entry.digest, entry.name, Date.now() / 1000);
+            if (previous) {
+                const old = LocalRow.parse(previous);
+                result.push({ artifact_id: old.id, name: old.name, mime: old.mime, sha256: old.digest, size: old.size,
+                    producer_task_id: a2aTaskId, artifact_manifest: Manifest.parse(JSON.parse(old.manifest_json)) });
+                continue;
+            }
+            const id = randomBytes(16).toString('hex');
+            const created = Date.now() / 1000;
+            const manifest = {
+                schema_version: '1.0', revision: 1, source_revision: entry.digest,
+                visibility: 'private', license: 'NOASSERTION', preview: { mode: 'download_only', mime: entry.mime },
+                supersedes_sha256: null, acceptance_status: 'unreviewed', name: entry.name, mime: entry.mime,
+                sha256: entry.digest, size, created_at: created, expires_at: created + TTL_SECONDS,
+                provenance: { producer: entry.producer, source_id: entry.sourceId, producer_task_id: a2aTaskId,
+                    lineage: [{ producer: entry.producer, source_id: entry.sourceId }] },
+                recovery: { on_expiry: 'request_verified_reexport' }, artifact_id: id
+            };
+            db.prepare(`INSERT INTO a2a_team_artifacts(id,peer,context_id,a2a_task_id,digest,name,mime,size,manifest_json,status,expires)
+        VALUES (?,?,?,?,?,?,?,?,?,'available',?)`).run(id, bound.caller, bound.context_id, a2aTaskId, entry.digest, entry.name, entry.mime, size, JSON.stringify(manifest), manifest.expires_at);
+            result.push({ artifact_id: id, name: entry.name, mime: entry.mime, sha256: entry.digest, size,
+                producer_task_id: a2aTaskId, artifact_manifest: manifest });
+        }
+        return result;
+    }
+    async serve(peer, id, contextId) {
+        if (!identifier.safeParse(id).success || !contextId || contextId.length > 128)
+            return { status: 404 };
+        const raw = this.runtime.store.db.prepare('SELECT * FROM a2a_team_artifacts WHERE id=? AND peer=? AND context_id=?').get(id, peer, contextId);
+        if (!raw)
+            return { status: 404 };
+        const row = LocalRow.parse(raw);
+        if (row.status !== 'available' || row.expires <= Date.now() / 1000)
+            return { status: 410 };
+        try {
+            const bytes = await this.runtime.artifacts.get(row.digest);
+            if (bytes.byteLength !== row.size)
+                return { status: 409 };
+            const manifest = Manifest.parse(JSON.parse(row.manifest_json));
+            if (manifest.artifact_id !== id || manifest.sha256 !== row.digest || manifest.expires_at !== row.expires ||
+                manifest.name !== row.name || manifest.mime !== row.mime || manifest.size !== row.size ||
+                manifest.provenance.producer_task_id !== row.a2a_task_id)
+                return { status: 410 };
+            return { status: 200, bytes, descriptor: { artifact_id: id, name: row.name, mime: row.mime,
+                    sha256: row.digest, size: row.size, producer_task_id: row.a2a_task_id, artifact_manifest: manifest } };
+        }
+        catch {
+            return { status: 409 };
+        }
+    }
+    revokeLocal(peer, a2aTaskId, id) {
+        const changed = this.runtime.store.db.prepare(`UPDATE a2a_team_artifacts SET status='revoked'
+      WHERE id=? AND peer=? AND a2a_task_id=? AND status='available'`).run(id, peer, a2aTaskId).changes;
+        if (changed !== 1)
+            throw new Error('Owned artifact export is unavailable');
+    }
+    async fetchHermes(input) {
+        const owned = this.runtime.store.get(input.localTaskId);
+        if (!owned || owned.caller !== input.owner || !['direct', 'peer'].includes(owned.context))
+            throw new Error('Local recipient task is not owned');
+        const id = identifier.parse(input.artifactId);
+        const expected = digest.parse(input.sha256);
+        if (!input.remoteTaskId || !input.remoteContextId)
+            throw new Error('Remote task receipt is incomplete');
+        const transferId = sha(Buffer.from(JSON.stringify([input.owner, input.localTaskId, input.peer,
+            input.remoteTaskId, input.remoteContextId, id, expected])));
+        const priorRaw = this.runtime.store.db.prepare('SELECT * FROM a2a_team_artifact_transfers WHERE id=?').get(transferId);
+        if (priorRaw) {
+            const prior = TransferRow.parse(priorRaw);
+            if (prior.status !== 'complete')
+                throw new Error('Artifact transfer requires reconciliation');
+            await this.runtime.artifacts.get(prior.digest);
+            const manifest = Manifest.parse(JSON.parse(prior.manifest_json));
+            return { artifact_id: id, name: manifest.name, mime: manifest.mime, sha256: expected, size: manifest.size,
+                producer_task_id: input.remoteTaskId, artifact_manifest: manifest, local_artifact_id: prior.digest };
+        }
+        const { card, client, authorization } = await new ArdentA2AClient(this.runtime.profileDir, this.config, this.env).open(input.peer);
+        const remote = await client.getTask({ tenant: '', id: input.remoteTaskId }, { serviceParameters: { Authorization: authorization, 'A2A-Version': '1.0' } });
+        if (remote.id !== input.remoteTaskId || remote.contextId !== input.remoteContextId ||
+            remote.status?.state !== TaskState.TASK_STATE_COMPLETED)
+            throw new Error('Remote task receipt is not complete or bound');
+        const descriptors = textParts(remote).flatMap(value => {
+            try {
+                return [TeamArtifactDescriptorSchema.parse(JSON.parse(value))];
+            }
+            catch {
+                return [];
+            }
+        });
+        const declared = descriptors.find(item => item.artifact_id === id && item.sha256 === expected &&
+            item.producer_task_id === input.remoteTaskId);
+        if (!declared)
+            throw new Error('Remote task did not declare this exact artifact');
+        const interfaceUrl = card.supportedInterfaces.find(item => item.protocolBinding.toUpperCase() === 'JSONRPC' &&
+            item.protocolVersion === '1.0')?.url;
+        if (!interfaceUrl)
+            throw new Error('Remote peer has no pinned JSON-RPC origin');
+        const url = new URL(`/team/artifacts/${id}`, interfaceUrl);
+        url.searchParams.set('context', input.remoteContextId);
+        const response = await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(30_000),
+            headers: { Authorization: authorization } });
+        if (!response.ok)
+            throw new Error(`Artifact fetch HTTP ${response.status}`);
+        const lengthHeader = response.headers.get('content-length');
+        const length = lengthHeader === null ? NaN : Number(lengthHeader);
+        if (!Number.isInteger(length) || length < 0 || length > MAX_BYTES || length !== declared.size)
+            throw new Error('Artifact size differs from task receipt');
+        if (response.headers.get('x-hermes-task-id') !== input.remoteTaskId ||
+            decodeURIComponent(response.headers.get('x-artifact-name') ?? '') !== declared.name ||
+            response.headers.get('content-type')?.split(';')[0] !== declared.mime)
+            throw new Error('Artifact response differs from task receipt');
+        const encoded = response.headers.get('x-hermes-artifact-manifest');
+        if (!encoded || encoded.length > 8192)
+            throw new Error('Artifact manifest is missing or oversized');
+        const manifest = Manifest.parse(JSON.parse(Buffer.from(encoded, 'base64url').toString('utf8')));
+        if (JSON.stringify(manifest) !== JSON.stringify(declared.artifact_manifest) ||
+            manifest.expires_at <= Date.now() / 1000 || manifest.provenance.producer_task_id !== input.remoteTaskId)
+            throw new Error('Artifact manifest differs from task receipt');
+        if (!response.body)
+            throw new Error('Artifact response has no body');
+        const reader = response.body.getReader();
+        const chunks = [];
+        let total = 0;
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                total += value.byteLength;
+                if (total > MAX_BYTES || total > length)
+                    throw new Error('Artifact response exceeds declared size');
+                chunks.push(value);
+            }
+        }
+        catch (error) {
+            await reader.cancel().catch(() => { });
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const bytes = Buffer.concat(chunks, total);
+        if (bytes.byteLength !== length || sha(bytes) !== expected)
+            throw new Error('Artifact bytes differ from task receipt');
+        const local = await this.runtime.artifacts.put(manifest.name, manifest.mime, bytes);
+        this.runtime.store.db.prepare(`INSERT INTO a2a_team_artifact_transfers(id,owner,local_task_id,peer,remote_task_id,
+      remote_context_id,remote_artifact_id,digest,manifest_json,status) VALUES (?,?,?,?,?,?,?,?,?,'complete')`)
+            .run(transferId, input.owner, input.localTaskId, input.peer, input.remoteTaskId, input.remoteContextId, id, local.id, JSON.stringify(manifest));
+        return { ...declared, local_artifact_id: local.id };
+    }
+    project(owner, localTaskId) {
+        const task = this.runtime.store.get(localTaskId);
+        if (!task || task.caller !== owner)
+            throw new Error('Recipient task owner differs');
+        return this.runtime.store.db.prepare(`SELECT * FROM a2a_team_artifact_transfers
+      WHERE owner=? AND local_task_id=? AND status='complete'`).all(owner, localTaskId).map(raw => {
+            const row = TransferRow.parse(raw);
+            return { local_artifact_id: row.digest, peer: row.peer, remote_task_id: row.remote_task_id,
+                artifact_manifest: Manifest.parse(JSON.parse(row.manifest_json)), delivery: 'unverified' };
+        });
+    }
+}

package/dist/team-child.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import type { ArdentRuntime } from './runtime.js';
+import { TeamEnvelope, type TeamResult } from './team-contract.js';
+export declare const TeamChildReference: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    root: z.ZodString;
+    child_id: z.ZodString;
+    sha256: z.ZodString;
+}, z.core.$strict>;
+export type TeamChildReference = z.infer<typeof TeamChildReference>;
+/** A child is admitted only after the retained Hermes root grants its exact scope. */
+export declare class TeamChildService {
+    #private;
+    readonly runtime: ArdentRuntime;
+    constructor(runtime: ArdentRuntime, env: NodeJS.ProcessEnv);
+    claim(raw: unknown, envelope: z.infer<typeof TeamEnvelope>, a2aTaskId: string, contextId: string, authenticatedCaller: string, requestFingerprint: string): Promise<TeamChildReference>;
+    attach(ref: TeamChildReference, operationId: string): void;
+    deadline(ref: TeamChildReference): number;
+    settle(ref: TeamChildReference, outcome: TeamResult['outcome'], result: string): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist/team-child.js

@@ -0,0 +1,130 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { ArdentA2AClient } from './a2a-client.js';
+import { TeamEnvelope } from './team-contract.js';
+const id = z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/);
+const sha = z.string().regex(/^[a-f0-9]{64}$/);
+export const TeamChildReference = z.object({ version: z.literal('1.0'), root: id, child_id: id, sha256: sha }).strict();
+const Grant = z.object({ version: z.literal('1.0'), root: id, child_id: id, target: z.string().regex(/^[A-Za-z0-9_-]{1,64}$/), parent_task: id,
+    context: id, envelope: TeamEnvelope, budget_id: id, depth: z.number().int().min(1).max(4), deadline: z.number().int().positive(), sha256: sha }).strict();
+const ClaimResponse = z.object({ grant: Grant, state: z.literal('claimed'), claim_id: id }).passthrough();
+const SettlementResponse = z.object({ native_id: id, status: z.string() }).passthrough();
+const Row = z.object({ child_id: id, a2a_task_id: z.string(), fingerprint: sha, claim_id: id, root: id, grant_json: z.string(),
+    operation_id: z.string().nullable(), settlement_json: z.string().nullable(), acknowledged: z.number().int() });
+function stable(value) {
+    const sort = (item) => {
+        if (Array.isArray(item))
+            return item.map(sort);
+        if (item && typeof item === 'object')
+            return Object.fromEntries(Object.entries(item)
+                .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, nested]) => [key, sort(nested)]));
+        return item;
+    };
+    return JSON.stringify(sort(value));
+}
+function digest(value) { return createHash('sha256').update(stable(value)).digest('hex'); }
+/** A child is admitted only after the retained Hermes root grants its exact scope. */
+export class TeamChildService {
+    runtime;
+    #client;
+    constructor(runtime, env) {
+        this.runtime = runtime;
+        this.#client = new ArdentA2AClient(runtime.profileDir, runtime.config, env);
+        runtime.store.db.exec(`CREATE TABLE IF NOT EXISTS a2a_team_child_claims (
+      child_id TEXT PRIMARY KEY, a2a_task_id TEXT NOT NULL, fingerprint TEXT NOT NULL,
+      claim_id TEXT NOT NULL, root TEXT NOT NULL, grant_json TEXT NOT NULL,
+      operation_id TEXT, settlement_json TEXT, acknowledged INTEGER NOT NULL DEFAULT 0);`);
+    }
+    #row(childId) {
+        const raw = this.runtime.store.db.prepare('SELECT * FROM a2a_team_child_claims WHERE child_id=?').get(childId);
+        return raw ? Row.parse(raw) : undefined;
+    }
+    async #call(root, action, payload, key) {
+        const control = { version: '1.0', action, key, payload };
+        const receipt = await this.#client.teamControl(root, control);
+        if (receipt['request_digest'] !== digest(control))
+            throw new Error('Root coordination receipt digest differs');
+        return z.record(z.string(), z.unknown()).parse(receipt['data']);
+    }
+    async claim(raw, envelope, a2aTaskId, contextId, authenticatedCaller, requestFingerprint) {
+        const ref = TeamChildReference.parse(raw);
+        if (ref.child_id !== envelope.task_id || envelope.mission.parent_task === null ||
+            authenticatedCaller !== envelope.caller || !envelope.mission.allowed_actions.every(action => action === 'observe' || action === 'analyze'))
+            throw new Error('Child reference is outside the authenticated read-only mission');
+        const fingerprint = digest({ reference: ref, envelope, contextId, caller: authenticatedCaller, requestFingerprint });
+        const db = this.runtime.store.db;
+        let row = this.#row(ref.child_id);
+        if (row && (row.fingerprint !== fingerprint || row.root !== ref.root || row.a2a_task_id !== a2aTaskId))
+            throw new Error('Child receipt already binds different work');
+        if (!row) {
+            const claimId = `claim-${randomUUID().replaceAll('-', '')}`;
+            db.prepare('INSERT INTO a2a_team_child_claims(child_id,a2a_task_id,fingerprint,claim_id,root,grant_json) VALUES (?,?,?,?,?,?)')
+                .run(ref.child_id, a2aTaskId, fingerprint, claimId, ref.root, '{}');
+            row = this.#row(ref.child_id);
+        }
+        if (!row)
+            throw new Error('Child claim was not retained');
+        if (row.operation_id)
+            throw new Error('Child already has a native execution receipt; reconcile without replay');
+        if (row.grant_json !== '{}') {
+            if (Grant.parse(JSON.parse(row.grant_json)).deadline <= Date.now() / 1000)
+                throw new Error('Retained child grant has expired');
+            return ref;
+        }
+        const response = ClaimResponse.parse(await this.#call(ref.root, 'claim_child', { child_id: ref.child_id, grant_sha256: ref.sha256, claim_id: row.claim_id }, `claim-${digest([ref.child_id, row.claim_id])}`));
+        const grant = response.grant;
+        const { sha256, ...unsigned } = grant;
+        if (response.claim_id !== row.claim_id || sha256 !== ref.sha256 || digest(unsigned) !== sha256 ||
+            grant.target !== this.runtime.config.profile || grant.root !== ref.root || grant.child_id !== ref.child_id || grant.context !== contextId ||
+            stable(grant.envelope) !== stable(envelope) || grant.deadline <= Date.now() / 1000 ||
+            grant.deadline > envelope.mission.deadline || grant.parent_task !== envelope.mission.parent_task)
+            throw new Error('Root child grant does not authorize these exact parameters');
+        db.prepare('UPDATE a2a_team_child_claims SET grant_json=? WHERE child_id=?').run(stable(grant), ref.child_id);
+        return ref;
+    }
+    attach(ref, operationId) {
+        const row = this.#row(ref.child_id);
+        if (!row || row.grant_json === '{}')
+            throw new Error('Child execution has no retained root claim');
+        if (row.operation_id && row.operation_id !== operationId)
+            throw new Error('Child native execution identity changed');
+        this.runtime.store.db.prepare('UPDATE a2a_team_child_claims SET operation_id=? WHERE child_id=?').run(operationId, ref.child_id);
+    }
+    deadline(ref) {
+        const row = this.#row(ref.child_id);
+        if (!row || row.grant_json === '{}')
+            throw new Error('Child has no retained root budget');
+        return Grant.parse(JSON.parse(row.grant_json)).deadline;
+    }
+    async settle(ref, outcome, result) {
+        const row = this.#row(ref.child_id);
+        if (!row?.operation_id)
+            throw new Error('Child settlement has no native execution');
+        const value = { child_id: ref.child_id, claim_id: row.claim_id, native_id: row.a2a_task_id,
+            result: Buffer.byteLength(result, 'utf8') > 40_000 ? 'Child result exceeds root settlement limit; inspect retained Ardent task' : result,
+            outcome: Buffer.byteLength(result, 'utf8') > 40_000 ? 'unknown' : outcome };
+        const serialized = stable(value);
+        if (row.settlement_json && row.settlement_json !== serialized)
+            throw new Error('Child settlement cannot change after first publication');
+        if (!row.settlement_json)
+            this.runtime.store.db.prepare('UPDATE a2a_team_child_claims SET settlement_json=? WHERE child_id=?').run(serialized, ref.child_id);
+        if (row.acknowledged)
+            return;
+        const response = SettlementResponse.parse(await this.#call(row.root, 'settle_child', value, `settle-${digest(value)}`));
+        if (response.native_id !== row.a2a_task_id || response.status !== value.outcome)
+            throw new Error('Root child settlement binding differs');
+        this.runtime.store.db.prepare('UPDATE a2a_team_child_claims SET acknowledged=1 WHERE child_id=?').run(ref.child_id);
+    }
+    async flush() {
+        const rows = this.runtime.store.db.prepare('SELECT * FROM a2a_team_child_claims WHERE settlement_json IS NOT NULL AND acknowledged=0 LIMIT 16').all();
+        for (const raw of rows) {
+            try {
+                const row = Row.parse(raw);
+                const value = JSON.parse(row.settlement_json ?? '');
+                const settlement = z.object({ outcome: z.enum(['completed', 'partial', 'failed', 'blocked', 'input_required', 'cancelled', 'unknown']), result: z.string() }).passthrough().parse(value);
+                await this.settle({ version: '1.0', root: row.root, child_id: row.child_id, sha256: Grant.parse(JSON.parse(row.grant_json)).sha256 }, settlement.outcome, settlement.result);
+            }
+            catch { /* Retained settlement is retried later; native work is never replayed. */ }
+        }
+    }
+}

package/dist/team-contract.d.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+export declare const TEAM_VERSION = "1.0";
+export declare const TEAM_TASK_METADATA_KEY = "hermesTeamTask";
+export declare const TEAM_CLARIFICATION_METADATA_KEY = "hermesTeamClarification";
+/** The mission shape without its cross-field rules (Zod 4 cannot omit fields from a refined object). */
+export declare const TeamMissionShape: z.ZodObject<{
+    id: z.ZodString;
+    revision: z.ZodNumber;
+    parent_task: z.ZodNullable<z.ZodString>;
+    constraints: z.ZodArray<z.ZodString>;
+    allowed_actions: z.ZodArray<z.ZodEnum<{
+        observe: "observe";
+        analyze: "analyze";
+        create_artifact: "create_artifact";
+        create_draft: "create_draft";
+        reversible_change: "reversible_change";
+        deploy: "deploy";
+        external_publish: "external_publish";
+        destructive_response: "destructive_response";
+    }>>;
+    resources: z.ZodArray<z.ZodString>;
+    deadline: z.ZodNumber;
+    acceptance_criteria: z.ZodArray<z.ZodString>;
+    expected_artifacts: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const TeamMission: z.ZodObject<{
+    id: z.ZodString;
+    revision: z.ZodNumber;
+    parent_task: z.ZodNullable<z.ZodString>;
+    constraints: z.ZodArray<z.ZodString>;
+    allowed_actions: z.ZodArray<z.ZodEnum<{
+        observe: "observe";
+        analyze: "analyze";
+        create_artifact: "create_artifact";
+        create_draft: "create_draft";
+        reversible_change: "reversible_change";
+        deploy: "deploy";
+        external_publish: "external_publish";
+        destructive_response: "destructive_response";
+    }>>;
+    resources: z.ZodArray<z.ZodString>;
+    deadline: z.ZodNumber;
+    acceptance_criteria: z.ZodArray<z.ZodString>;
+    expected_artifacts: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type TeamMission = z.infer<typeof TeamMission>;
+export declare const TeamEnvelope: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    caller: z.ZodString;
+    task_id: z.ZodString;
+    objective: z.ZodString;
+    mission: z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodNumber;
+        parent_task: z.ZodNullable<z.ZodString>;
+        constraints: z.ZodArray<z.ZodString>;
+        allowed_actions: z.ZodArray<z.ZodEnum<{
+            observe: "observe";
+            analyze: "analyze";
+            create_artifact: "create_artifact";
+            create_draft: "create_draft";
+            reversible_change: "reversible_change";
+            deploy: "deploy";
+            external_publish: "external_publish";
+            destructive_response: "destructive_response";
+        }>>;
+        resources: z.ZodArray<z.ZodString>;
+        deadline: z.ZodNumber;
+        acceptance_criteria: z.ZodArray<z.ZodString>;
+        expected_artifacts: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type TeamEnvelope = z.infer<typeof TeamEnvelope>;
+export declare const TeamResult: z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    mission_id: z.ZodString;
+    mission_revision: z.ZodNumber;
+    task_id: z.ZodString;
+    outcome: z.ZodEnum<{
+        unknown: "unknown";
+        failed: "failed";
+        completed: "completed";
+        input_required: "input_required";
+        partial: "partial";
+        cancelled: "cancelled";
+        blocked: "blocked";
+    }>;
+    summary: z.ZodString;
+    checks: z.ZodArray<z.ZodObject<{
+        criterion: z.ZodString;
+        status: z.ZodEnum<{
+            unknown: "unknown";
+            pass: "pass";
+            fail: "fail";
+        }>;
+        evidence: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    artifacts: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        reference: z.ZodString;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    uncertain_effects: z.ZodArray<z.ZodString>;
+    clarification: z.ZodOptional<z.ZodObject<{
+        missing_fact: z.ZodString;
+        choices: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+        blocked_task: z.ZodString;
+        intended_respondent: z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"operator">]>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type TeamResult = z.infer<typeof TeamResult>;
+export declare function validateTeamEnvelope(value: unknown, authenticatedPeer: string, messageId: string, objective: string, nowSeconds?: number, child?: boolean): TeamEnvelope;
+export declare function validateTeamResult(raw: string, envelope: TeamEnvelope, knownReferences?: ReadonlySet<string>): TeamResult;