@antasphere/chassis-contract 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,82 @@
+# License
+
+The Antasphere chassis
+Copyright (c) 2026 Antasphere
+
+The Antasphere chassis is made available by Antasphere, the licensor, under the "Sustainable Use License" as
+defined below. All third party components incorporated into the Antasphere chassis are licensed under the
+original license provided by the owner of the applicable component.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license
+to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes or for non-commercial or
+personal use. You may distribute the software or provide it to others only if you do so free of charge for
+non-commercial purposes. You may not alter, remove, or obscure any licensing, copyright, or other notices of
+the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to
+license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case
+subject to the limitations and conditions in this license. This license does not cover any patent claims that
+you cause to be infringed by modifications or additions to the software. If you or your company make any
+written claim that the software infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company makes such a claim, your patent
+license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these
+terms. If you modify the software, you must include in any modified copies of the software a prominent notice
+stating that you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed, and your license will
+automatically terminate. If the licensor provides you with a notice of your violation, and you cease all
+violation of this license no later than 30 days after you receive that notice, your license will be reinstated
+retroactively. However, if you violate these terms after such reinstatement, any additional violation of these
+terms will cause your license to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will
+not be liable to you for any damages arising out of these terms or the use or nature of the software, under
+any kind of legal claim.
+
+### Definitions
+
+The “licensor” is the entity offering these terms.
+
+The “software” is the software the licensor makes available under these terms, including any portion of it.
+
+“You” refers to the individual or entity agreeing to these terms.
+
+“Your company” is any legal entity, sole proprietorship, or other kind of organization that you work for, plus
+all organizations that have control over, are under the control of, or are under common control with that
+organization. Control means ownership of substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+“Your license” is the license granted to you for the software under these terms.
+
+“Use” means anything you do with the software requiring your license.
+
+“Trademark” means trademarks, service marks, and similar rights.

package/dist/define.d.ts

@@ -0,0 +1,177 @@
+import type { z } from 'zod';
+import { type ScopeSchema, type ScopeTuple } from './schemas/scope.js';
+/**
+ * The scope-dependent half of the chassis contract. Everything else in this
+ * package is a plain static export; these schemas transitively hold the
+ * tool's scope enum, so they are BUILT, once per tool, from the scopes the
+ * tool names — no module-level state, the returned object is the contract.
+ *
+ *   const { read, write, dataExport } = IDENTITY.scopes; // the tool's `ToolIdentity` value
+ *   const contract = defineChassisContract({ scopes: [read, write, dataExport] });
+ *   export const { scopeSchema, apiKeySchema, meResponseSchema } = contract;
+ *   export type Scope = ScopeOf<typeof contract>;
+ *
+ * The scopes are a TUPLE, in the order the enum publishes them: a tool with
+ * more scopes than the three parts of its identity appends them here.
+ *
+ * The route contracts over these schemas come from
+ * `defineChassisRoutes(contract, IDENTITY, copy)` on the `./routes` entry (it pulls
+ * Hono; this one stays client-safe).
+ */
+export declare function defineChassisContract<const TScopes extends ScopeTuple>(tool: {
+    scopes: TScopes;
+}): ChassisContract<TScopes[number]>;
+declare function buildChassisContract<TScope extends string>(scopeSchema: ScopeSchema<TScope>): {
+    meResponseSchema: z.ZodObject<{
+        user: z.ZodObject<{
+            id: z.ZodString;
+            email: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+        workspace: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            hubOrigin: z.ZodBoolean;
+            look: z.ZodObject<{
+                theme: z.ZodNullable<z.ZodString>;
+                pattern: z.ZodNullable<z.ZodString>;
+                field: z.ZodNullable<z.ZodNumber>;
+                grain: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        role: z.ZodNullable<z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            member: "member";
+        }>>;
+        origin: z.ZodNullable<z.ZodEnum<{
+            local: "local";
+            hub: "hub";
+            guest: "guest";
+        }>>;
+        via: z.ZodEnum<{
+            session: "session";
+            api_key: "api_key";
+            oauth: "oauth";
+        }>;
+        scopes: z.ZodNullable<z.ZodArray<ScopeSchema<TScope>>>;
+        apiKeyExpiresAt: z.ZodNullable<z.ZodString>;
+        workspaces: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            role: z.ZodEnum<{
+                owner: "owner";
+                admin: "admin";
+                member: "member";
+            }>;
+            hubOrigin: z.ZodBoolean;
+            centralAccountId: z.ZodNullable<z.ZodString>;
+            look: z.ZodObject<{
+                theme: z.ZodNullable<z.ZodString>;
+                pattern: z.ZodNullable<z.ZodString>;
+                field: z.ZodNullable<z.ZodNumber>;
+                grain: z.ZodNullable<z.ZodNumber>;
+            }, z.core.$strip>;
+            suspended: z.ZodBoolean;
+            default: z.ZodBoolean;
+        }, z.core.$strip>>;
+        activeWorkspaceId: z.ZodNullable<z.ZodString>;
+        hubManageUrl: z.ZodNullable<z.ZodString>;
+        canCreateWorkspace: z.ZodBoolean;
+        firstRunPending: z.ZodOptional<z.ZodBoolean>;
+        ssoOnly: z.ZodOptional<z.ZodBoolean>;
+        hubDenied: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>>;
+        hubNoAccessUrl: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    cliAuthCompletedSchema: z.ZodObject<{
+        key: z.ZodString;
+        apiKey: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            keyId: z.ZodString;
+            scopes: z.ZodArray<ScopeSchema<TScope>>;
+            workspaceId: z.ZodNullable<z.ZodString>;
+            createdBy: z.ZodString;
+            createdAt: z.ZodString;
+            lastUsedAt: z.ZodNullable<z.ZodString>;
+            revokedAt: z.ZodNullable<z.ZodString>;
+            expiresAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        user: z.ZodObject<{
+            id: z.ZodString;
+            email: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+        workspaceId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    apiKeySchema: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        keyId: z.ZodString;
+        scopes: z.ZodArray<ScopeSchema<TScope>>;
+        workspaceId: z.ZodNullable<z.ZodString>;
+        createdBy: z.ZodString;
+        createdAt: z.ZodString;
+        lastUsedAt: z.ZodNullable<z.ZodString>;
+        revokedAt: z.ZodNullable<z.ZodString>;
+        expiresAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    apiKeysListSchema: z.ZodObject<{
+        apiKeys: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            keyId: z.ZodString;
+            scopes: z.ZodArray<ScopeSchema<TScope>>;
+            workspaceId: z.ZodNullable<z.ZodString>;
+            createdBy: z.ZodString;
+            createdAt: z.ZodString;
+            lastUsedAt: z.ZodNullable<z.ZodString>;
+            revokedAt: z.ZodNullable<z.ZodString>;
+            expiresAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>>;
+        nextCursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    apiKeyCreateSchema: z.ZodObject<{
+        name: z.ZodString;
+        scopes: z.ZodArray<ScopeSchema<TScope>>;
+        expiresInDays: z.ZodOptional<z.ZodNumber>;
+        workspaceId: z.ZodOptional<z.ZodUUID>;
+    }, z.core.$strip>;
+    apiKeyCreatedSchema: z.ZodObject<{
+        apiKey: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            keyId: z.ZodString;
+            scopes: z.ZodArray<ScopeSchema<TScope>>;
+            workspaceId: z.ZodNullable<z.ZodString>;
+            createdBy: z.ZodString;
+            createdAt: z.ZodString;
+            lastUsedAt: z.ZodNullable<z.ZodString>;
+            revokedAt: z.ZodNullable<z.ZodString>;
+            expiresAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strip>;
+        key: z.ZodString;
+    }, z.core.$strip>;
+    scopeSchema: ScopeSchema<TScope>;
+};
+/** The contract a tool gets for its scopes (`TScope` = the union of the scope literals). */
+export type ChassisContract<TScope extends string> = ReturnType<typeof buildChassisContract<TScope>>;
+/** The loosest reading of a contract — what the `…Of` type helpers below accept. */
+export type ChassisContractShape = {
+    [K in keyof ChassisContract<string>]: z.ZodType;
+};
+/**
+ * The inferred types of an instantiated contract, under the names their
+ * schemas have always had: `type Scope = ScopeOf<typeof contract>`.
+ */
+export type ScopeOf<C extends Pick<ChassisContractShape, 'scopeSchema'>> = z.infer<C['scopeSchema']>;
+export type ApiKeyInfoOf<C extends Pick<ChassisContractShape, 'apiKeySchema'>> = z.infer<C['apiKeySchema']>;
+export type ApiKeyCreateOf<C extends Pick<ChassisContractShape, 'apiKeyCreateSchema'>> = z.infer<C['apiKeyCreateSchema']>;
+export type ApiKeyCreatedOf<C extends Pick<ChassisContractShape, 'apiKeyCreatedSchema'>> = z.infer<C['apiKeyCreatedSchema']>;
+export type CliAuthCompletedOf<C extends Pick<ChassisContractShape, 'cliAuthCompletedSchema'>> = z.infer<C['cliAuthCompletedSchema']>;
+export type MeResponseOf<C extends Pick<ChassisContractShape, 'meResponseSchema'>> = z.infer<C['meResponseSchema']>;
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAI7B,OAAO,EAAqB,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAE1F;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,OAAO,SAAS,UAAU,EAAE,IAAI,EAAE;IAC5E,MAAM,EAAE,OAAO,CAAC;CACjB,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAEnC;AAED,iBAAS,oBAAoB,CAAC,MAAM,SAAS,MAAM,EAAE,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQpF;AAED,4FAA4F;AAC5F,MAAM,MAAM,eAAe,CAAC,MAAM,SAAS,MAAM,IAAI,UAAU,CAAC,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;AAErG,oFAAoF;AACpF,MAAM,MAAM,oBAAoB,GAAG;KAAG,CAAC,IAAI,MAAM,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO;CAAE,CAAC;AAEvF;;;GAGG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,IAAI,CAAC,oBAAoB,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC;AACrG,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,IAAI,CAAC,oBAAoB,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;AAC5G,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,IAAI,CAAC,oBAAoB,EAAE,oBAAoB,CAAC,IAAI,CAAC,CAAC,KAAK,CAC9F,CAAC,CAAC,oBAAoB,CAAC,CACxB,CAAC;AACF,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,IAAI,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC,KAAK,CAChG,CAAC,CAAC,qBAAqB,CAAC,CACzB,CAAC;AACF,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,IAAI,CAAC,oBAAoB,EAAE,wBAAwB,CAAC,IAAI,CAAC,CAAC,KAAK,CACtG,CAAC,CAAC,wBAAwB,CAAC,CAC5B,CAAC;AACF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,IAAI,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC,KAAK,CAC1F,CAAC,CAAC,kBAAkB,CAAC,CACtB,CAAC"}

package/dist/define.js

@@ -0,0 +1,35 @@
+import { defineApiKeySchemas } from './schemas/api-keys.js';
+import { defineCliAuthSchemas } from './schemas/cli-auth.js';
+import { defineMeSchemas } from './schemas/me.js';
+import { defineScopeSchema } from './schemas/scope.js';
+/**
+ * The scope-dependent half of the chassis contract. Everything else in this
+ * package is a plain static export; these schemas transitively hold the
+ * tool's scope enum, so they are BUILT, once per tool, from the scopes the
+ * tool names — no module-level state, the returned object is the contract.
+ *
+ *   const { read, write, dataExport } = IDENTITY.scopes; // the tool's `ToolIdentity` value
+ *   const contract = defineChassisContract({ scopes: [read, write, dataExport] });
+ *   export const { scopeSchema, apiKeySchema, meResponseSchema } = contract;
+ *   export type Scope = ScopeOf<typeof contract>;
+ *
+ * The scopes are a TUPLE, in the order the enum publishes them: a tool with
+ * more scopes than the three parts of its identity appends them here.
+ *
+ * The route contracts over these schemas come from
+ * `defineChassisRoutes(contract, IDENTITY, copy)` on the `./routes` entry (it pulls
+ * Hono; this one stays client-safe).
+ */
+export function defineChassisContract(tool) {
+    return buildChassisContract(defineScopeSchema(tool.scopes));
+}
+function buildChassisContract(scopeSchema) {
+    const apiKeys = defineApiKeySchemas(scopeSchema);
+    return {
+        scopeSchema,
+        ...apiKeys,
+        ...defineCliAuthSchemas(apiKeys.apiKeySchema),
+        ...defineMeSchemas(scopeSchema)
+    };
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAqC,MAAM,oBAAoB,CAAC;AAE1F;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CAAmC,IAEvE;IACC,OAAO,oBAAoB,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,oBAAoB,CAAwB,WAAgC;IACnF,MAAM,OAAO,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACjD,OAAO;QACL,WAAW;QACX,GAAG,OAAO;QACV,GAAG,oBAAoB,CAAC,OAAO,CAAC,YAAY,CAAC;QAC7C,GAAG,eAAe,CAAC,WAAW,CAAC;KAChC,CAAC;AACJ,CAAC"}

package/dist/entitlements.d.ts

@@ -0,0 +1,265 @@
+import { z } from 'zod';
+import { type BillingPlan } from '@antasphere/contract';
+import type { HeaderReader, Principal } from './seams.js';
+/**
+ * The billing rail's declaration layer (the pay-per-use billing rail spec,
+ * §7 and §8b): a route says ONCE, next to its contract, what it meters, which
+ * limit it checks and which feature it needs. One chassis middleware reads
+ * the declaration and enforces it for every client of `/api/v1` at once (the
+ * dashboard, the CLI and the MCP tools are all HTTP clients of it), and a
+ * handler never checks or emits by hand.
+ *
+ * Client-safe on purpose: no Hono here. A route is referenced by its
+ * `{ method, path }` as the OpenAPI helper spells it (`{id}` params), so the
+ * tool's contract builds the registry from its route objects and the SDK can
+ * read the same declarations without pulling the server.
+ */
+export { BILLING_PLANS, USAGE_CHECK_REASONS, USAGE_EVENT_MAX_FUTURE_MS, USAGE_EVENT_MAX_PAST_MS, USAGE_EVENTS_BATCH_MAX, USAGE_REJECT_REASONS, USAGE_ROUTE_ERRORS, USAGE_WRITE_SCOPE, usageCheckRequestSchema, usageCheckSchema, usageEventOccurrenceIssue, usageEventResultSchema, usageEventSchema, usageEventsBatchSchema, usageIngestResultSchema, usageRejectReasonSchema } from '@antasphere/contract';
+export type { UsageCheck, UsageCheckReason, UsageCheckRequest, UsageEventResult, UsageEventsBatch, UsageIngestResult, UsageRejectReason, UsageRouteError } from '@antasphere/contract';
+/**
+ * The plan tiers, a CLOSED enum the hub owns (`BILLING_PLANS` in
+ * `@antasphere/contract`), under the chassis's own names (§8b): `free` is the
+ * default with no subscription; `pro` is the paid plan. "Enterprise" is not
+ * a tier but a per-account override the hub serves.
+ */
+export declare const ENTITLEMENT_TIERS: readonly ["free", "pro"];
+export type EntitlementTier = BillingPlan;
+export declare const entitlementTierSchema: z.ZodEnum<{
+    free: "free";
+    pro: "pro";
+}>;
+/** The wire code of a credit refusal (§7 step 4), and its `details`. */
+export declare const ENTITLEMENT_DENIED = "entitlement_denied";
+export interface EntitlementDeniedDetails {
+    /** The price of this action, in credits. */
+    credits: number;
+    /** The organization's balance, in credits. */
+    balance: number;
+    /** The hub's billing page for the organization: where a human adds credits. */
+    topUpUrl: string;
+}
+/**
+ * What a declaration's functions see: the request as the chassis reads it.
+ * `audit` is present only AFTER the handler ran (the emit), carrying what the
+ * handler recorded for its audit row — the place a stored size or a created
+ * resource id lives.
+ */
+export interface EntitlementRequest {
+    method: string;
+    path: string;
+    headers: HeaderReader;
+    /** Route params by name (`{id}` → its value). */
+    params: Record<string, string>;
+    principal: Principal | null;
+    /**
+     * The parsed JSON body of the request, read once and shared with the
+     * handler's own validation (the server caches the parse); `undefined`
+     * when the request carries none or it does not parse (the route's
+     * validator then answers 400 itself). A count limit or a conditional
+     * feature reads what the request asks for here (PRDCT-2702): the mint
+     * of a share link with a password, the address an invitation names.
+     */
+    body: () => Promise<unknown>;
+    audit?: {
+        action: string;
+        resourceType: string;
+        resourceId?: string;
+        metadata?: Record<string, unknown>;
+    } | undefined;
+}
+/**
+ * Who pays and who is reported (§8): the organization's account pays, the
+ * user is reported. The default actor is the principal; a route on an
+ * anonymous surface resolves its resource's owner here instead (share token
+ * → deck → owner → the owner's workspace and account) — the viewer is never
+ * identified.
+ */
+export interface ActorRef {
+    /** The reported user, or null when the actor is a resource owner the tool could not name. */
+    userId: string | null;
+    workspaceId: string;
+    /** The paying account (the workspace's central account id); absent = unmetered (oss, or a cloud-local workspace). */
+    accountRef?: string | undefined;
+}
+/**
+ * The actor of a request when it is not the principal: the owner of a
+ * resource reached anonymously (a form response through a share link), or
+ * the workspace a public door opens (an invitation accepted, a collaborator
+ * grant claimed). Resolves null to leave the route to its own handling.
+ */
+export type ActorHook = (ctx: EntitlementRequest) => Promise<ActorRef | null> | ActorRef | null;
+export interface MeterDeclaration {
+    /** The action key, namespaced by the tool's price book (`things.publish`). */
+    key: string;
+    /** The unit the price is per (`call`, `bytes`, `items`). */
+    unit: string;
+    /** The quantity of this request; default 1. Called before the handler (the check) and after it (the emit, with `audit` set). */
+    quantity?: (ctx: EntitlementRequest) => number;
+    /** The actor when it is not the principal (the owner of a resource reached anonymously). */
+    actor?: ActorHook;
+}
+export interface LimitDeclaration {
+    /** The limit key (`things.maxBytes`), declared with its per-tier values in the tool's `entitlements` slot. */
+    key: string;
+    /**
+     * The value this request observes, compared against the tier's value; over
+     * it is a plan refusal. A SIZE limit reads the declared length
+     * (`declaredContentLength`, synchronous: the gate then also demands a
+     * Content-Length on a metered account). A COUNT limit (PRDCT-2702) may be
+     * asynchronous and read the body and the tool's own tables: it returns the
+     * count AFTER this action (the resource's things plus this one), so
+     * `observed > max` is the refusal, and `null` when there is nothing to
+     * judge (the resource does not resolve, the caller may not see it): the
+     * gate then lets the route answer on its own.
+     */
+    value: (ctx: EntitlementRequest) => number | null | Promise<number | null>;
+}
+/**
+ * A feature a route needs, with an optional condition on the request
+ * (PRDCT-2702): a route that creates a thing needs `things.premium` only
+ * when the body asks for the premium option, so a declaration on the route
+ * refuses the act and never the route. Absent `when`, the whole route needs
+ * the feature.
+ */
+export interface FeatureDeclaration {
+    key: string;
+    when?: (ctx: EntitlementRequest) => boolean | Promise<boolean>;
+}
+export interface RouteEntitlement {
+    meter?: MeterDeclaration | undefined;
+    limit?: LimitDeclaration | undefined;
+    /** A feature key (`things.premium`), declared with its per-tier switch in the tool's `entitlements` slot, or the key with a condition. */
+    feature?: string | FeatureDeclaration | undefined;
+    /**
+     * The actor of a route that meters nothing but checks a limit or a feature
+     * on a PUBLIC door (no principal): the workspace the door opens pays and is
+     * judged. A meter's own `actor` serves the same purpose on a metered route;
+     * this one covers the limit-only shape. Either makes the route a viewer's
+     * surface: every refusal to it is one neutral sentence.
+     */
+    actor?: ActorHook | undefined;
+}
+/** The key of a route's feature declaration, whichever shape it uses; null when none. */
+export declare function featureKeyOf(entry: RouteEntitlement): string | null;
+/** The actor hook of a route, the entry's own or its meter's; null when the principal is the actor. */
+export declare function actorHookOf(entry: RouteEntitlement): ActorHook | null;
+/** A route as the contract spells it: the OpenAPI method and the `{param}` path. */
+export interface RouteRef {
+    method: string;
+    path: string;
+}
+export interface RouteEntitlementEntry extends RouteEntitlement {
+    route: RouteRef;
+}
+/** `METHOD /path` — the registry key of a route. */
+export declare function routeEntitlementKey(route: RouteRef): string;
+export type RouteEntitlementDeclarations = ReadonlyMap<string, RouteEntitlementEntry>;
+/**
+ * Build the registry from the tool's route objects. One entry per route: a
+ * second declaration of the same route throws at module load, so a typo or a
+ * copy cannot silently double or replace a price.
+ */
+export declare function declareRouteEntitlements(entries: ReadonlyArray<RouteEntitlementEntry>): RouteEntitlementDeclarations;
+/** The declared body size of a request (its `Content-Length`), 0 when absent or malformed. */
+export declare function declaredContentLength(ctx: EntitlementRequest): number;
+/**
+ * The stored size a handler recorded in its audit metadata (`sizeBytes`),
+ * falling back to the declared body size before the handler ran. The check
+ * sees the declared size, the emit sees the bytes that were actually kept.
+ */
+export declare function auditedSizeBytes(ctx: EntitlementRequest): number;
+/**
+ * A priced action: the default the hub seeds its price book from (§7); the
+ * hub's rows win afterwards. `creditsPerUnit` credits buy `per` units of
+ * `unit` (`per` defaults to 1): an action metered in bytes and priced per
+ * mebibyte declares `{ creditsPerUnit: 5, unit: 'bytes', per: 1048576 }`,
+ * so the meter stays exact, the price reads as the seed table says it, and
+ * the two agree by construction (PRDCT-2627: the boot refuses a route whose
+ * meter unit differs from its action's). The hub prices an event as
+ * `creditsPerUnit × quantity / per`; rounding a fraction of a credit is the
+ * hub's rule, not the tool's.
+ */
+export declare const entitlementActionSchema: z.ZodObject<{
+    key: z.ZodString;
+    creditsPerUnit: z.ZodNumber;
+    unit: z.ZodString;
+    per: z.ZodOptional<z.ZodNumber>;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type EntitlementAction = z.infer<typeof entitlementActionSchema>;
+/**
+ * The credits an action declares for a quantity: `creditsPerUnit × quantity
+ * / per`, exact (a fraction is the hub's to round). A test pins the seed
+ * values with it, so a unit slip (5 per byte where 5 per MB was meant)
+ * fails before the price book is seeded from discovery.
+ */
+export declare function declaredCredits(action: Pick<EntitlementAction, 'creditsPerUnit' | 'per'>, quantity: number): number;
+/** A limit's value per tier plus the oss value (the operator's own knob); null = unlimited. */
+export declare const tierLimitSchema: z.ZodObject<{
+    oss: z.ZodNullable<z.ZodNumber>;
+    free: z.ZodNullable<z.ZodNumber>;
+    pro: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type TierLimit = z.infer<typeof tierLimitSchema>;
+/** A feature's switch per tier (oss has every feature: a self-hosted instance knows no plan). */
+export declare const tierFeatureSchema: z.ZodObject<{
+    free: z.ZodBoolean;
+    pro: z.ZodBoolean;
+}, z.core.$strip>;
+export type TierFeature = z.infer<typeof tierFeatureSchema>;
+export declare const toolEntitlementsSchema: z.ZodObject<{
+    actions: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        creditsPerUnit: z.ZodNumber;
+        unit: z.ZodString;
+        per: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodString;
+    }, z.core.$strip>>;
+    limits: z.ZodRecord<z.ZodString, z.ZodObject<{
+        oss: z.ZodNullable<z.ZodNumber>;
+        free: z.ZodNullable<z.ZodNumber>;
+        pro: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    features: z.ZodRecord<z.ZodString, z.ZodObject<{
+        free: z.ZodBoolean;
+        pro: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ToolEntitlements = z.infer<typeof toolEntitlementsSchema>;
+/**
+ * The hub's answer to `GET /usage/entitlements?accountRef=` (§5): the hub's
+ * `usageEntitlementsSchema` (PRDCT-2636), the hub's own shape in
+ * snapshot (PRDCT-2677). The account's
+ * plan, resolved from the tier's defaults and the account's overrides; in
+ * phase 1 `limits` and `features` are empty and the tool's own declared
+ * values fill the numbers. A limit's value is a number or a boolean: the
+ * hub may switch a numeric limit off or on per account (`true` = unlimited,
+ * `false` = nothing allowed; `profiles.ts` resolves it so). Since phase 2
+ * (PRDCT-2663) the hub serves its real rows — every limit key it holds for
+ * the calling tool and the features on for the account — and `upgradeUrl`,
+ * its upgrade page for the organization carrying `org`, `tool` and `plan`;
+ * the chassis appends `&key=<key>&requiredPlan=<tier>` at refusal time.
+ * Required: every hub since 0.11.0 sends it.
+ */
+export declare const entitlementProfileSchema: z.ZodObject<{
+    accountRef: z.ZodUUID;
+    plan: z.ZodEnum<{
+        free: "free";
+        pro: "pro";
+    }>;
+    planUntil: z.ZodNullable<z.ZodString>;
+    limits: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNumber, z.ZodBoolean]>>;
+    features: z.ZodArray<z.ZodString>;
+    upgradeUrl: z.ZodString;
+}, z.core.$strip>;
+export type EntitlementProfile = z.infer<typeof entitlementProfileSchema>;
+/** The wire code of a plan refusal, and its `details` (§7 step 2). */
+export declare const PLAN_REQUIRED = "plan_required";
+export interface PlanRequiredDetails {
+    key: string;
+    plan: EntitlementTier;
+    /** The first tier that allows the action, or null when none does. */
+    requiredPlan: EntitlementTier | null;
+    upgradeUrl: string;
+}
+//# sourceMappingURL=entitlements.d.ts.map

package/dist/entitlements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlements.d.ts","sourceRoot":"","sources":["../src/entitlements.ts"],"names":[],"mappings":"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"}