@ouro.bot/friends 0.1.0-alpha.4

package/dist/share.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.originalAsserterOf = originalAsserterOf;
+exports.prepareProfileShare = prepareProfileShare;
+exports.importProfileShare = importProfileShare;
+// prepareProfileShare (producer) + importProfileShare (consumer) — the moat (N12).
+//
+// Two DIFFERENT agents agreeing a party is the same person AND sharing what they
+// know — WITH CONSENT, without first-party knowledge being clobbered. The package
+// stays store-only + transport-agnostic: prepareProfileShare returns an envelope,
+// importProfileShare consumes one; the WIRE between them is the caller's job.
+//
+// Through-line invariants (every one is tested):
+//  - the party is named by its JOIN KEY (externalIds), NEVER the local UUID;
+//  - the share is consent-gated (a ConsentPolicy) and scope-filtered;
+//  - imported facts NEVER touch first-party `notes` (a separate `importedNotes`
+//    namespace) — first-party always wins, structurally;
+//  - the source agent's trust CAPS acceptance (a stranger peer is refused);
+//  - imports NEVER change the party's trust level (non-transitive — the key one);
+//  - an unknown party may be SEEDED only by a friend/family introducing peer
+//    (Fork E); a stranger/acquaintance peer may not seed a new record.
+const node_crypto_1 = require("node:crypto");
+const observability_1 = require("./observability");
+const types_1 = require("./types");
+const consent_1 = require("./consent");
+const verifier_1 = require("./verifier");
+/** The original asserter of a note: for an imported note, whoever the import
+ * recorded as `originallyAssertedBy` (falling back to its `assertedBy`); for a
+ * first-party note, this agent itself. Never launders imported → first-party.
+ * Always returns an attribution (a shared fact is always attributable). Exported
+ * so the mission-share producer reuses it (a MissionLearning is structurally
+ * compatible with the inline param type) — single-sourced, tested once. */
+function originalAsserterOf(note, selfAgentId) {
+    if (note.provenance?.origin === "imported") {
+        return note.provenance.assertedBy ?? { agentId: selfAgentId };
+    }
+    return { agentId: selfAgentId };
+}
+function buildSharedNotes(record, scope, selfAgentId) {
+    return Object.entries(record.notes)
+        .filter(([, note]) => scope === "notes:all" || note.shareable === true)
+        .map(([key, note]) => ({
+        key,
+        value: note.value,
+        originallyAssertedBy: originalAsserterOf(note, selfAgentId),
+    }));
+}
+/**
+ * Producer half of the moat. Consent-gated (via the injected ConsentPolicy, or
+ * the module default), scope-filtered, provenance-preserving. Names the party by
+ * join key, never the local UUID. The recipient's trust level — read off this
+ * agent's own record for `toAgentId` — is the authorization input the policy
+ * uses. Returns `{ ok:true, envelope }` or `{ ok:false, status }`.
+ */
+async function prepareProfileShare(store, grants, input, consent = consent_1.DEFAULT_CONSENT_POLICY) {
+    const record = await store.get(input.friendId);
+    if (!record) {
+        return { ok: false, status: "not_found" };
+    }
+    // The recipient's trust level is read from this agent's own knowledge of it
+    // (the a2a-agent 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 };
+    const consented = await consent.consents({
+        subjectKey: record.id,
+        recipient,
+        scope: input.scope,
+        grants,
+    });
+    if (!consented) {
+        return { ok: false, status: "no_consent" };
+    }
+    const now = new Date().toISOString();
+    const isIdentityScope = types_1.IDENTITY_SCOPES.has(input.scope);
+    const envelope = {
+        subject: {
+            externalIds: record.externalIds,
+            displayName: record.name,
+        },
+        fromAgentId: input.selfAgentId,
+        scope: input.scope,
+        issuedAt: now,
+        ...(input.proof !== undefined ? { proof: input.proof } : {}),
+        ...(input.scope === "outcomes"
+            ? { outcomes: record.agentMeta?.outcomes ?? [] }
+            : {}),
+        ...(!isIdentityScope && input.scope !== "outcomes"
+            ? { notes: buildSharedNotes(record, input.scope, input.selfAgentId) }
+            : {}),
+    };
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.profile_share_prepared",
+        message: "prepared profile 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 party (Fork E).
+ * A friend/family peer may seed a new record at acquaintance; a stranger /
+ * acquaintance peer may not. */
+const SEEDING_TRUST = new Set(["family", "friend"]);
+const TRUST_RANK = { family: 4, friend: 3, acquaintance: 2, stranger: 1 };
+/** Find the local friend the envelope's subject refers to, by join key — the
+ * FIRST of the subject's externalIds that resolves to an existing record. */
+async function resolveSubject(store, envelope) {
+    for (const ext of envelope.subject.externalIds) {
+        const found = await store.findByExternalId(ext.provider, ext.externalId, ext.tenantId);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function importedNoteFrom(note, fromAgentId, now) {
+    return {
+        value: note.value,
+        importedAt: now,
+        assertedBy: { agentId: fromAgentId },
+        ...(note.originallyAssertedBy ? { originallyAssertedBy: note.originallyAssertedBy } : {}),
+    };
+}
+/** Merge the envelope's notes into the record's `importedNotes` namespace under
+ * the source agentId. First-party `notes` are NOT passed in and are physically
+ * untouched. Within the namespace, the newest import wins on key collision. */
+function mergeImportedNotes(record, notes, fromAgentId, now) {
+    const existing = record.importedNotes ?? {};
+    const forAgent = { ...(existing[fromAgentId] ?? {}) };
+    for (const note of notes) {
+        forAgent[note.key] = importedNoteFrom(note, fromAgentId, now);
+    }
+    return { ...existing, [fromAgentId]: forAgent };
+}
+/** Create a freshly-seeded record for a previously-unknown party (Fork E). Always
+ * `acquaintance`, kind `human`, carrying the subject's join-key externalIds. */
+function seedRecord(envelope, now) {
+    return {
+        id: (0, node_crypto_1.randomUUID)(),
+        name: envelope.subject.displayName,
+        role: "acquaintance",
+        trustLevel: "acquaintance",
+        connections: [],
+        externalIds: envelope.subject.externalIds.map((ext) => ({ ...ext, linkedAt: now })),
+        tenantMemberships: [],
+        toolPreferences: {},
+        notes: {},
+        totalTokens: 0,
+        createdAt: now,
+        updatedAt: now,
+        schemaVersion: 1,
+        kind: "human",
+    };
+}
+/**
+ * Consumer half of the moat — the non-clobbering merge. Resolves the party by
+ * join key; lands imported facts in the `importedNotes` namespace (origin
+ * "imported" + assertedBy + importedAt) WITHOUT ever touching first-party `notes`;
+ * the source agent's trust caps acceptance; NEVER changes the party's trust level
+ * (the key safety invariant); seeds an unknown party only when a friend/family
+ * peer introduces it. Returns `{ ok, status, record }`.
+ */
+async function importProfileShare(store, 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.profile_share_refused",
+            message: "refused profile 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 resolveSubject(store, input.envelope);
+    if (!existing) {
+        // Unknown party. Fork E: only a friend/family peer may seed a new record.
+        if (!SEEDING_TRUST.has(input.trustOfSource)) {
+            return { ok: false, status: "untrusted_introduction" };
+        }
+        const seeded = seedRecord(input.envelope, now);
+        const withNotes = applyEnvelopeToRecord(seeded, input.envelope, input.fromAgentId, now);
+        await store.put(withNotes.id, withNotes);
+        (0, observability_1.emitNervesEvent)({
+            component: "friends",
+            event: "friends.profile_share_seeded",
+            message: "seeded new party from profile share",
+            meta: { friendId: withNotes.id, fromAgentId: input.fromAgentId },
+        });
+        return { ok: true, status: "seeded", record: withNotes };
+    }
+    const updated = applyEnvelopeToRecord(existing, input.envelope, input.fromAgentId, now);
+    await store.put(updated.id, updated);
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.profile_share_imported",
+        message: "imported profile share into existing party",
+        meta: { friendId: updated.id, fromAgentId: input.fromAgentId, scope: input.envelope.scope },
+    });
+    return { ok: true, status: "imported", record: updated };
+}
+/** Apply an envelope's payload to a record WITHOUT changing its trust level or
+ * touching first-party `notes`. Only `importedNotes` (and `updatedAt`) change.
+ * `trustLevel` and `role` are copied through verbatim — imports are non-transitive. */
+function applyEnvelopeToRecord(record, envelope, fromAgentId, now) {
+    const importedNotes = envelope.notes && envelope.notes.length > 0
+        ? mergeImportedNotes(record, envelope.notes, fromAgentId, now)
+        : record.importedNotes;
+    return {
+        ...record,
+        // trustLevel / role are intentionally NOT recomputed — an import must never
+        // change the party's trust (the single most important safety invariant).
+        ...(importedNotes ? { importedNotes } : {}),
+        updatedAt: now,
+    };
+}

package/dist/standing.d.ts

@@ -0,0 +1,83 @@
+import type { FriendRecord } from "./types";
+/** A peer's earned standing tier - derived from the first-party outcomes you
+ * personally recorded with them. Ordered worst→best for reference:
+ * `troubled` < `untested` < `mixed` < `reliable` < `proven`. */
+export type StandingTier = "proven" | "reliable" | "mixed" | "untested" | "troubled";
+/** The tally of first-party outcomes by result (imported outcomes excluded). */
+export interface StandingTally {
+    success: number;
+    partial: number;
+    failed: number;
+}
+/** A derived, advisory assessment of a peer from your first-party outcomes.
+ * Computed on read; persisted nowhere; never crosses the wire. */
+export interface Standing {
+    tier: StandingTier;
+    /** How many first-party outcomes the tier rests on (imported excluded). */
+    basisCount: number;
+    tally: StandingTally;
+    /** The peer's familiarity counter (read through from `agentMeta`). */
+    familiarity: number;
+    /** ISO timestamp at which this assessment was computed. */
+    assessedAt: string;
+}
+/** A human gloss of a `Standing` plus advisory notes that frame it as input to a
+ * MANUAL trust decision - never an instruction to change trust. */
+export interface StandingExplanation {
+    standing: Standing;
+    summary: string;
+    why: string;
+    /** Advisory notes. ALWAYS includes the guardrail that standing does not change
+     * the peer's trust level (the anti-auto-promote firewall). */
+    advisory: string[];
+}
+/** The inputs a tier rule maps to a `StandingTier`: the first-party tally, the
+ * basis count, and the peer's familiarity. */
+export interface StandingRuleInput {
+    tally: StandingTally;
+    basisCount: number;
+    familiarity: number;
+}
+/**
+ * A pluggable tier rule - the swap point (mirrors `ConsentPolicy`). `tier`
+ * deterministically maps `(tally, basisCount, familiarity)` to a `StandingTier`.
+ * Inject a custom rule to change the ladder (e.g. add time-decay later) without
+ * touching `assessStanding`/`explainStanding`.
+ */
+export interface StandingRule {
+    readonly name: string;
+    tier(input: StandingRuleInput): StandingTier;
+}
+/**
+ * The familiarity floor a peer must reach (alongside ≥3 clean successes) to earn
+ * `proven`. Equal to the proven success floor - a peer is only "proven" once you
+ * have both enough good outcomes AND enough lived history. Tunable.
+ */
+export declare const FAMILIARITY_THRESHOLD = 3;
+/**
+ * ── STANDING-RULE SWAP POINT (the default tier ladder) ──
+ * The active tier rule. A fixed, transparent, count-based ladder - NOT ML:
+ *   • no basis at all          → `untested`
+ *   • failures outnumber wins  → `troubled`
+ *   • ≥3 clean wins + familiar  → `proven`
+ *   • ≥1 clean win              → `reliable`
+ *   • otherwise (mixed signal)  → `mixed`
+ * Swap this assignment (or inject a `rule` per-call) to change the ladder; e.g. a
+ * later recency/decay rule is an additive swap here, not a rebuild.
+ */
+export declare const DEFAULT_STANDING_RULE: StandingRule;
+/**
+ * Assess a peer's earned standing from the first-party outcomes you personally
+ * recorded with them. Pure + store-free: reads `agentMeta.outcomes`, FILTERS to
+ * first-party (firewall 1), tallies by result, reads `familiarity`, and maps via
+ * the (injectable) tier rule. Emits `friends.standing_assessed`. Returns a value;
+ * never writes trust (firewall 2); never produces a wire artifact (firewall 3).
+ */
+export declare function assessStanding(record: FriendRecord, now?: Date, rule?: StandingRule): Standing;
+/**
+ * Explain a peer's earned standing in words: the tier with a human `summary` +
+ * `why`, plus `advisory` notes that explicitly frame standing as input to a
+ * MANUAL trust decision (firewall 4 - never an instruction to change trust).
+ * Mirrors `describeTrustContext`'s shape.
+ */
+export declare function explainStanding(record: FriendRecord, now?: Date, rule?: StandingRule): StandingExplanation;

package/dist/standing.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_STANDING_RULE = exports.FAMILIARITY_THRESHOLD = void 0;
+exports.assessStanding = assessStanding;
+exports.explainStanding = explainStanding;
+const observability_1 = require("./observability");
+/**
+ * The familiarity floor a peer must reach (alongside ≥3 clean successes) to earn
+ * `proven`. Equal to the proven success floor - a peer is only "proven" once you
+ * have both enough good outcomes AND enough lived history. Tunable.
+ */
+exports.FAMILIARITY_THRESHOLD = 3;
+/**
+ * ── STANDING-RULE SWAP POINT (the default tier ladder) ──
+ * The active tier rule. A fixed, transparent, count-based ladder - NOT ML:
+ *   • no basis at all          → `untested`
+ *   • failures outnumber wins  → `troubled`
+ *   • ≥3 clean wins + familiar  → `proven`
+ *   • ≥1 clean win              → `reliable`
+ *   • otherwise (mixed signal)  → `mixed`
+ * Swap this assignment (or inject a `rule` per-call) to change the ladder; e.g. a
+ * later recency/decay rule is an additive swap here, not a rebuild.
+ */
+exports.DEFAULT_STANDING_RULE = {
+    name: "count_based",
+    tier({ tally, basisCount, familiarity }) {
+        if (basisCount === 0)
+            return "untested";
+        if (tally.failed > tally.success)
+            return "troubled";
+        if (tally.success >= 3 && tally.failed === 0 && familiarity >= exports.FAMILIARITY_THRESHOLD)
+            return "proven";
+        if (tally.success >= 1 && tally.failed === 0)
+            return "reliable";
+        return "mixed";
+    },
+};
+/**
+ * Assess a peer's earned standing from the first-party outcomes you personally
+ * recorded with them. Pure + store-free: reads `agentMeta.outcomes`, FILTERS to
+ * first-party (firewall 1), tallies by result, reads `familiarity`, and maps via
+ * the (injectable) tier rule. Emits `friends.standing_assessed`. Returns a value;
+ * never writes trust (firewall 2); never produces a wire artifact (firewall 3).
+ */
+function assessStanding(record, now, rule) {
+    const outcomes = record.agentMeta?.outcomes ?? [];
+    // FIREWALL 1: first-party only. An absent `origin` is treated as first-party
+    // (the safe-merge predicate); only an explicit "imported" is excluded.
+    const firstParty = outcomes.filter((outcome) => outcome.provenance?.origin !== "imported");
+    const tally = { success: 0, partial: 0, failed: 0 };
+    for (const outcome of firstParty) {
+        tally[outcome.result] += 1;
+    }
+    const basisCount = firstParty.length;
+    const familiarity = record.agentMeta?.familiarity ?? 0;
+    const tier = (rule ?? exports.DEFAULT_STANDING_RULE).tier({ tally, basisCount, familiarity });
+    const assessedAt = (now ?? new Date()).toISOString();
+    (0, observability_1.emitNervesEvent)({
+        component: "friends",
+        event: "friends.standing_assessed",
+        message: "assessed earned standing",
+        meta: { tier, basisCount },
+    });
+    return { tier, basisCount, tally, familiarity, assessedAt };
+}
+/**
+ * Explain a peer's earned standing in words: the tier with a human `summary` +
+ * `why`, plus `advisory` notes that explicitly frame standing as input to a
+ * MANUAL trust decision (firewall 4 - never an instruction to change trust).
+ * Mirrors `describeTrustContext`'s shape.
+ */
+function explainStanding(record, now, rule) {
+    const standing = assessStanding(record, now, rule);
+    const { tier, basisCount, tally } = standing;
+    // FIREWALL 4: the guardrail. ALWAYS present - frames standing as input to a
+    // manual trust decision, never an instruction. It states, in plain words, that
+    // standing does not change the peer's trust level.
+    const guardrail = "Standing is advisory only - it does not change this peer's trust level. Adjust trust deliberately with set_trust if warranted.";
+    // Per-tier human gloss (count-based language; references the basis where it
+    // helps). Mirrors describeTrustContext's per-level branch. Every tier carries a
+    // tier-flavored `note`, paired with the always-present guardrail in `advisory`.
+    const gloss = {
+        proven: {
+            summary: "proven on our shared work",
+            why: `every one of the ${basisCount} outcomes I personally recorded with this peer succeeded, across enough shared work to be confident.`,
+            note: "A strong track record - still your call whether it warrants more trust.",
+        },
+        reliable: {
+            summary: "reliable so far",
+            why: `the ${basisCount} first-party outcome${basisCount === 1 ? "" : "s"} I recorded with this peer succeeded, with no failures yet.`,
+            note: "Promising, but on a thin basis - weigh it as one input, not a verdict.",
+        },
+        mixed: {
+            summary: "a mixed track record",
+            why: `the outcomes I recorded with this peer are mixed (${tally.success} succeeded, ${tally.partial} partial, ${tally.failed} failed) - not yet a clear signal either way.`,
+            note: "Signals are mixed; lean on direct judgement here.",
+        },
+        untested: {
+            summary: "untested - no first-party basis",
+            why: "I have not recorded any first-party outcomes with this peer, so there is nothing earned to assess.",
+            note: "No basis yet - standing offers no guidance until you have shared outcomes.",
+        },
+        troubled: {
+            summary: "troubled - failures outweigh successes",
+            why: `the outcomes I recorded with this peer skew negative (${tally.failed} failed vs ${tally.success} succeeded).`,
+            note: "Recent results are poor; weigh carefully before granting more authority.",
+        },
+    };
+    const chosen = gloss[tier];
+    return { standing, summary: chosen.summary, why: chosen.why, advisory: [chosen.note, guardrail] };
+}

package/dist/store-file.d.ts

@@ -0,0 +1,21 @@
+import type { FriendStore } from "./store";
+import type { FriendRecord } from "./types";
+export declare class FileFriendStore implements FriendStore {
+    private readonly friendsPath;
+    constructor(friendsPath: string);
+    get(id: string): Promise<FriendRecord | null>;
+    put(id: string, record: FriendRecord): Promise<void>;
+    delete(id: string): Promise<void>;
+    findByExternalId(provider: string, externalId: string, tenantId?: string): Promise<FriendRecord | null>;
+    hasAnyFriends(): Promise<boolean>;
+    listAll(): Promise<FriendRecord[]>;
+    private normalize;
+    private normalizeAgentMeta;
+    private normalizeA2AMeta;
+    /** Preserve an additive a2a.mailbox coord only when both fields are strings;
+     * otherwise drop it (absent ⇒ unchanged — the additive guarantee). */
+    private normalizeMailbox;
+    private readJson;
+    private writeJson;
+    private removeFile;
+}