@oxy.so/contracts 4.8.0 → 4.9.1

package/dist/types/accountGraph.d.ts

@@ -10,11 +10,18 @@ import { z } from 'zod';
 /**
  * Account-graph classification — the ONE authority for the kind vocabulary.
  *
- * `personal` is the only kind minted by signup and the only one that carries
- * its own credentials; every other kind is a child account created under a
- * parent and operated through `account_members`. The API schema, the Drizzle
+ * `personal` is the only kind minted by signup and the only one that signs in
+ * as a device principal; every other kind is a child account created under a
+ * parent and reached through `account_members`. The API schema, the Drizzle
  * table and the SDK all derive from this list rather than restating it, so a
  * new kind is one edit here instead of four literals that can drift.
+ *
+ * The kind names what an account IS. It does not, on its own, answer who may
+ * switch into it, who may act as it, who the actor is, or anything commercial —
+ * each of those has its own predicate or contract, tabulated at the top of
+ * `accountSubject.ts`. In particular a `bot` is a COMPLETE account (issue
+ * #1520): it owns resources, holds roles, plans and a balance, receives funds
+ * and pays for itself under the same rules as a person, and is its own actor.
  */
 export type AccountKind = 'personal' | 'organization' | 'project' | 'bot' | 'channel';
 /**
@@ -65,6 +72,12 @@ export declare const childAccountKindSchema: z.ZodEnum<["organization", "project
  *
  * Consumers must gate on this predicate rather than testing `kind === 'personal'`,
  * which silently admits every kind added after it was written.
+ *
+ * Being act-as-eligible is NOT being without an identity of one's own. A bot is
+ * act-as-eligible AND its own actor (`accountKindActorNature` → `'agent'` in
+ * `accountSubject.ts`): an application acting as it on a person's authority
+ * records that person as the actor, and the bot acting with nobody operating it
+ * records the bot. Neither ever records the bot's owner in the bot's place.
  */
 export declare function isDelegatedActAsEligibleKind(kind: AccountKind | null | undefined): boolean;
 /**
@@ -76,11 +89,13 @@ export declare function isDelegatedActAsEligibleKind(kind: AccountKind | null |
  * The two differ on exactly one kind, `bot`, and that difference is the whole
  * reason both exist.
  *
- * **A bot is not something you become. It is something that operates on your
- * behalf.** Its whole purpose is to act while nobody is present: an application
- * holds a credential, names the human whose authority it borrows, and speaks as
- * the bot. That is delegation, and it is what
- * {@link isDelegatedActAsEligibleKind} admits it for.
+ * **A bot is not something you become. It is somebody of its own.** It is an
+ * agent's identity, with its own resources, roles, plan and balance, and it is
+ * the actor of what it does unoperated. A person may still act AS it on their
+ * own authority — that is delegation, recorded with the person as actor, and it
+ * is what {@link isDelegatedActAsEligibleKind} admits it for. What a person
+ * never does is occupy its seat. This is a refusal of a SEAT, not a capability
+ * restriction: nothing a bot may do depends on this predicate.
  *
  * Handing a person the bot's seat instead inverts that. It puts a human inside
  * the identity that exists to act without one, and it does so on the human's own

package/dist/types/accountSubject.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Account subject contract — what an account IS, kept apart from how it proves
+ * itself, who may become it, who may act as it, who acted, and whose money moves.
+ *
+ * `AccountKind` (`accountGraph.ts`) names the nature of an account. Five other
+ * questions are routinely asked of an account, and each has its own answer here
+ * or in `accountGraph.ts`. None of them may be answered by testing `kind`
+ * directly at a call site:
+ *
+ * | question                                  | answered by                              |
+ * |-------------------------------------------|------------------------------------------|
+ * | may a PERSON switch into it?              | `isOperatorSwitchTargetKind`             |
+ * | may someone act AS it on their authority? | `isDelegatedActAsEligibleKind`           |
+ * | who is the ACTOR when it acts unoperated? | {@link accountKindActorNature}           |
+ * | who acted, and as whom, on this request?  | {@link AccountActorChain}                |
+ * | whose money / receipt is an effect?       | {@link attributeFinancialEffect}         |
+ * | roles, resources, plan, balance, payer    | NOT kind — {@link KIND_INDEPENDENT_ACCOUNT_DIMENSIONS} |
+ *
+ * ## A bot is a complete account (issue #1520, I01)
+ *
+ * A `bot` is an AI agent's own identity. It owns resources, holds roles, has a
+ * plan, holds a balance, receives funds and pays for itself under exactly the
+ * rules a personal account does. Nothing commercial derives from it being a bot,
+ * and nothing about it requires its owner's approval merely because it is one.
+ *
+ * Two things DO differ, and both are about seats, not capability:
+ *
+ *  - a person never switches INTO a bot (`isOperatorSwitchTargetKind`): a bot is
+ *    somebody, not a seat a human occupies;
+ *  - when a bot acts with nobody operating it, the actor recorded is the BOT
+ *    ({@link accountKindActorNature} `'agent'`), never its owner.
+ */
+import { z } from 'zod';
+import type { AccountKind } from './accountGraph';
+/** Bumped when any shape in this module changes incompatibly. */
+export declare const ACCOUNT_SUBJECT_CONTRACT_VERSION: 1;
+/**
+ * Who is recorded as the ACTOR when an account of this kind acts and no other
+ * account is operating it.
+ *
+ *  - `person` — a human; a personal account is its own actor.
+ *  - `agent`  — an AI agent; a bot is its own actor (ADR 0018 `ActorRef`
+ *    `{type:'agent'}`), and audit records the bot, never the human who owns it.
+ *  - `operated` — never its own actor. An organization, project or channel only
+ *    acts through a member, and that member is the actor.
+ */
+export declare const ACCOUNT_ACTOR_NATURES: readonly ["person", "agent", "operated"];
+export type AccountActorNature = (typeof ACCOUNT_ACTOR_NATURES)[number];
+export declare const accountActorNatureSchema: z.ZodEnum<["person", "agent", "operated"]>;
+/** `null` for a value that is not an account kind. Never a guess. */
+export declare function accountKindActorNature(kind: AccountKind | null | undefined): AccountActorNature | null;
+/** Whether an account of this kind can be the actor of its own actions. */
+export declare function accountKindActsAsItself(kind: AccountKind | null | undefined): boolean;
+/**
+ * What an account's KIND never decides.
+ *
+ * There is deliberately no predicate taking a kind for any of these. A member's
+ * role grants the same permissions whatever kind the member is; a plan, a
+ * balance, the payer and the beneficiary are resolved from billing state and
+ * membership, never from `kind`. A bot and a person with the same role and plan
+ * get the same action and the same commercial treatment.
+ *
+ * Listed so a consumer can cite the rule, and so the API's static guard
+ * (`commercialTreatmentIgnoresAccountKind.test.ts`) has a single source.
+ */
+export declare const KIND_INDEPENDENT_ACCOUNT_DIMENSIONS: readonly ["roles", "resources", "plan", "balance", "payer", "beneficiary"];
+export type KindIndependentAccountDimension = (typeof KIND_INDEPENDENT_ACCOUNT_DIMENSIONS)[number];
+/**
+ * Who acted, and as whom, for one authenticated request.
+ *
+ *  - `effectiveAccountId` — the account the request speaks AS (token `sub`).
+ *  - `actorAccountId` — who actually acted (token `act.sub`): the human operating
+ *    a managed account, or the account itself when nobody operates it.
+ *  - `delegated` — exactly `actorAccountId !== effectiveAccountId`. Carried as
+ *    its own field so a consumer reads a fact instead of re-deriving it, and
+ *    refined so the two can never disagree.
+ *
+ * Produced ONLY by the session authority (Oxy's `/session/validate*`) from the
+ * session ROW. A header or an unverified token claim never produces one: that is
+ * what keeps a modified header from changing the actor.
+ */
+export declare const accountActorChainSchema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    effectiveAccountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    actorAccountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    delegated: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    effectiveAccountId: string & z.BRAND<"OxyAccountId">;
+    actorAccountId: string & z.BRAND<"OxyAccountId">;
+    delegated: boolean;
+}, {
+    schemaVersion: 1;
+    effectiveAccountId: string;
+    actorAccountId: string;
+    delegated: boolean;
+}>, {
+    schemaVersion: 1;
+    effectiveAccountId: string & z.BRAND<"OxyAccountId">;
+    actorAccountId: string & z.BRAND<"OxyAccountId">;
+    delegated: boolean;
+}, {
+    schemaVersion: 1;
+    effectiveAccountId: string;
+    actorAccountId: string;
+    delegated: boolean;
+}>;
+export type AccountActorChain = z.infer<typeof accountActorChainSchema>;
+/**
+ * Build the chain from a session's binding: its subject and the operator
+ * recorded on it (`sessions.operated_by_user_id`), if any.
+ *
+ * The one constructor, so producers cannot each invent a rule. An operator equal
+ * to the subject is not a delegation.
+ */
+export declare function accountActorChainFromSession(binding: {
+    readonly subjectAccountId: string;
+    readonly operatedByAccountId?: string | null;
+}): AccountActorChain;
+/** `debit` — the subject pays; `credit` — the subject receives. */
+export declare const FINANCIAL_EFFECT_DIRECTIONS: readonly ["debit", "credit"];
+export type FinancialEffectDirection = (typeof FINANCIAL_EFFECT_DIRECTIONS)[number];
+/**
+ * Whose money a financial effect is, and who caused it.
+ *
+ * `subjectAccountId` is the account the effect BELONGS to — the payer of a
+ * debit, the beneficiary of a credit — and it is always the EFFECTIVE account of
+ * the actor chain. Never the operator: a person paying from the bot they operate
+ * spends the bot's money, and the receipt names the bot as payer and the person
+ * as actor. Never the owner: a bot paying for itself is recorded as the bot.
+ *
+ * What this does NOT decide is which balance row FUNDS a debit. That is the
+ * billing walk's answer (ADR 0014: the account's own active profile, else its
+ * nearest ancestor's) and it is kind-independent; this contract only fixes the
+ * subject and the actor the receipt must carry. Moving money is not done here.
+ */
+export declare const financialEffectAttributionSchema: z.ZodEffects<z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    direction: z.ZodEnum<["debit", "credit"]>;
+    subjectAccountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+    actor: z.ZodEffects<z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        effectiveAccountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+        actorAccountId: z.ZodBranded<z.ZodString, "OxyAccountId">;
+        delegated: z.ZodBoolean;
+    }, "strict", z.ZodTypeAny, {
+        schemaVersion: 1;
+        effectiveAccountId: string & z.BRAND<"OxyAccountId">;
+        actorAccountId: string & z.BRAND<"OxyAccountId">;
+        delegated: boolean;
+    }, {
+        schemaVersion: 1;
+        effectiveAccountId: string;
+        actorAccountId: string;
+        delegated: boolean;
+    }>, {
+        schemaVersion: 1;
+        effectiveAccountId: string & z.BRAND<"OxyAccountId">;
+        actorAccountId: string & z.BRAND<"OxyAccountId">;
+        delegated: boolean;
+    }, {
+        schemaVersion: 1;
+        effectiveAccountId: string;
+        actorAccountId: string;
+        delegated: boolean;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    schemaVersion: 1;
+    direction: "debit" | "credit";
+    subjectAccountId: string & z.BRAND<"OxyAccountId">;
+    actor: {
+        schemaVersion: 1;
+        effectiveAccountId: string & z.BRAND<"OxyAccountId">;
+        actorAccountId: string & z.BRAND<"OxyAccountId">;
+        delegated: boolean;
+    };
+}, {
+    schemaVersion: 1;
+    direction: "debit" | "credit";
+    subjectAccountId: string;
+    actor: {
+        schemaVersion: 1;
+        effectiveAccountId: string;
+        actorAccountId: string;
+        delegated: boolean;
+    };
+}>, {
+    schemaVersion: 1;
+    direction: "debit" | "credit";
+    subjectAccountId: string & z.BRAND<"OxyAccountId">;
+    actor: {
+        schemaVersion: 1;
+        effectiveAccountId: string & z.BRAND<"OxyAccountId">;
+        actorAccountId: string & z.BRAND<"OxyAccountId">;
+        delegated: boolean;
+    };
+}, {
+    schemaVersion: 1;
+    direction: "debit" | "credit";
+    subjectAccountId: string;
+    actor: {
+        schemaVersion: 1;
+        effectiveAccountId: string;
+        actorAccountId: string;
+        delegated: boolean;
+    };
+}>;
+export type FinancialEffectAttribution = z.infer<typeof financialEffectAttributionSchema>;
+/** Attribute a payment or a receipt to the subject the actor chain speaks as. */
+export declare function attributeFinancialEffect(direction: FinancialEffectDirection, actor: AccountActorChain): FinancialEffectAttribution;