@oxy.so/contracts 4.16.0 → 4.21.0

package/dist/esm/accountGraph.js

@@ -10,239 +10,12 @@ import { z } from 'zod';
 import { avatarCharacterSchema } from './avatarCharacter.js';
 import { ORGANIZATION_TYPES, ORGANIZATION_NAME_MAX_LENGTH, organizationNameSchema, } from './organizations.js';
 import { usernameSchema, usernameSchemaForAccountKind } from './username.js';
-/**
- * The union is spelled out above and the array proves coverage BOTH ways
- * (`satisfies` here, the `Gap` alias below) — the same shape this package's
- * `ACCOUNT_CATEGORY_IDS` / `TRUST_TIERS` pairs use, and the one
- * `db/schema/users.ts` mirrors to keep the `users_kind_check` CHECK honest.
- *
- * Deriving the union from the array instead would cost nothing here and be paid
- * by consumers: `kind` travels into `@oxy.so/services` on every device-directory
- * context (`deviceContextSchema.kind` → `DeviceContext` → the switcher rows),
- * and an indexed-access type is materially more expensive to check there than a
- * literal union.
- */
-export const ACCOUNT_KINDS = [
-    'personal',
-    'organization',
-    'project',
-    'bot',
-    'channel',
-];
+// The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
+// it is re-exported here so the root entry is unchanged.
+import { ACCOUNT_KINDS, CHILD_ACCOUNT_KINDS, ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, } from './client/accountGraph.js';
+export { ACCOUNT_KINDS, CHILD_ACCOUNT_KINDS, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, isAccountKind, ACCOUNT_CATEGORY_IDS, RETIRED_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, SELECTABLE_ACCOUNT_CATEGORY_IDS, newlyAddedRetiredCategories, MAX_ACCOUNT_CATEGORIES, ACCOUNT_CATEGORY_KINDS, kindAcceptsAccountCategories, } from './client/accountGraph.js';
 export const accountKindSchema = z.enum(ACCOUNT_KINDS);
-export const CHILD_ACCOUNT_KINDS = [
-    'organization',
-    'project',
-    'bot',
-    'channel',
-];
 export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
-/**
- * Whether an account of this kind may be the SUBJECT OF A DELEGATION — an
- * application acting as it on some person's authority. `POST /internal/accounts/
- * :id/service-switch` and the OAuth delegated subject both gate on this.
- *
- * It is NOT the question an account switcher asks. See
- * {@link isOperatorSwitchTargetKind}, and the note below on why the difference
- * is `bot`.
- *
- * Two kinds are refused, for opposite reasons:
- *
- *  - `personal` is a human login, so assuming it would be impersonation.
- *  - `channel` is a CONTENT identity, not an operating one. A channel exists so
- *    that posts can be authored BY it; it is never a seat anybody occupies. Its
- *    operators act on it through their own membership, and an application
- *    publishes to it with its own credential. Refusing act-as is what makes
- *    "no login, ever" structural rather than incidental: no session can be
- *    minted whose subject is a channel, so no bearer exists that could add an
- *    auth method to one (every auth-method write resolves its target from the
- *    authenticated subject, never from a parameter).
- *
- * 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 function isDelegatedActAsEligibleKind(kind) {
-    return kind === 'organization' || kind === 'project' || kind === 'bot';
-}
-/**
- * Whether a PERSON may switch into an account of this kind — become it, in an
- * account switcher, for the rest of their session.
- *
- * ## Why this is not the same question as {@link isDelegatedActAsEligibleKind}
- *
- * 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 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
- * device, next to their personal login — which is precisely what happened: a
- * `bot` account held a live session on a person's device, offered to them by a
- * switcher that had asked the delegation question by mistake.
- *
- * `channel` is refused here as well, for the reason set out above, and
- * `personal` because assuming somebody else's login is impersonation.
- *
- * ## This is the narrower predicate, deliberately
- *
- * Everything a person may become, a service may also act as; the reverse does
- * not hold. A caller that is unsure which question it is asking wants THIS one:
- * being wrong here withholds an affordance, while being wrong the other way
- * hands out a seat.
- */
-export function isOperatorSwitchTargetKind(kind) {
-    return kind === 'organization' || kind === 'project';
-}
-/**
- * Narrow an unknown value to an {@link AccountKind}.
- *
- * The user-DTO serializers read from structurally-permissive `unknown` sources
- * (a Drizzle row, a raw document, an already-formatted object), so each one
- * would otherwise hand-roll this check and they would drift on what counts.
- */
-export function isAccountKind(value) {
-    return typeof value === 'string' && ACCOUNT_KINDS.includes(value);
-}
-// ===========================================================================
-// Account categories
-//
-// Four rules govern this taxonomy. Each one is here because the obvious
-// alternative fails silently rather than loudly.
-//
-// 1. AN ID IS AN OPAQUE, IMMUTABLE SLUG — the LABEL is not stored anywhere.
-//    Every value below is an identifier that no rename may ever change. The
-//    human-readable label lives in each client's own translation catalogue,
-//    keyed by the id. Re-labelling `agency` from "Real estate agency" to
-//    "Agency" is therefore a one-line locale edit that touches no row; moving
-//    the label into the column or the DTO would make the same edit a data
-//    migration, and would pin every reader to the language of whoever chose it.
-//
-// 2. THE PRIMARY CATEGORY IS THE FIRST ELEMENT of an ordered list. Not a
-//    separate flag, and not a second field: a flag admits two primaries and
-//    admits none, and ordering makes both unrepresentable. The cost is that
-//    ORDER IS DATA — anything that re-serializes, sorts or de-duplicates this
-//    list can change which category is primary without erroring, so no layer
-//    between the column and the client may reorder it.
-//
-// 3. THE VOCABULARY IS APPEND-ONLY. `ACCOUNT_CATEGORY_IDS` may gain ids and may
-//    never lose one, because rows already carry the ids it holds. Withdrawing a
-//    category means listing it in {@link RETIRED_ACCOUNT_CATEGORY_IDS}, which
-//    removes it from the picker while leaving it readable and re-writable. The
-//    database enforces the same asymmetry: its CHECK is re-evaluated on EVERY
-//    update to a row, so narrowing the allowed set makes an unrelated write —
-//    saving a bio — fail on any account that had picked the withdrawn value.
-//    Measured on a real Postgres, `NOT VALID` included; it does not help.
-//
-// 4. THE SET IS CLOSED. An id nobody can validate is an id no client can render:
-//    the label comes from a translation key derived from the id, so an invented
-//    value paints as a blank or a raw slug in every app at once. Closing it also
-//    costs nothing that rule 3 does not already charge — adding a category needs
-//    a migration to widen the CHECK whether or not the enum exists, so an open
-//    list would buy back no work, only the validation.
-// ===========================================================================
-/**
- * Every account category, by stable id.
- *
- * Grouped by comment for readability only; the storage, the wire and the picker
- * all treat this as one flat list. `other` is the escape hatch for an account
- * that fits nothing here.
- *
- * TO ADD ONE: append an id (lowercase ASCII, `snake_case`) here, publish
- * `@oxy.so/contracts`, then ship a migration that widens
- * `users_account_categories_check` — never edit an existing migration — and add
- * an `accounts.accountCategory.<id>` label to each client's locales.
- *
- * TO WITHDRAW ONE: leave the id here and add it to
- * {@link RETIRED_ACCOUNT_CATEGORY_IDS}. See rule 3 above.
- */
-export const ACCOUNT_CATEGORY_IDS = [
-    // ---- media & public information -----------------------------------------
-    'news',
-    'politics',
-    // ---- business & economy --------------------------------------------------
-    'business',
-    'startup',
-    'finance',
-    'crypto',
-    'marketplace',
-    'retail',
-    // The four ids the single-valued `organizationCategory` field used to hold,
-    // carried forward VERBATIM. Their labels may be rewritten freely; their ids
-    // may not, because live rows hold them.
-    'real_estate',
-    'agency',
-    'landlord',
-    'cooperative',
-    'architecture',
-    // ---- technology ----------------------------------------------------------
-    'technology',
-    'software',
-    'ai',
-    'security',
-    'automation',
-    // ---- knowledge -----------------------------------------------------------
-    'science',
-    'education',
-    'books',
-    // ---- health --------------------------------------------------------------
-    'health',
-    'fitness',
-    // ---- sport & play --------------------------------------------------------
-    'sports',
-    'gaming',
-    // ---- culture & entertainment ---------------------------------------------
-    //
-    // There is deliberately NO generic `entertainment` here, and re-adding one is
-    // a regression rather than a gap. It is the only id this list ever carried
-    // that was dominated by its own specifics — `film`, `music`, `gaming` and
-    // `comedy` all exist — and a generic drawer sitting beside its four
-    // concretions collects the lazy pick, which degrades the data for all four at
-    // once: the accounts that would have said `film` say `entertainment` instead,
-    // and `film` stops meaning what it meant.
-    //
-    // The other overlaps in this vocabulary are NOT the same case and must not be
-    // merged on this reasoning: `sports`/`fitness`, `art`/`photography`,
-    // `business`/`startup`, `finance`/`crypto`, `home_garden`/`diy` and
-    // `technology`/`software`/`security` are genuinely different audiences, and
-    // with a cap of four the granularity is cheap.
-    'music',
-    'film',
-    'podcast',
-    'art',
-    'photography',
-    'comedy',
-    // ---- everyday life -------------------------------------------------------
-    'food',
-    'travel',
-    'fashion',
-    'home_garden',
-    'diy',
-    'automotive',
-    'animals',
-    'family',
-    // ---- society -------------------------------------------------------------
-    'nonprofit',
-    'government',
-    'community',
-    'activism',
-    'environment',
-    'religion',
-    // ---- fallback ------------------------------------------------------------
-    'other',
-];
 /**
  * Accepts EVERY id, withdrawn ones included — see rule 3.
  *
@@ -252,59 +25,6 @@ export const ACCOUNT_CATEGORY_IDS = [
  * nullable `bio` / `avatar` fix addressed, wearing a different hat.
  */
 export const accountCategoryIdSchema = z.enum(ACCOUNT_CATEGORY_IDS);
-/**
- * Ids withdrawn from the picker. Empty today.
- *
- * A withdrawn id keeps working everywhere it is already stored: it validates,
- * it survives a round-trip save, it still renders from its label key, and it
- * stays PRIMARY if it was primary. Nothing rewrites a stored list — a read-time
- * or migration-time demotion would silently replace a choice its owner made,
- * which is precisely what stable ids exist to prevent. The owner drops it on
- * their next edit; until then it is honoured.
- *
- * What withdrawal changes is only this: the id leaves
- * {@link SELECTABLE_ACCOUNT_CATEGORY_IDS}, so no picker offers it, and
- * {@link newlyAddedRetiredCategories} refuses to let a write ADD it to an
- * account that did not already have it.
- */
-export const RETIRED_ACCOUNT_CATEGORY_IDS = [];
-/** Whether a category may still be OFFERED. A stored one is readable either way. */
-export function isSelectableAccountCategoryId(id) {
-    return !RETIRED_ACCOUNT_CATEGORY_IDS.includes(id);
-}
-/** The ids a picker may offer, in declaration order. */
-export const SELECTABLE_ACCOUNT_CATEGORY_IDS = ACCOUNT_CATEGORY_IDS.filter(isSelectableAccountCategoryId);
-/**
- * Which of `next` are withdrawn ids the account did not already carry — i.e.
- * the ones a write must be refused for.
- *
- * `retired` is a parameter rather than a module read so the rule can be
- * exercised against a non-empty set while the production one is empty; a test
- * over `RETIRED_ACCOUNT_CATEGORY_IDS` alone would pass vacuously today and stay
- * passing if the rule were deleted.
- */
-export function newlyAddedRetiredCategories(next, previous, retired) {
-    return next.filter((id) => retired.includes(id) && !previous.includes(id));
-}
-/**
- * How many categories one account may carry.
- *
- * Four, not "as many as you like". Three reasons, in the order they bind:
- *
- *  - The primary has to MEAN something. At ten categories the first element
- *    reads as a sort artifact rather than a choice, and rule 2 above is the
- *    entire mechanism by which a primary exists.
- *  - The profile RENDERS them as a row of chips; four labels of this length is
- *    what fits a phone-width profile header before the row wraps or truncates.
- *  - Four is enough to place a genuinely compound account without a tag cloud:
- *    a housing cooperative that is also a non-profit serving a local community
- *    spends `cooperative`, `nonprofit`, `community`, `real_estate` — and is the
- *    most compound real example in the ecosystem.
- *
- * One constant, read by the wire schema, the database CHECK and the picker, so
- * changing it is one edit plus a migration.
- */
-export const MAX_ACCOUNT_CATEGORIES = 4;
 /**
  * An account's categories on the wire. ORDER IS MEANINGFUL — index 0 is the
  * primary (rule 2).
@@ -331,31 +51,6 @@ export const accountCategoriesSchema = z
         seen.add(id);
     });
 });
-/**
- * Kinds that may carry categories: every kind EXCEPT `personal`.
- *
- * A person has interests, not a sector — and their interests are not a
- * classification anybody else gets to read off their profile. Spelled out
- * positively, like {@link isDelegatedActAsEligibleKind} and for the same reason: a `kind
- * !== 'personal'` test silently admits every kind invented after it was
- * written, whereas this list forces whoever adds one to decide.
- */
-export const ACCOUNT_CATEGORY_KINDS = [
-    'organization',
-    'project',
-    'bot',
-    'channel',
-];
-/**
- * Whether an account of this kind may carry categories.
- *
- * The API refuses the write and the `users_account_categories_kind_check`
- * constraint makes it unrepresentable; both derive from
- * {@link ACCOUNT_CATEGORY_KINDS}, so they cannot disagree.
- */
-export function kindAcceptsAccountCategories(kind) {
-    return ACCOUNT_CATEGORY_KINDS.includes(kind ?? '');
-}
 /**
  * An account's name on the create/update wire.
  *

package/dist/esm/agency.js

@@ -140,6 +140,35 @@ export const delegationGrantSchema = z
     updatedAt: z.string().datetime(),
 })
     .strict();
+/**
+ * The two levels an owner publishes for whoever uses their agent (ADR 0042):
+ * "Ver" and "Ver y actuar". A ceiling never says `draft` or `execute_on_request`:
+ * an agent is either allowed to act on its own or not at all, and nothing ever
+ * asks the person for approval.
+ */
+export const AGENT_REQUESTER_CEILING_AUTONOMY = ['read_only', 'autonomous'];
+/** What an agent may do in one app for whoever uses it; written by an operator of the bot. */
+export const agentRequesterCeilingWriteSchema = z
+    .object({
+    capabilityPackages: z.array(capabilityPackageSchema),
+    capabilities: z.array(identifierSchema).default([]),
+    toolOverrides: z.array(toolGrantOverrideSchema).default([]),
+    limits: z.array(grantLimitSchema).default([]),
+    maximumAutonomy: z.enum(AGENT_REQUESTER_CEILING_AUTONOMY),
+})
+    .strict();
+export const agentRequesterCeilingSchema = agentRequesterCeilingWriteSchema
+    .extend({
+    id: identifierSchema,
+    agentAccountId: identifierSchema,
+    appId: identifierSchema,
+    catalog: capabilityCatalogBindingSchema,
+    version: z.number().int().positive(),
+    revokedAt: z.string().datetime().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+})
+    .strict();
 export const automationTriggerSchema = z.discriminatedUnion('type', [
     z.object({ type: z.literal('manual') }).strict(),
     z
@@ -201,6 +230,8 @@ export const capabilityTicketClaimsSchema = z
     /** Signed only for callers that explicitly requested a pinned catalogue. */
     catalog: capabilityCatalogBindingSchema.optional(),
     grantId: identifierSchema.optional(),
+    /** The owner's published ceiling that bounds an agent acting for a non-owner (ADR 0042). */
+    ceilingId: identifierSchema.optional(),
     requesterAccountId: identifierSchema,
     ownerAccountId: identifierSchema,
     actor: executionActorRefSchema,
@@ -239,6 +270,24 @@ export const capabilityTicketClaimsSchema = z
             message: 'requester actors require their exact principal and direct read-only authority without standing grants',
         });
     }
+    if (claims.ceilingId !== undefined) {
+        if (claims.grantId !== undefined) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['ceilingId'],
+                message: 'a ticket is bounded by either a grant or a ceiling, never both',
+            });
+        }
+        if (claims.actor.type !== 'agent' ||
+            claims.ownerAccountId !== claims.requesterAccountId ||
+            claims.resource.resourceId !== claims.resource.effectiveAccountId) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['ceilingId'],
+                message: "a ceiling bounds an agent acting on the requester's own authority at an account root",
+            });
+        }
+    }
     if (claims.exp <= claims.iat) {
         context.addIssue({
             code: z.ZodIssueCode.custom,
@@ -300,6 +349,7 @@ export const policyDecisionSchema = z
     reason: identifierSchema,
     effectiveAutonomy: autonomyLevelSchema.optional(),
     grantId: identifierSchema.optional(),
+    ceilingId: identifierSchema.optional(),
 })
     .strict();
 export const auditResultSchema = z
@@ -509,6 +559,24 @@ export const catalogEventSchema = z
     resourceTypes: z.array(identifierSchema).min(1),
 })
     .strict();
+/**
+ * A feature an agent may gate on (Alia ADR 0020 §6): the app answers whether the
+ * person may use it (`checkTool`) and, when using it costs something, spends it
+ * (`consumeTool`). Both are internal tools of the same catalogue.
+ */
+export const catalogFeatureSchema = z
+    .object({
+    key: z
+        .string()
+        .regex(/^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/, 'feature keys are dot-separated slugs')
+        .max(128),
+    description: nonEmptyStringSchema,
+    checkTool: identifierSchema,
+    consumeTool: identifierSchema.optional(),
+})
+    .strict();
+/** How a coordinator reaches the catalogue's internal tools. */
+export const CATALOG_INTERNAL_TRANSPORTS = ['http', 'mcp'];
 export const appCapabilityCatalogSchema = z
     .object({
     schemaVersion: z.literal('1'),
@@ -564,11 +632,54 @@ export const appCapabilityCatalogSchema = z
     })
         .strict()
         .optional(),
+    /**
+     * `mcp`: internal tools are served at `<internalBaseUrl>/_oxy/mcp`. Absent or
+     * `http`: each tool's `invocation` path on `internalBaseUrl`.
+     */
+    internalTransport: z.enum(CATALOG_INTERNAL_TRANSPORTS).optional(),
+    features: z.array(catalogFeatureSchema).optional(),
     tools: z.array(catalogToolSchema),
     events: z.array(catalogEventSchema),
 })
     .strict()
     .superRefine((catalog, context) => {
+    const toolsByName = new Map(catalog.tools.map((tool) => [tool.name, tool]));
+    const featureKeys = new Set();
+    for (const [index, feature] of (catalog.features ?? []).entries()) {
+        if (featureKeys.has(feature.key)) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Duplicate feature key: ${feature.key}`,
+                path: ['features', index, 'key'],
+            });
+        }
+        featureKeys.add(feature.key);
+        const check = toolsByName.get(feature.checkTool);
+        if (!check ||
+            check.effect !== 'read' ||
+            check.exposure.length !== 1 ||
+            check.exposure[0] !== 'internal') {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'checkTool must name an internal-only read tool of this catalogue',
+                path: ['features', index, 'checkTool'],
+            });
+        }
+        if (feature.consumeTool !== undefined) {
+            const consume = toolsByName.get(feature.consumeTool);
+            if (!consume ||
+                consume.effect === 'read' ||
+                consume.idempotency !== 'required' ||
+                consume.exposure.length !== 1 ||
+                consume.exposure[0] !== 'internal') {
+                context.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'consumeTool must name an internal-only effectful tool that requires idempotency keys',
+                    path: ['features', index, 'consumeTool'],
+                });
+            }
+        }
+    }
     const names = new Set();
     for (const [index, tool] of catalog.tools.entries()) {
         if (names.has(tool.name)) {

package/dist/esm/agentKeys.js

@@ -2,15 +2,10 @@
 import { z } from 'zod';
 import { reauthProofSchema } from './signIn.js';
 import { canonicalJson } from './identityProof.js';
-export const AGENT_PROOF_AUDIENCE = 'oxy-api/agent';
-export const AGENT_PROOF_TTL_MS = 60000;
-export const AGENT_PROOF_ACTIONS = [
-    'agent_signin',
-    'agent_enroll',
-    'agent_rotate',
-    'agent_recover',
-    'agent_governance',
-];
+// The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
+// it is re-exported here so the root entry is unchanged.
+import { AGENT_PROOF_AUDIENCE, AGENT_PROOF_ACTIONS } from './client/agentKeys.js';
+export { AGENT_PROOF_AUDIENCE, AGENT_PROOF_TTL_MS, AGENT_PROOF_ACTIONS, ACCOUNT_AUTH_METHODS, } from './client/agentKeys.js';
 export const agentProofClaimsSchema = z
     .object({
     version: z.literal(1),
@@ -97,7 +92,6 @@ export const agentKeyOperationResultSchema = z
     revokedMethodIds: z.array(z.string()),
 })
     .strict();
-export const ACCOUNT_AUTH_METHODS = ['identity', 'agent_key'];
 /** Public credential inventory. Never includes a proof, bearer or private key. */
 export const agentKeyListResponseSchema = z
     .object({