@sealant/api-contracts-next 0.40.0-next.769 → 0.40.0-next.771

package/dist/core-api/resource-domains.d.ts

@@ -15,9 +15,93 @@
  * before a handler runs. A deployment served without authentication (the development exception)
  * serves them as it serves every other route. A request body is decoded strictly: a field the contract does not declare (an
  * owner, a credential) is refused with `400` instead of being dropped.
+ *
+ * Members are the people the application lets reach the domain. A grant or a revoke carries
+ * `version`, the application's own number for its decision about this person, rising with each
+ * decision it makes (its record's revision, say). Core writes the decision only over a lower
+ * version. The same version with the same state is a repeat, answered with the member unchanged.
+ * The same version with the other state, or a lower one, is stale: `409`, carrying the decision
+ * that stands. So a delayed grant never undoes a newer revoke, whatever order decisions arrive in
+ * and however often each is retried, and the application never reads before it writes. A revoke
+ * keeps the member's row, with its version. One member reads at `GET …/members/:userId`, and the
+ * list pages by user id: `limit` (100 unless named, at most 500) and the previous page's
+ * `nextCursor` as `cursor`.
+ *
+ * A budget caps CPU (millicores), memory and storage (bytes): ceilings, not measurements, and
+ * zero allows nothing. Storage is one allowance for volumes, archived ones included, and the
+ * backups and snapshots that protect them. `ensureResourceDomain` may name a new domain's budget
+ * and never changes one: naming another gets `409`, carrying the domain and its revision.
+ * `setResourceDomainBudget` takes the `revision` it read: a change made since gets `409`, so a
+ * delayed update never overwrites a newer one, and it answers the budget it wrote. Changing a
+ * budget changes nothing the domain holds. The read is one snapshot. It reports, per dimension,
+ * `used` (confirmed to exist), `reserved` (admitted, not yet confirmed), the `limit` and a `warning`
+ * once both reach 80%, 95% or all of it; storage also reports its `archived` and `protection` bytes.
  */
 import { Schema } from "effect";
 import { HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
+/**
+ * The dimensions a budget caps, defined once: the contract's schemas, the database's budget, the
+ * admission check and the SDK all take theirs from these keys. `freedBy` is what makes room in a
+ * dimension besides raising its limit.
+ */
+export declare const RESOURCE_DOMAIN_BUDGET_DIMENSIONS: {
+    readonly cpuMillicores: {
+        readonly name: "CPU";
+        readonly freedBy: "stop-objects";
+    };
+    readonly memoryBytes: {
+        readonly name: "memory";
+        readonly freedBy: "stop-objects";
+    };
+    readonly storageBytes: {
+        readonly name: "storage";
+        readonly freedBy: "purge-objects";
+    };
+};
+export type ResourceDomainBudgetDimension = keyof typeof RESOURCE_DOMAIN_BUDGET_DIMENSIONS;
+export declare const resourceDomainBudgetLimitsSchema: Schema.Struct<Record<"cpuMillicores" | "memoryBytes" | "storageBytes", Schema.Int>>;
+export type ResourceDomainBudgetLimits = typeof resourceDomainBudgetLimitsSchema.Type;
+/** The share of a limit at which the budget read starts to warn. */
+export declare const RESOURCE_DOMAIN_BUDGET_WARNINGS: {
+    readonly "80-percent": 80;
+    readonly "95-percent": 95;
+};
+declare const BudgetWarning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+export type ResourceDomainBudgetWarning = typeof BudgetWarning.Type;
+export declare const resourceDomainBudgetSchema: Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly storageBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        readonly archived: Schema.Int;
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        readonly protection: Schema.Int;
+    }>;
+    readonly cpuMillicores: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+    readonly memoryBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+}>;
+export type ResourceDomainBudgetWire = typeof resourceDomainBudgetSchema.Type;
+export declare const setResourceDomainBudgetRequestSchema: Schema.Struct<{
+    /** The revision this change replaces: the one the caller last read. */
+    readonly revision: Schema.Int;
+    readonly cpuMillicores: Schema.Int;
+    readonly memoryBytes: Schema.Int;
+    readonly storageBytes: Schema.Int;
+}>;
+export type SetResourceDomainBudgetRequest = typeof setResourceDomainBudgetRequestSchema.Type;
 export declare const resourceDomainSchema: Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
@@ -26,6 +110,8 @@ export declare const resourceDomainSchema: Schema.Struct<{
 export type ResourceDomainWire = typeof resourceDomainSchema.Type;
 export declare const ensureResourceDomainRequestSchema: Schema.Struct<{
     readonly key: Schema.String;
+    /** The budget a new domain starts with; none starts it at zero. */
+    readonly budget: Schema.optional<Schema.Struct<Record<"cpuMillicores" | "memoryBytes" | "storageBytes", Schema.Int>>>;
 }>;
 export type EnsureResourceDomainRequest = typeof ensureResourceDomainRequestSchema.Type;
 export declare const ensureResourceDomainResponseSchema: Schema.Struct<{
@@ -36,6 +122,40 @@ export declare const ensureResourceDomainResponseSchema: Schema.Struct<{
     readonly created: Schema.Boolean;
 }>;
 export type EnsureResourceDomainResponse = typeof ensureResourceDomainResponseSchema.Type;
+export declare const resourceDomainMemberSchema: Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>;
+export type ResourceDomainMemberWire = typeof resourceDomainMemberSchema.Type;
+export declare const resourceDomainMemberDecisionSchema: Schema.Struct<{
+    /** The application's own version of this decision, rising with each decision it makes. */
+    readonly version: Schema.Int;
+}>;
+export type ResourceDomainMemberDecisionRequest = typeof resourceDomainMemberDecisionSchema.Type;
+/** At most this many members a page, and this many when the request names no `limit`. */
+export declare const RESOURCE_DOMAIN_MEMBERS_PAGE: {
+    readonly default: 100;
+    readonly max: 500;
+};
+export declare const listResourceDomainMembersQuerySchema: Schema.Struct<{
+    readonly limit: Schema.optional<Schema.FiniteFromString>;
+    /** A previous page's `nextCursor`: the page starts after it. */
+    readonly cursor: Schema.optional<Schema.String>;
+}>;
+export type ListResourceDomainMembersQuery = typeof listResourceDomainMembersQuerySchema.Type;
+export declare const listResourceDomainMembersResponseSchema: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly userId: Schema.String;
+        readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+        readonly version: Schema.Int;
+        readonly updatedAt: Schema.String;
+    }>>;
+    /** Present when more members follow: pass it as `cursor` for the next page. */
+    readonly nextCursor: Schema.optional<Schema.String>;
+}>;
+export type ListResourceDomainMembersResponse = typeof listResourceDomainMembersResponseSchema.Type;
 declare const ResourceDomainForbiddenError_base: Schema.Class<ResourceDomainForbiddenError, Schema.TaggedStruct<"ResourceDomainForbiddenError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -46,6 +166,46 @@ declare const ResourceDomainNotFoundError_base: Schema.Class<ResourceDomainNotFo
 }>, import("effect/Cause").YieldableError>;
 export declare class ResourceDomainNotFoundError extends ResourceDomainNotFoundError_base {
 }
+declare const ResourceDomainPersonNotFoundError_base: Schema.Class<ResourceDomainPersonNotFoundError, Schema.TaggedStruct<"ResourceDomainPersonNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The person a member route names does not exist (the domain does). */
+export declare class ResourceDomainPersonNotFoundError extends ResourceDomainPersonNotFoundError_base {
+}
+declare const ResourceDomainMemberNotFoundError_base: Schema.Class<ResourceDomainMemberNotFoundError, Schema.TaggedStruct<"ResourceDomainMemberNotFoundError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The person exists, and the application has made no decision about them in the domain. */
+export declare class ResourceDomainMemberNotFoundError extends ResourceDomainMemberNotFoundError_base {
+}
+declare const ResourceDomainMemberVersionConflictError_base: Schema.Class<ResourceDomainMemberVersionConflictError, Schema.TaggedStruct<"ResourceDomainMemberVersionConflictError", {
+    readonly message: Schema.String;
+    readonly current: Schema.Struct<{
+        readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+        readonly version: Schema.Int;
+    }>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A decision at least as new stands, so this one changed nothing. `current` is the decision that
+ * stands; the message quotes nothing the request sent.
+ */
+export declare class ResourceDomainMemberVersionConflictError extends ResourceDomainMemberVersionConflictError_base {
+}
+declare const ResourceDomainBudgetDiffersError_base: Schema.Class<ResourceDomainBudgetDiffersError, Schema.TaggedStruct<"ResourceDomainBudgetDiffersError", {
+    readonly message: Schema.String;
+    readonly resourceDomainId: Schema.String;
+    readonly revision: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** The domain exists with another budget, at `revision`; nothing changed. */
+export declare class ResourceDomainBudgetDiffersError extends ResourceDomainBudgetDiffersError_base {
+}
+declare const ResourceDomainBudgetRevisionConflictError_base: Schema.Class<ResourceDomainBudgetRevisionConflictError, Schema.TaggedStruct<"ResourceDomainBudgetRevisionConflictError", {
+    readonly message: Schema.String;
+    readonly revision: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** `revision` is the current one. */
+export declare class ResourceDomainBudgetRevisionConflictError extends ResourceDomainBudgetRevisionConflictError_base {
+}
 declare const ResourceDomainInternalServerError_base: Schema.Class<ResourceDomainInternalServerError, Schema.TaggedStruct<"ResourceDomainInternalServerError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -53,17 +213,122 @@ export declare class ResourceDomainInternalServerError extends ResourceDomainInt
 }
 export declare const ResourceDomainsGroup: HttpApiGroup.HttpApiGroup<"resourceDomains", HttpApiEndpoint.HttpApiEndpoint<"ensureResourceDomain", "POST", "/", never, never, Schema.toCodecJson<Schema.Struct<{
     readonly key: Schema.String;
+    /** The budget a new domain starts with; none starts it at zero. */
+    readonly budget: Schema.optional<Schema.Struct<Record<"cpuMillicores" | "memoryBytes" | "storageBytes", Schema.Int>>>;
 }>>, never, Schema.toCodecJson<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
     readonly createdAt: Schema.String;
     /** True when this call created the domain. */
     readonly created: Schema.Boolean;
-}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomain", "GET", "/:resourceDomainId", Schema.toCodecStringTree<Schema.Struct<{
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainBudgetDiffersError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomain", "GET", "/:resourceDomainId", Schema.toCodecStringTree<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
 }>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
     readonly createdAt: Schema.String;
-}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never>, false>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomainBudget", "GET", "/:resourceDomainId/budget", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly storageBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        readonly archived: Schema.Int;
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        readonly protection: Schema.Int;
+    }>;
+    readonly cpuMillicores: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+    readonly memoryBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomainMember", "GET", "/:resourceDomainId/members/:userId", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly userId: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"grantResourceDomainMember", "POST", "/:resourceDomainId/members/:userId/grant", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly userId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The application's own version of this decision, rising with each decision it makes. */
+    readonly version: Schema.Int;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberVersionConflictError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"listResourceDomainMembers", "GET", "/:resourceDomainId/members", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, Schema.toCodecStringTree<Schema.Struct<{
+    readonly limit: Schema.optional<Schema.FiniteFromString>;
+    /** A previous page's `nextCursor`: the page starts after it. */
+    readonly cursor: Schema.optional<Schema.String>;
+}>>, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly userId: Schema.String;
+        readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+        readonly version: Schema.Int;
+        readonly updatedAt: Schema.String;
+    }>>;
+    /** Present when more members follow: pass it as `cursor` for the next page. */
+    readonly nextCursor: Schema.optional<Schema.String>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"revokeResourceDomainMember", "POST", "/:resourceDomainId/members/:userId/revoke", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+    readonly userId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The application's own version of this decision, rising with each decision it makes. */
+    readonly version: Schema.Int;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly userId: Schema.String;
+    readonly state: Schema.Literals<readonly ["member", "revoked"]>;
+    readonly version: Schema.Int;
+    readonly updatedAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberVersionConflictError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"setResourceDomainBudget", "PUT", "/:resourceDomainId/budget", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The revision this change replaces: the one the caller last read. */
+    readonly revision: Schema.Int;
+    readonly cpuMillicores: Schema.Int;
+    readonly memoryBytes: Schema.Int;
+    readonly storageBytes: Schema.Int;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly storageBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        readonly archived: Schema.Int;
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        readonly protection: Schema.Int;
+    }>;
+    readonly cpuMillicores: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+    readonly memoryBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainBudgetRevisionConflictError | typeof ResourceDomainInternalServerError>, never, never>, false>;
 export {};

package/dist/core-api/resource-domains.js

@@ -15,38 +15,159 @@
  * before a handler runs. A deployment served without authentication (the development exception)
  * serves them as it serves every other route. A request body is decoded strictly: a field the contract does not declare (an
  * owner, a credential) is refused with `400` instead of being dropped.
+ *
+ * Members are the people the application lets reach the domain. A grant or a revoke carries
+ * `version`, the application's own number for its decision about this person, rising with each
+ * decision it makes (its record's revision, say). Core writes the decision only over a lower
+ * version. The same version with the same state is a repeat, answered with the member unchanged.
+ * The same version with the other state, or a lower one, is stale: `409`, carrying the decision
+ * that stands. So a delayed grant never undoes a newer revoke, whatever order decisions arrive in
+ * and however often each is retried, and the application never reads before it writes. A revoke
+ * keeps the member's row, with its version. One member reads at `GET …/members/:userId`, and the
+ * list pages by user id: `limit` (100 unless named, at most 500) and the previous page's
+ * `nextCursor` as `cursor`.
+ *
+ * A budget caps CPU (millicores), memory and storage (bytes): ceilings, not measurements, and
+ * zero allows nothing. Storage is one allowance for volumes, archived ones included, and the
+ * backups and snapshots that protect them. `ensureResourceDomain` may name a new domain's budget
+ * and never changes one: naming another gets `409`, carrying the domain and its revision.
+ * `setResourceDomainBudget` takes the `revision` it read: a change made since gets `409`, so a
+ * delayed update never overwrites a newer one, and it answers the budget it wrote. Changing a
+ * budget changes nothing the domain holds. The read is one snapshot. It reports, per dimension,
+ * `used` (confirmed to exist), `reserved` (admitted, not yet confirmed), the `limit` and a `warning`
+ * once both reach 80%, 95% or all of it; storage also reports its `archived` and `protection` bytes.
  */
 import { Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api";
-import { RESOURCE_DOMAIN_ID_PREFIX } from "./person-id.js";
+import * as Rec from "effect/Record";
+import { PersonId, RESOURCE_DOMAIN_ID_PREFIX } from "./person-id.js";
 const RESOURCE_DOMAIN_ID_PATTERN = new RegExp(`^${RESOURCE_DOMAIN_ID_PREFIX}[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`);
 const RESOURCE_DOMAIN_KEY_PATTERN = /^[a-z][a-z0-9-]{0,31}:[A-Za-z0-9._:/@+=-]{1,223}$/;
 const ResourceDomainId = Schema.String.check(Schema.makeFilter((id) => RESOURCE_DOMAIN_ID_PATTERN.test(id) ? undefined : "must be a resource domain id (rdm:<uuid>)"));
 const ResourceDomainKey = Schema.String.check(Schema.makeFilter((key) => RESOURCE_DOMAIN_KEY_PATTERN.test(key)
     ? undefined
     : "must be <application>:<name>: a lower-case application name (letters, digits, '-'), a colon, then at most 223 letters, digits, '.', '_', ':', '/', '@', '+', '=' or '-'"));
+const Amount = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }));
+const BudgetRevision = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }));
+/**
+ * The dimensions a budget caps, defined once: the contract's schemas, the database's budget, the
+ * admission check and the SDK all take theirs from these keys. `freedBy` is what makes room in a
+ * dimension besides raising its limit.
+ */
+export const RESOURCE_DOMAIN_BUDGET_DIMENSIONS = {
+    cpuMillicores: { name: "CPU", freedBy: "stop-objects" },
+    memoryBytes: { name: "memory", freedBy: "stop-objects" },
+    storageBytes: { name: "storage", freedBy: "purge-objects" },
+};
+export const resourceDomainBudgetLimitsSchema = Schema.Struct(Rec.map(RESOURCE_DOMAIN_BUDGET_DIMENSIONS, () => Amount));
+/** The share of a limit at which the budget read starts to warn. */
+export const RESOURCE_DOMAIN_BUDGET_WARNINGS = { "80-percent": 80, "95-percent": 95 };
+const BudgetWarning = Schema.Literals(["none", "80-percent", "95-percent", "full"]);
+const budgetDimensionSchema = Schema.Struct({
+    limit: Amount,
+    used: Amount,
+    reserved: Amount,
+    warning: BudgetWarning,
+});
+export const resourceDomainBudgetSchema = Schema.Struct({
+    revision: BudgetRevision,
+    ...Rec.map(RESOURCE_DOMAIN_BUDGET_DIMENSIONS, () => budgetDimensionSchema),
+    storageBytes: Schema.Struct({
+        ...budgetDimensionSchema.fields,
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        archived: Amount,
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        protection: Amount,
+    }),
+});
+export const setResourceDomainBudgetRequestSchema = Schema.Struct({
+    ...resourceDomainBudgetLimitsSchema.fields,
+    /** The revision this change replaces: the one the caller last read. */
+    revision: BudgetRevision,
+});
 export const resourceDomainSchema = Schema.Struct({
     resourceDomainId: ResourceDomainId,
     key: ResourceDomainKey,
     createdAt: Schema.String,
 });
-export const ensureResourceDomainRequestSchema = Schema.Struct({ key: ResourceDomainKey });
+export const ensureResourceDomainRequestSchema = Schema.Struct({
+    key: ResourceDomainKey,
+    /** The budget a new domain starts with; none starts it at zero. */
+    budget: Schema.optional(resourceDomainBudgetLimitsSchema),
+});
 export const ensureResourceDomainResponseSchema = Schema.Struct({
     ...resourceDomainSchema.fields,
     /** True when this call created the domain. */
     created: Schema.Boolean,
 });
+const MemberVersion = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }));
+const MemberState = Schema.Literals(["member", "revoked"]);
+export const resourceDomainMemberSchema = Schema.Struct({
+    userId: PersonId,
+    state: MemberState,
+    version: MemberVersion,
+    updatedAt: Schema.String,
+});
+export const resourceDomainMemberDecisionSchema = Schema.Struct({
+    /** The application's own version of this decision, rising with each decision it makes. */
+    version: MemberVersion,
+});
+/** At most this many members a page, and this many when the request names no `limit`. */
+export const RESOURCE_DOMAIN_MEMBERS_PAGE = { default: 100, max: 500 };
+export const listResourceDomainMembersQuerySchema = Schema.Struct({
+    limit: Schema.optional(Schema.FiniteFromString.check(Schema.isInt(), Schema.isBetween({ minimum: 1, maximum: RESOURCE_DOMAIN_MEMBERS_PAGE.max }))),
+    /** A previous page's `nextCursor`: the page starts after it. */
+    cursor: Schema.optional(Schema.String.check(Schema.isNonEmpty())),
+});
+export const listResourceDomainMembersResponseSchema = Schema.Struct({
+    items: Schema.Array(resourceDomainMemberSchema),
+    /** Present when more members follow: pass it as `cursor` for the next page. */
+    nextCursor: Schema.optional(Schema.String),
+});
 export class ResourceDomainForbiddenError extends Schema.TaggedError()("ResourceDomainForbiddenError", { message: Schema.String }, { httpApiStatus: 403 }) {
 }
 export class ResourceDomainNotFoundError extends Schema.TaggedError()("ResourceDomainNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
 }
+/** The person a member route names does not exist (the domain does). */
+export class ResourceDomainPersonNotFoundError extends Schema.TaggedError()("ResourceDomainPersonNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+/** The person exists, and the application has made no decision about them in the domain. */
+export class ResourceDomainMemberNotFoundError extends Schema.TaggedError()("ResourceDomainMemberNotFoundError", { message: Schema.String }, { httpApiStatus: 404 }) {
+}
+/**
+ * A decision at least as new stands, so this one changed nothing. `current` is the decision that
+ * stands; the message quotes nothing the request sent.
+ */
+export class ResourceDomainMemberVersionConflictError extends Schema.TaggedError()("ResourceDomainMemberVersionConflictError", {
+    message: Schema.String,
+    current: Schema.Struct({ state: MemberState, version: MemberVersion }),
+}, { httpApiStatus: 409 }) {
+}
+/** The domain exists with another budget, at `revision`; nothing changed. */
+export class ResourceDomainBudgetDiffersError extends Schema.TaggedError()("ResourceDomainBudgetDiffersError", { message: Schema.String, resourceDomainId: ResourceDomainId, revision: BudgetRevision }, { httpApiStatus: 409 }) {
+}
+/** `revision` is the current one. */
+export class ResourceDomainBudgetRevisionConflictError extends Schema.TaggedError()("ResourceDomainBudgetRevisionConflictError", { message: Schema.String, revision: BudgetRevision }, { httpApiStatus: 409 }) {
+}
 export class ResourceDomainInternalServerError extends Schema.TaggedError()("ResourceDomainInternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
 }
+const memberParams = Schema.Struct({ resourceDomainId: ResourceDomainId, userId: PersonId });
+const memberErrors = [
+    ResourceDomainForbiddenError,
+    ResourceDomainNotFoundError,
+    ResourceDomainPersonNotFoundError,
+    ResourceDomainMemberVersionConflictError,
+    ResourceDomainInternalServerError,
+];
 export const ResourceDomainsGroup = HttpApiGroup.make("resourceDomains")
     .add(HttpApiEndpoint.post("ensureResourceDomain", "/", {
     payload: ensureResourceDomainRequestSchema,
     success: ensureResourceDomainResponseSchema,
-    error: [ResourceDomainForbiddenError, ResourceDomainInternalServerError],
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainBudgetDiffersError,
+        ResourceDomainInternalServerError,
+    ],
 }))
     .add(HttpApiEndpoint.get("getResourceDomain", "/:resourceDomainId", {
     params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
@@ -56,6 +177,59 @@ export const ResourceDomainsGroup = HttpApiGroup.make("resourceDomains")
         ResourceDomainNotFoundError,
         ResourceDomainInternalServerError,
     ],
+}))
+    .add(HttpApiEndpoint.post("grantResourceDomainMember", "/:resourceDomainId/members/:userId/grant", {
+    params: memberParams,
+    payload: resourceDomainMemberDecisionSchema,
+    success: resourceDomainMemberSchema,
+    error: memberErrors,
+}))
+    .add(HttpApiEndpoint.post("revokeResourceDomainMember", "/:resourceDomainId/members/:userId/revoke", {
+    params: memberParams,
+    payload: resourceDomainMemberDecisionSchema,
+    success: resourceDomainMemberSchema,
+    error: memberErrors,
+}))
+    .add(HttpApiEndpoint.get("getResourceDomainMember", "/:resourceDomainId/members/:userId", {
+    params: memberParams,
+    success: resourceDomainMemberSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainPersonNotFoundError,
+        ResourceDomainMemberNotFoundError,
+        ResourceDomainInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.get("listResourceDomainMembers", "/:resourceDomainId/members", {
+    params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
+    query: listResourceDomainMembersQuerySchema,
+    success: listResourceDomainMembersResponseSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.get("getResourceDomainBudget", "/:resourceDomainId/budget", {
+    params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
+    success: resourceDomainBudgetSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.put("setResourceDomainBudget", "/:resourceDomainId/budget", {
+    params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
+    payload: setResourceDomainBudgetRequestSchema,
+    success: resourceDomainBudgetSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainBudgetRevisionConflictError,
+        ResourceDomainInternalServerError,
+    ],
 }))
     .annotate(HttpApi.PayloadParseOptions, { onExcessProperty: "error" })
     .annotate(OpenApi.Description, "Owners that are projects, not people: they never hold a login or a provider credential.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.40.0-next.769",
+  "version": "0.40.0-next.771",
   "description": "Contract-first HTTP API definitions for Sealant services",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "ab6f8d9ccf2f282c542e388b994099cae91c1354",
+  "gitHead": "697e8d55f312105e4f52964dd5a7fb956c0c6d63",
   "publishConfig": {
     "access": "public"
   }