@ouro.bot/friends 0.1.0-alpha.4

package/dist/mission-share.d.ts

@@ -0,0 +1,94 @@
+import type { MissionStore } from "./mission-store";
+import type { FriendStore } from "./store";
+import type { GrantStore } from "./grant-store";
+import type { AgentAttribution, MissionRecord, RelationshipOutcome, TrustLevel } from "./types";
+import type { ConsentPolicy } from "./consent";
+import type { AgentVerifier } from "./verifier";
+/** A learning as carried on the wire: its value plus who FIRST asserted it
+ * (`originallyAssertedBy`), so the consumer can attribute it without laundering
+ * an imported fact into first-party. The mission analogue of `SharedNote`. */
+export interface SharedLearning {
+    key: string;
+    value: string;
+    originallyAssertedBy?: AgentAttribution;
+}
+/** The cross-agent mission-share envelope. Names the subject by JOIN KEY
+ * (`missionKey`) + title only — NEVER a local UUID. A SIBLING of
+ * `ProfileShareEnvelope` (Fork A), not a widening. */
+export interface MissionShareEnvelope {
+    /** The mission, named by its join key — `missionKey` + a human title. */
+    subject: {
+        missionKey: string;
+        title: string;
+    };
+    /** The agent that produced this envelope (its join-key agentId). */
+    fromAgentId: string;
+    scope: "mission" | "outcomes";
+    /** Scope-filtered relationship outcomes (present for the `outcomes` scope). */
+    outcomes?: RelationshipOutcome[];
+    /** Scope-filtered shareable learnings (present for the `mission` scope). */
+    learnings?: SharedLearning[];
+    /** Opaque, verifier-specific proof slot. The TOFU verifier ignores it. */
+    proof?: string;
+    issuedAt: string;
+}
+export interface PrepareMissionShareInput {
+    /** The LOCAL mission to share, by its local UUID id (resolved via the store). */
+    missionId: string;
+    /** The recipient agent's join-key agentId. */
+    toAgentId: string;
+    scope: "mission" | "outcomes";
+    /** This agent's own join-key agentId — the original asserter of first-party
+     * learnings (so a shared first-party learning is attributed to self). */
+    selfAgentId: string;
+    /** Optional proof to stamp on the envelope (for a non-TOFU recipient verifier). */
+    proof?: string;
+}
+export type PrepareMissionShareStatus = "not_found" | "no_consent" | "no_recipient";
+export type PrepareMissionShareResult = {
+    ok: true;
+    envelope: MissionShareEnvelope;
+} | {
+    ok: false;
+    status: PrepareMissionShareStatus;
+};
+/**
+ * Producer half of the mission ledger. Consent-gated (subject = the mission's
+ * `missionKey`), scope-filtered, provenance-preserving. Names the mission by its
+ * join key, never the local UUID. The recipient's trust — read off this agent's
+ * own friend record for `toAgentId` — is the authorization input the policy uses.
+ */
+export declare function prepareMissionShare(missions: MissionStore, store: FriendStore, grants: GrantStore, input: PrepareMissionShareInput, consent?: ConsentPolicy): Promise<PrepareMissionShareResult>;
+export interface ImportMissionShareInput {
+    envelope: MissionShareEnvelope;
+    /** The agent the envelope arrived from (its join-key agentId). */
+    fromAgentId: string;
+    /** This agent's resolved trust in the source agent — the cap on acceptance. */
+    trustOfSource: TrustLevel;
+}
+export type ImportMissionShareStatus = "imported" | "seeded" | "no_mission" | "untrusted_source" | "untrusted_introduction";
+export type ImportMissionShareResult = {
+    ok: true;
+    status: "imported" | "seeded";
+    record: MissionRecord;
+} | {
+    ok: false;
+    status: "no_mission" | "untrusted_source" | "untrusted_introduction";
+};
+export interface ImportMissionShareOptions {
+    /** Authentication seam. Defaults to TOFU. Authorization (trust) is still
+     * applied regardless of what the verifier says. */
+    verifier?: AgentVerifier;
+    /** Minimum trust a source must hold for its facts to be accepted at all.
+     * Default `acquaintance`: a stranger source is refused. */
+    minTrustToAccept?: TrustLevel;
+}
+/**
+ * Consumer half of the mission ledger — the non-clobbering merge. Resolves the
+ * mission by `findByMissionKey`; lands imported learnings in the
+ * `importedLearnings` namespace WITHOUT touching first-party `learnings`;
+ * append-merges + dedupes imported outcomes; NEVER recomputes status /
+ * participants; the source agent's trust caps acceptance; seeds an unknown
+ * mission only when a friend/family peer introduces it.
+ */
+export declare function importMissionShare(missions: MissionStore, input: ImportMissionShareInput, options?: ImportMissionShareOptions): Promise<ImportMissionShareResult>;

package/dist/mission-share.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareMissionShare = prepareMissionShare;
+exports.importMissionShare = importMissionShare;
+// prepareMissionShare (producer) + importMissionShare (consumer) — the shared
+// mission ledger (brick 3). Structural twins of share.ts's profile producer /
+// consumer, re-aimed from a PERSON at a MISSION.
+//
+// Two DIFFERENT agents agreeing they did the SAME mission (by `missionKey`) AND
+// sharing what they collectively learned — WITH CONSENT, without first-party
+// learnings being clobbered. Store-only + transport-agnostic: prepareMissionShare
+// returns an envelope, importMissionShare consumes one; the WIRE is the caller's
+// job. Pure — the only node builtin is `node:crypto`, mirroring share.ts.
+//
+// Through-line invariants (every one is tested in mission-share.test.ts):
+//  - the mission is named by its JOIN KEY (`missionKey`), NEVER the local UUID;
+//  - the share is consent-gated (subject = the missionKey) and scope-filtered;
+//  - imported learnings NEVER touch first-party `learnings` (a separate
+//    `importedLearnings` namespace) — first-party always wins, structurally;
+//  - the source agent's trust CAPS acceptance (a stranger peer is refused);
+//  - `status` / `participants` are NEVER recomputed from an import (non-transitive);
+//  - imported outcomes are append-merged, stamped `origin:imported`, and deduped
+//    by (missionId, timestamp, assertedBy.agentId) — same peer idempotent,
+//    different peers coexist;
+//  - an unknown mission may be SEEDED only by a friend/family introducing peer.
+const node_crypto_1 = require("node:crypto");
+const observability_1 = require("./observability");
+const consent_1 = require("./consent");
+const verifier_1 = require("./verifier");
+const share_1 = require("./share");
+/** Build the scope-filtered shared learnings: only `shareable` learnings, each
+ * attributed to its original asserter (self for a first-party learning, the
+ * recorded original asserter for a relayed import). Reuses `originalAsserterOf`
+ * from share.ts — single-sourced, no duplicate coverage surface. */
+function buildSharedLearnings(record, selfAgentId) {
+    return Object.entries(record.learnings)
+        .filter(([, learning]) => learning.shareable === true)
+        .map(([key, learning]) => ({
+        key,
+        value: learning.value,
+        originallyAssertedBy: (0, share_1.originalAsserterOf)(learning, selfAgentId),
+    }));
+}
+/**
+ * Producer half of the mission ledger. Consent-gated (subject = the mission's
+ * `missionKey`), scope-filtered, provenance-preserving. Names the mission by its
+ * join key, never the local UUID. The recipient's trust — read off this agent's
+ * own friend record for `toAgentId` — is the authorization input the policy uses.
+ */
+async function prepareMissionShare(missions, store, grants, input, consent = consent_1.DEFAULT_CONSENT_POLICY) {
+    const record = await missions.get(input.missionId);
+    if (!record) {
+        return { ok: false, status: "not_found" };
+    }
+    // The recipient's trust is read from this agent's own knowledge of it (the
+    // a2a-agent friend record for toAgentId). An unknown recipient defaults to
+    // stranger — never trusted by default.
+    const recipientRecord = await store.findByExternalId("a2a-agent", input.toAgentId);
+    const recipientTrust = recipientRecord?.trustLevel ?? "stranger";
+    const recipient = { agentId: input.toAgentId, trustLevel: recipientTrust };
+    // The subject is the mission, keyed by its missionKey (a mission is just
+    // another grant subject under the Fork-D opaque subject key).
+    const consented = await consent.consents({
+        subjectKey: record.missionKey,
+        recipient,
+        scope: input.scope,
+        grants,
+    });
+    if (!consented) {
+        return { ok: false, status: "no_consent" };
+    }
+    const now = new Date().toISOString();
+    const envelope = {
+        subject: { missionKey: record.missionKey, title: record.title },
+        fromAgentId: input.selfAgentId,
+        scope: input.scope,
+        issuedAt: now,
+        ...(input.proof !== undefined ? { proof: input.proof } : {}),
+        ...(input.scope === "outcomes"
+            ? { outcomes: record.outcomes }
+            : { learnings: buildSharedLearnings(record, input.selfAgentId) }),
+    };
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.mission_share_prepared",
+        message: "prepared mission share envelope",
+        meta: { scope: input.scope, toAgentId: input.toAgentId, consentPolicy: consent.name },
+    });
+    return { ok: true, envelope };
+}
+// ── Consumer ──
+/** Trust levels a peer must hold to INTRODUCE a previously-unknown mission. A
+ * friend/family peer may seed a new mission; a stranger / acquaintance peer may
+ * not (mirrors the person path's SEEDING_TRUST). */
+const SEEDING_TRUST = new Set(["family", "friend"]);
+const TRUST_RANK = { family: 4, friend: 3, acquaintance: 2, stranger: 1 };
+function importedLearningFrom(learning, fromAgentId, now) {
+    return {
+        value: learning.value,
+        importedAt: now,
+        assertedBy: { agentId: fromAgentId },
+        ...(learning.originallyAssertedBy ? { originallyAssertedBy: learning.originallyAssertedBy } : {}),
+    };
+}
+/** Merge the envelope's learnings into the record's `importedLearnings` namespace
+ * under the source agentId. First-party `learnings` are NOT passed in and are
+ * physically untouched. Within the namespace, the newest import wins per key. */
+function mergeImportedLearnings(record, learnings, fromAgentId, now) {
+    const existing = record.importedLearnings ?? {};
+    const forAgent = { ...(existing[fromAgentId] ?? {}) };
+    for (const learning of learnings) {
+        forAgent[learning.key] = importedLearningFrom(learning, fromAgentId, now);
+    }
+    return { ...existing, [fromAgentId]: forAgent };
+}
+/** Append the envelope's outcomes to the record's outcomes, stamping each with
+ * `origin:imported` + the source attribution + importedAt, and DEDUPING by
+ * (missionId, timestamp, assertedBy.agentId): a row whose identity already exists
+ * is skipped (same peer idempotent); a row from a different peer with the same
+ * (missionId, timestamp) coexists. The existing rows' `assertedBy?.agentId` is
+ * read defensively — a first-party outcome may carry no provenance, and must
+ * never be spuriously matched. This outcome-merge is genuinely NEW logic (the
+ * person path's import never merged outcomes). */
+function mergeImportedOutcomes(existing, incoming, fromAgentId, now) {
+    const identityOf = (o, assertedAgentId) => JSON.stringify([o.missionId, o.timestamp, assertedAgentId]);
+    const seen = new Set(existing.map((o) => identityOf(o, o.provenance?.assertedBy?.agentId)));
+    const merged = [...existing];
+    for (const o of incoming) {
+        const identity = identityOf(o, fromAgentId);
+        if (seen.has(identity))
+            continue;
+        seen.add(identity);
+        merged.push({
+            missionId: o.missionId,
+            result: o.result,
+            timestamp: o.timestamp,
+            ...(o.note ? { note: o.note } : {}),
+            provenance: { origin: "imported", assertedBy: { agentId: fromAgentId }, importedAt: now },
+        });
+    }
+    return merged;
+}
+/** Create a freshly-seeded mission for a previously-unknown key. Always
+ * `status:"active"`, empty first-party `learnings`, carrying the subject's join
+ * key + title. */
+function seedMission(envelope, now) {
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        missionKey: envelope.subject.missionKey,
+        title: envelope.subject.title,
+        status: "active",
+        participants: [],
+        outcomes: [],
+        learnings: {},
+        importedLearnings: {},
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: 1,
+    };
+}
+/** Apply an envelope's payload to a mission record WITHOUT recomputing its
+ * `status` or `participants` (non-transitive) and WITHOUT touching first-party
+ * `learnings`. Only `importedLearnings`, `outcomes`, and `updatedAt` change. */
+function applyEnvelopeToMission(record, envelope, fromAgentId, now) {
+    const importedLearnings = envelope.learnings && envelope.learnings.length > 0
+        ? mergeImportedLearnings(record, envelope.learnings, fromAgentId, now)
+        : record.importedLearnings;
+    const outcomes = envelope.outcomes && envelope.outcomes.length > 0
+        ? mergeImportedOutcomes(record.outcomes, envelope.outcomes, fromAgentId, now)
+        : record.outcomes;
+    return {
+        ...record,
+        // status / participants are intentionally NOT recomputed — an import must
+        // never flip the mission's status (the non-transitive invariant).
+        ...(importedLearnings ? { importedLearnings } : {}),
+        outcomes,
+        updatedAt: now,
+    };
+}
+/**
+ * Consumer half of the mission ledger — the non-clobbering merge. Resolves the
+ * mission by `findByMissionKey`; lands imported learnings in the
+ * `importedLearnings` namespace WITHOUT touching first-party `learnings`;
+ * append-merges + dedupes imported outcomes; NEVER recomputes status /
+ * participants; the source agent's trust caps acceptance; seeds an unknown
+ * mission only when a friend/family peer introduces it.
+ */
+async function importMissionShare(missions, input, options = {}) {
+    const verifier = options.verifier ?? verifier_1.DEFAULT_AGENT_VERIFIER;
+    const minTrust = options.minTrustToAccept ?? "acquaintance";
+    // Authentication (caller's seam) AND authorization (trust ladder) must BOTH
+    // pass. The verifier authenticates the wire; the trust cap is the package's own
+    // gate and applies regardless of what the verifier returns.
+    const authenticated = verifier.verify(input.fromAgentId, input.envelope.proof);
+    const trustedEnough = TRUST_RANK[input.trustOfSource] >= TRUST_RANK[minTrust];
+    if (!authenticated || !trustedEnough) {
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.mission_share_refused",
+            message: "refused mission share from untrusted source",
+            meta: { fromAgentId: input.fromAgentId, trustOfSource: input.trustOfSource, authenticated },
+        });
+        return { ok: false, status: "untrusted_source" };
+    }
+    const now = new Date().toISOString();
+    const existing = await missions.findByMissionKey(input.envelope.subject.missionKey);
+    if (!existing) {
+        // Unknown mission. Only a friend/family peer may seed a new one.
+        if (!SEEDING_TRUST.has(input.trustOfSource)) {
+            return { ok: false, status: "untrusted_introduction" };
+        }
+        const seeded = seedMission(input.envelope, now);
+        const withPayload = applyEnvelopeToMission(seeded, input.envelope, input.fromAgentId, now);
+        await missions.put(withPayload.id, withPayload);
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.mission_share_seeded",
+            message: "seeded new mission from mission share",
+            meta: { missionId: withPayload.id, fromAgentId: input.fromAgentId },
+        });
+        return { ok: true, status: "seeded", record: withPayload };
+    }
+    const updated = applyEnvelopeToMission(existing, input.envelope, input.fromAgentId, now);
+    await missions.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.mission_share_imported",
+        message: "imported mission share into existing mission",
+        meta: { missionId: updated.id, fromAgentId: input.fromAgentId, scope: input.envelope.scope },
+    });
+    return { ok: true, status: "imported", record: updated };
+}

package/dist/mission-store-file.d.ts

@@ -0,0 +1,18 @@
+import type { MissionStore } from "./mission-store";
+import type { MissionRecord } from "./types";
+/** The sibling missions directory for a given friends directory:
+ * `<friendsDir>/_missions`. The collection lives UNDER the friends dir (a
+ * reserved `_`-prefixed subdir) so a single `--dir` still points the whole
+ * substrate at one place. */
+export declare function missionsDirFor(friendsDir: string): string;
+export declare class FileMissionStore implements MissionStore {
+    private readonly missionsPath;
+    constructor(missionsPath: string);
+    get(id: string): Promise<MissionRecord | null>;
+    put(id: string, mission: MissionRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+    findByMissionKey(missionKey: string): Promise<MissionRecord | null>;
+    listAll(): Promise<MissionRecord[]>;
+    private normalize;
+    private readJson;
+}

package/dist/mission-store-file.js

@@ -0,0 +1,153 @@
+"use strict";
+// FileMissionStore — filesystem adapter for MissionStore (brick 3).
+// Stores each MissionRecord as one JSON file in a sibling `_missions/` collection
+// next to the friends directory. Mirrors FileGrantStore's structure (mkdir on
+// construct, one file per record, guarded reads, a `normalize` for round-trip
+// discipline) so the three stores feel uniform.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileMissionStore = void 0;
+exports.missionsDirFor = missionsDirFor;
+const fs = __importStar(require("fs"));
+const fsPromises = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const observability_1 = require("./observability");
+const MISSION_STATUSES = new Set([
+    "active",
+    "succeeded",
+    "partial",
+    "failed",
+    "abandoned",
+]);
+/** The sibling missions directory for a given friends directory:
+ * `<friendsDir>/_missions`. The collection lives UNDER the friends dir (a
+ * reserved `_`-prefixed subdir) so a single `--dir` still points the whole
+ * substrate at one place. */
+function missionsDirFor(friendsDir) {
+    return path.join(friendsDir, "_missions");
+}
+class FileMissionStore {
+    missionsPath;
+    constructor(missionsPath) {
+        this.missionsPath = missionsPath;
+        fs.mkdirSync(missionsPath, { recursive: true });
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.mission_store_init",
+            message: "file mission store initialized",
+            meta: {},
+        });
+    }
+    async get(id) {
+        const mission = await this.readJson(path.join(this.missionsPath, `${id}.json`));
+        return mission ? this.normalize(mission) : null;
+    }
+    async put(id, mission) {
+        await fsPromises.writeFile(path.join(this.missionsPath, `${id}.json`), JSON.stringify(this.normalize(mission), null, 2), "utf-8");
+    }
+    async delete(id) {
+        try {
+            await fsPromises.unlink(path.join(this.missionsPath, `${id}.json`));
+        }
+        catch (err) {
+            if (err?.code === "ENOENT")
+                return;
+            throw err;
+        }
+    }
+    async findByMissionKey(missionKey) {
+        const all = await this.listAll();
+        return all.find((m) => m.missionKey === missionKey) ?? null;
+    }
+    async listAll() {
+        let entries;
+        try {
+            entries = await fsPromises.readdir(this.missionsPath);
+        }
+        catch {
+            /* v8 ignore next -- defensive: dir is mkdir'd in the constructor, so readdir
+               only throws if it's deleted mid-run; unreachable through the API @preserve */
+            return [];
+        }
+        const missions = [];
+        for (const entry of entries) {
+            if (!entry.endsWith(".json"))
+                continue;
+            const raw = await this.readJson(path.join(this.missionsPath, entry));
+            if (!raw)
+                continue;
+            missions.push(this.normalize(raw));
+        }
+        return missions;
+    }
+    normalize(raw) {
+        return {
+            id: raw.id,
+            missionKey: raw.missionKey,
+            title: typeof raw.title === "string" ? raw.title : raw.missionKey,
+            status: typeof raw.status === "string" && MISSION_STATUSES.has(raw.status) ? raw.status : "active",
+            participants: Array.isArray(raw.participants) ? raw.participants : [],
+            outcomes: Array.isArray(raw.outcomes) ? raw.outcomes : [],
+            learnings: raw.learnings && typeof raw.learnings === "object" ? raw.learnings : {},
+            ...(raw.importedLearnings && typeof raw.importedLearnings === "object" ? { importedLearnings: raw.importedLearnings } : {}),
+            // The coordination sub-object (brick 5) passes through like importedLearnings:
+            // present iff the record carries one, so a legacy mission with no coordination
+            // round-trips unchanged (absent ⇒ unclaimed).
+            ...(raw.coordination && typeof raw.coordination === "object" ? { coordination: raw.coordination } : {}),
+            createdAt: typeof raw.createdAt === "string" ? raw.createdAt : new Date().toISOString(),
+            updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : new Date().toISOString(),
+            schemaVersion: typeof raw.schemaVersion === "number" ? raw.schemaVersion : 1,
+        };
+    }
+    async readJson(filePath) {
+        try {
+            const raw = await fsPromises.readFile(filePath, "utf-8");
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    return null;
+                }
+                return parsed;
+            }
+            catch {
+                return null;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.FileMissionStore = FileMissionStore;

package/dist/mission-store.d.ts

@@ -0,0 +1,10 @@
+import type { MissionRecord } from "./types";
+export interface MissionStore {
+    get(id: string): Promise<MissionRecord | null>;
+    put(id: string, mission: MissionRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Resolve a mission by its cross-agent join key (the name on the wire), not
+     * the local UUID. Returns null when no mission carries that key. */
+    findByMissionKey(missionKey: string): Promise<MissionRecord | null>;
+    listAll(): Promise<MissionRecord[]>;
+}

package/dist/mission-store.js

@@ -0,0 +1,9 @@
+"use strict";
+// Mission store abstraction (brick 3).
+// MissionRecord state persists through MissionStore — a sibling to FriendStore /
+// GrantStore, mirroring their shape. A mission is many-to-many with peers and has
+// its own identity/lifecycle, so it lives in its own collection rather than on a
+// friend record. Adds `findByMissionKey` (the cross-agent join-key lookup the
+// consumer resolves on) over the get/put/delete/listAll quartet. No mission
+// module imports `fs` directly except the FileMissionStore adapter.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/missions.d.ts

@@ -0,0 +1,31 @@
+import type { MissionStore } from "./mission-store";
+import type { AgentAttribution, MissionRecord, RelationshipOutcome } from "./types";
+export interface RecordMissionInput {
+    missionKey: string;
+    /** Used only when CREATING; ignored on upsert of an existing mission. */
+    title?: string;
+    /** When provided, sets the mission's status (first-party). */
+    status?: MissionRecord["status"];
+    /** Merged into the mission's participants, deduped by agentId. */
+    participants?: AgentAttribution[];
+    /** Appended to the first-party `learnings` map (NEVER `importedLearnings`). */
+    learnings?: Array<{
+        key: string;
+        value: string;
+        shareable?: boolean;
+    }>;
+    /** Appended to the mission's outcomes as first-party rows (no `origin:imported`). */
+    outcomes?: Array<{
+        missionId: string;
+        result: RelationshipOutcome["result"];
+        note?: string;
+    }>;
+}
+/**
+ * Upsert a mission by its `missionKey`. Creates a fresh record (new local UUID,
+ * `status:"active"`, empty namespaces) when the key is unknown; otherwise
+ * resolves the existing record and applies the input. First-party learnings are
+ * this agent's own — they NEVER touch `importedLearnings`. Returns the persisted
+ * record.
+ */
+export declare function recordMission(missions: MissionStore, input: RecordMissionInput): Promise<MissionRecord>;

package/dist/missions.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordMission = recordMission;
+// recordMission — the first-party mission writer (brick 3).
+//
+// Upserts a MissionRecord by its cross-agent `missionKey`: creates one with a
+// fresh local UUID when the key is unknown, else resolves the existing record via
+// `findByMissionKey` and applies the input. First-party learnings land in
+// `learnings` (this agent's own knowledge — NEVER in `importedLearnings`);
+// participants merge deduped by agentId; outcomes append; status updates when
+// provided. The companion to the UNTOUCHED `recordRelationshipOutcome` in
+// `outcomes.ts` (that writer owns a friend's denormalized outcome index; this one
+// owns the mission record). Pure store ops — no fs / net / env; the only node
+// builtin is `node:crypto` (randomUUID), mirroring share.ts.
+const node_crypto_1 = require("node:crypto");
+const observability_1 = require("./observability");
+/** Merge the input participants into the existing list, deduped by agentId. A
+ * participant whose agentId already appears is skipped (idempotent). */
+function mergeParticipants(existing, incoming) {
+    const seen = new Set(existing.map((p) => p.agentId));
+    const merged = [...existing];
+    for (const p of incoming) {
+        if (!seen.has(p.agentId)) {
+            merged.push(p);
+            seen.add(p.agentId);
+        }
+    }
+    return merged;
+}
+/** Apply the input's first-party learnings onto the existing learnings map,
+ * stamping each with `savedAt` + first-party provenance. */
+function applyLearnings(existing, incoming, now) {
+    const learnings = { ...existing };
+    for (const l of incoming) {
+        learnings[l.key] = {
+            value: l.value,
+            savedAt: now,
+            shareable: l.shareable ?? false,
+            provenance: { origin: "first_party" },
+        };
+    }
+    return learnings;
+}
+/** Append the input's first-party outcomes, stamping each with a timestamp. */
+function applyOutcomes(existing, incoming, now) {
+    const outcomes = [...existing];
+    for (const o of incoming) {
+        outcomes.push({
+            missionId: o.missionId,
+            result: o.result,
+            timestamp: now,
+            ...(o.note ? { note: o.note } : {}),
+        });
+    }
+    return outcomes;
+}
+/**
+ * Upsert a mission by its `missionKey`. Creates a fresh record (new local UUID,
+ * `status:"active"`, empty namespaces) when the key is unknown; otherwise
+ * resolves the existing record and applies the input. First-party learnings are
+ * this agent's own — they NEVER touch `importedLearnings`. Returns the persisted
+ * record.
+ */
+async function recordMission(missions, input) {
+    const now = new Date().toISOString();
+    const found = await missions.findByMissionKey(input.missionKey);
+    const base = found ?? {
+        id: (0, node_crypto_1.randomUUID)(),
+        missionKey: input.missionKey,
+        title: input.title ?? input.missionKey,
+        status: input.status ?? "active",
+        participants: [],
+        outcomes: [],
+        learnings: {},
+        importedLearnings: {},
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: 1,
+    };
+    const updated = {
+        ...base,
+        // `status` is set from the input when provided (first-party). On create it is
+        // already baked into `base`; this re-applies it on an upsert.
+        status: input.status ?? base.status,
+        participants: input.participants ? mergeParticipants(base.participants, input.participants) : base.participants,
+        outcomes: input.outcomes ? applyOutcomes(base.outcomes, input.outcomes, now) : base.outcomes,
+        learnings: input.learnings ? applyLearnings(base.learnings, input.learnings, now) : base.learnings,
+        updatedAt: now,
+    };
+    await missions.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.mission_recorded",
+        message: "recorded mission",
+        meta: { missionKey: input.missionKey, created: found === null, status: updated.status },
+    });
+    return updated;
+}

package/dist/notes.d.ts

@@ -0,0 +1,11 @@
+import type { FriendStore } from "./store";
+import type { NoteProvenance } from "./types";
+import type { FriendOpResult } from "./results";
+export interface ApplyFriendNoteInput {
+    type: "name" | "tool_preference" | "note";
+    key?: string;
+    content: string;
+    override?: boolean;
+    provenance?: NoteProvenance;
+}
+export declare function applyFriendNote(store: FriendStore, friendId: string, input: ApplyFriendNoteInput): Promise<FriendOpResult>;