@house-rules/party 0.0.0-stage → 0.1.0

package/dist/person/operations.js

@@ -0,0 +1,92 @@
+import { ActorId, defineOperation, NoInput } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+import { OrganisationRelation, PartyDenied, PartyNotFound, PartyUnavailable, } from "../organisation/organisation.js";
+import { AccessOperations } from "../role/operations.js";
+import { PartyPermissions } from "./permissions.js";
+import { PrincipalOperations } from "./principal-operations.js";
+import { Person, PersonAlreadyExists, PersonCallerDenied, PersonInputInvalid, PersonNotFound, PersonStoreUnavailable, PersonUpdateRefused, } from "./person.js";
+const createPerson = defineOperation("Party.createPerson", {
+    description: "Create a person during trusted account setup.",
+    input: Schema.Struct({ displayName: Schema.String, id: Schema.optionalKey(ActorId) }),
+    output: Person,
+    failure: Schema.Union([
+        PersonAlreadyExists,
+        PersonCallerDenied,
+        PersonInputInvalid,
+        PersonStoreUnavailable,
+    ]),
+    permission: "party:create",
+    edges: [],
+    transactional: true,
+});
+const showPerson = defineOperation("Party.showPerson", {
+    description: "Show one person's display name by id.",
+    input: Schema.Struct({ id: ActorId }),
+    output: Person,
+    failure: Schema.Union([PersonNotFound, PersonStoreUnavailable]),
+    permission: PartyPermissions.read,
+    edges: [],
+    readOnly: true,
+});
+const showMe = defineOperation("Party.showMe", {
+    description: "Show the signed-in person: their id and display name.",
+    input: NoInput,
+    output: Person,
+    failure: Schema.Union([PersonNotFound, PersonStoreUnavailable]),
+    permission: PartyPermissions.read,
+    edges: [],
+    readOnly: true,
+});
+const renamePerson = defineOperation("Party.renamePerson", {
+    description: "Change your own display name.",
+    input: Schema.Struct({ id: ActorId, displayName: Schema.String }),
+    output: Person,
+    failure: Schema.Union([
+        PersonInputInvalid,
+        PersonNotFound,
+        PersonUpdateRefused,
+        PersonStoreUnavailable,
+    ]),
+    permission: PartyPermissions.update,
+    edges: [],
+    transactional: true,
+});
+const listPeople = defineOperation("Party.listPeople", {
+    description: "List everyone for global admins, or only your organisations' staff for scoped admins.",
+    input: NoInput,
+    output: Schema.Array(Schema.Struct({
+        ...Person.fields,
+        assignments: Schema.Array(Schema.Struct({
+            roleKey: Schema.String,
+            roleName: Schema.String,
+            organisationId: Schema.NullOr(Schema.String),
+            organisationName: Schema.NullOr(Schema.String),
+        })),
+        organisations: Schema.Array(OrganisationRelation),
+    })),
+    failure: Schema.Union([PartyDenied, PartyUnavailable]),
+    permission: "party:admin",
+    readOnly: true,
+});
+const listMembers = defineOperation("Party.listMembers", {
+    description: "List an organisation's members and scoped roles only when you administer it.",
+    input: Schema.Struct({ organisationId: Schema.String }),
+    output: Schema.Array(Schema.Struct({
+        ...Person.fields,
+        relation: Schema.NullOr(Schema.String),
+        roles: Schema.Array(Schema.Struct({ roleKey: Schema.String, roleName: Schema.String })),
+    })),
+    failure: Schema.Union([PartyNotFound, PartyUnavailable]),
+    permission: "party:read",
+    readOnly: true,
+});
+export const PartyOperations = {
+    ...PrincipalOperations,
+    listMembers,
+    listPeople,
+    createPerson,
+    showPerson,
+    showMe,
+    renamePerson,
+    ...AccessOperations,
+};

package/dist/person/party.d.ts

@@ -0,0 +1,36 @@
+import { ActorId } from "@house-rules/domain";
+import { Effect } from "effect";
+import type { PersonStore } from "../storage.js";
+import { PersonAlreadyExists, PersonInputInvalid, PersonNotFound, PersonUpdateRefused } from "./person.js";
+export declare const makeParty: (store: PersonStore["Service"]) => {
+    createPerson: (input: {
+        readonly displayName: string;
+        readonly id?: ActorId;
+    }) => Effect.Effect<{
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+        readonly displayName: string;
+        readonly createdAt: number;
+    }, import("@house-rules/domain").NoOpenUnit | PersonAlreadyExists | PersonInputInvalid | import("./person.js").PersonStoreUnavailable, never>;
+    get: (actor: {
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+    }, id: string & import("effect/Brand").Brand<"ActorId">) => Effect.Effect<{
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+        readonly displayName: string;
+        readonly createdAt: number;
+    }, PersonNotFound | import("./person.js").PersonStoreUnavailable, never>;
+    me: (actor: {
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+    }) => Effect.Effect<{
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+        readonly displayName: string;
+        readonly createdAt: number;
+    }, PersonNotFound | import("./person.js").PersonStoreUnavailable, never>;
+    rename: (actor: {
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+    }, id: string & import("effect/Brand").Brand<"ActorId">, displayName: string) => Effect.Effect<{
+        readonly id: string & import("effect/Brand").Brand<"ActorId">;
+        readonly displayName: string;
+        readonly createdAt: number;
+    }, import("@house-rules/domain").NoOpenUnit | PersonInputInvalid | PersonNotFound | import("./person.js").PersonStoreUnavailable | PersonUpdateRefused, never>;
+    erase: (id: string & import("effect/Brand").Brand<"ActorId">) => Effect.Effect<void, import("@house-rules/domain").NoOpenUnit | import("./person.js").PersonStoreUnavailable, never>;
+};

package/dist/person/party.js

@@ -0,0 +1,55 @@
+import { ActorId, UnitOfWork } from "@house-rules/domain";
+import { DateTime, Effect, Random, Schema } from "effect";
+import { PartyPermissions } from "./permissions.js";
+import { DisplayName, PersonAlreadyExists, PersonInputInvalid, PersonNotFound, PersonUpdateRefused, } from "./person.js";
+import { personPolicy } from "./policy.js";
+export const makeParty = (store) => {
+    const decodeName = Schema.decodeUnknownEffect(DisplayName);
+    const decodeId = Schema.decodeUnknownEffect(ActorId);
+    const invalid = () => new PersonInputInvalid({ message: "Invalid person input." });
+    const newId = Effect.all(Array.from({ length: 4 }, () => Random.nextIntBetween(0, 0xffff_ffff))).pipe(Effect.map((words) => words.map((word) => word.toString(16).padStart(8, "0")).join("")), Effect.map((hex) => ActorId.make(hex)));
+    const relationOf = (actor, id) => (actor.id === id ? "self" : "other");
+    const get = Effect.fn("Party.get")(function* (actor, id) {
+        if (!personPolicy.allows(relationOf(actor, id), PartyPermissions.read))
+            return yield* new PersonNotFound();
+        const person = yield* store.find(id);
+        if (person === undefined)
+            return yield* new PersonNotFound();
+        return person;
+    });
+    return {
+        createPerson: Effect.fn("Party.createPerson")(function* (input) {
+            yield* UnitOfWork.required;
+            const displayName = yield* decodeName(input.displayName).pipe(Effect.mapError(invalid));
+            const id = input.id === undefined
+                ? yield* newId
+                : yield* decodeId(input.id).pipe(Effect.mapError(invalid));
+            const person = {
+                id,
+                displayName,
+                createdAt: DateTime.toEpochMillis(yield* DateTime.now),
+            };
+            if (!(yield* store.insertIfFree(person)))
+                return yield* new PersonAlreadyExists();
+            return person;
+        }),
+        get,
+        me: Effect.fn("Party.me")(function* (actor) {
+            return yield* get(actor, actor.id);
+        }),
+        rename: Effect.fn("Party.rename")(function* (actor, id, displayName) {
+            yield* UnitOfWork.required;
+            if (!personPolicy.allows(relationOf(actor, id), PartyPermissions.update))
+                return yield* new PersonUpdateRefused();
+            const decoded = yield* decodeName(displayName).pipe(Effect.mapError(invalid));
+            const person = yield* store.rename(id, decoded);
+            if (person === undefined)
+                return yield* new PersonNotFound();
+            return person;
+        }),
+        erase: Effect.fn("Party.erase")(function* (id) {
+            yield* UnitOfWork.required;
+            yield* store.erase(id);
+        }),
+    };
+};

package/dist/person/permissions.d.ts

@@ -0,0 +1,6 @@
+export declare const PartyPermissions: {
+    readonly read: "party:read";
+    readonly admin: "party:admin";
+    readonly update: "party:update";
+};
+export type PartyPermission = (typeof PartyPermissions)[keyof typeof PartyPermissions];

package/dist/person/permissions.js

@@ -0,0 +1,5 @@
+export const PartyPermissions = {
+    read: "party:read",
+    admin: "party:admin",
+    update: "party:update",
+};

package/dist/person/person-store.d.ts

@@ -0,0 +1,21 @@
+import type { ActorId, NoOpenUnit } from "@house-rules/domain";
+import { Context, type Effect } from "effect";
+import type { Person, PersonStoreUnavailable } from "./person.js";
+import type { Principal } from "./principal.js";
+declare const PersonStore_base: Context.ServiceClass<PersonStore, "@house-rules/party/PersonStore", {
+    readonly principal: (id: ActorId) => Effect.Effect<Principal | undefined, PersonStoreUnavailable>;
+    readonly principalByHandle: (handle: string) => Effect.Effect<Principal | undefined, PersonStoreUnavailable>;
+    readonly principalsByIds: (ids: readonly ActorId[]) => Effect.Effect<readonly Principal[], PersonStoreUnavailable>;
+    readonly insertPrincipal: (principal: Principal) => Effect.Effect<boolean, PersonStoreUnavailable | NoOpenUnit>;
+    readonly lockPrincipal: (handle: string) => Effect.Effect<Principal | undefined, PersonStoreUnavailable | NoOpenUnit>;
+    readonly principalForUpdate: (id: ActorId) => Effect.Effect<Principal | undefined, PersonStoreUnavailable | NoOpenUnit>;
+    readonly disable: (id: ActorId, disabledAt: number) => Effect.Effect<Principal | undefined, PersonStoreUnavailable | NoOpenUnit>;
+    readonly find: (id: ActorId) => Effect.Effect<Person | undefined, PersonStoreUnavailable>;
+    readonly list: (ids: readonly ActorId[] | null) => Effect.Effect<readonly Person[], PersonStoreUnavailable>;
+    readonly insertIfFree: (person: Person) => Effect.Effect<boolean, PersonStoreUnavailable | NoOpenUnit>;
+    readonly rename: (id: ActorId, displayName: string) => Effect.Effect<Person | undefined, PersonStoreUnavailable | NoOpenUnit>;
+    readonly erase: (id: ActorId) => Effect.Effect<void, PersonStoreUnavailable | NoOpenUnit>;
+}>;
+export declare class PersonStore extends PersonStore_base {
+}
+export {};

package/dist/person/person-store.js

@@ -0,0 +1,3 @@
+import { Context } from "effect";
+export class PersonStore extends Context.Service()("@house-rules/party/PersonStore") {
+}

package/dist/person/person.d.ts

@@ -0,0 +1,43 @@
+import { Schema } from "effect";
+export declare const DisplayName: Schema.Trim;
+export type DisplayName = typeof DisplayName.Type;
+export declare const Person: Schema.Struct<{
+    readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+    readonly displayName: Schema.Trim;
+    readonly createdAt: Schema.Int;
+}>;
+export type Person = typeof Person.Type;
+declare const PersonCallerDenied_base: Schema.Class<PersonCallerDenied, Schema.TaggedStruct<"PersonCallerDenied", {
+    readonly kind: Schema.tag<"forbidden">;
+}>, import("effect/Cause").YieldableError>;
+export declare class PersonCallerDenied extends PersonCallerDenied_base {
+}
+declare const PersonNotFound_base: Schema.Class<PersonNotFound, Schema.TaggedStruct<"PersonNotFound", {
+    readonly kind: Schema.tag<"not_found">;
+}>, import("effect/Cause").YieldableError>;
+export declare class PersonNotFound extends PersonNotFound_base {
+}
+declare const PersonUpdateRefused_base: Schema.Class<PersonUpdateRefused, Schema.TaggedStruct<"PersonUpdateRefused", {
+    readonly kind: Schema.tag<"forbidden">;
+}>, import("effect/Cause").YieldableError>;
+export declare class PersonUpdateRefused extends PersonUpdateRefused_base {
+}
+declare const PersonAlreadyExists_base: Schema.Class<PersonAlreadyExists, Schema.TaggedStruct<"PersonAlreadyExists", {
+    readonly kind: Schema.tag<"conflict">;
+}>, import("effect/Cause").YieldableError>;
+export declare class PersonAlreadyExists extends PersonAlreadyExists_base {
+}
+declare const PersonInputInvalid_base: Schema.Class<PersonInputInvalid, Schema.TaggedStruct<"PersonInputInvalid", {
+    readonly kind: Schema.tag<"invalid">;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class PersonInputInvalid extends PersonInputInvalid_base {
+}
+declare const PersonStoreUnavailable_base: Schema.Class<PersonStoreUnavailable, Schema.TaggedStruct<"PersonStoreUnavailable", {
+    readonly kind: Schema.tag<"unavailable">;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class PersonStoreUnavailable extends PersonStoreUnavailable_base {
+    get message(): string;
+}
+export {};

package/dist/person/person.js

@@ -0,0 +1,25 @@
+import { ActorId, errorKind } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+export const DisplayName = Schema.Trim.check(Schema.isMinLength(1), Schema.isMaxLength(120));
+export const Person = Schema.Struct({
+    id: ActorId,
+    displayName: DisplayName,
+    createdAt: Schema.Int,
+});
+export class PersonCallerDenied extends Schema.TaggedError()("PersonCallerDenied", { kind: errorKind("forbidden") }) {
+}
+export class PersonNotFound extends Schema.TaggedError()("PersonNotFound", {
+    kind: errorKind("not_found"),
+}) {
+}
+export class PersonUpdateRefused extends Schema.TaggedError()("PersonUpdateRefused", { kind: errorKind("forbidden") }) {
+}
+export class PersonAlreadyExists extends Schema.TaggedError()("PersonAlreadyExists", { kind: errorKind("conflict") }) {
+}
+export class PersonInputInvalid extends Schema.TaggedError()("PersonInputInvalid", { kind: errorKind("invalid"), message: Schema.String }) {
+}
+export class PersonStoreUnavailable extends Schema.TaggedError()("PersonStoreUnavailable", { kind: errorKind("unavailable"), cause: Schema.Defect() }) {
+    get message() {
+        return "People are unavailable. Try again shortly.";
+    }
+}

package/dist/person/policy.d.ts

@@ -0,0 +1 @@
+export declare const personPolicy: import("@house-rules/domain").PolicyBuilder<"other" | "self", "party:read" | "party:update">;

package/dist/person/policy.js

@@ -0,0 +1,6 @@
+import { definePolicy } from "@house-rules/domain";
+import { PartyPermissions } from "./permissions.js";
+export const personPolicy = definePolicy({
+    self: [PartyPermissions.read, PartyPermissions.update],
+    other: [PartyPermissions.read],
+});

package/dist/person/principal-operations.d.ts

@@ -0,0 +1,110 @@
+import { Schema } from "effect";
+import { PartyUnavailable } from "../organisation/organisation.js";
+import { PersonAlreadyExists, PersonCallerDenied, PersonInputInvalid, PersonNotFound, PersonStoreUnavailable } from "./person.js";
+import { PrincipalKindRefused, PrincipalDisabledRefused } from "./principal.js";
+export declare const PrincipalOperations: {
+    readonly createPrincipal: import("@house-rules/domain/contract").Operation<"Party.createPrincipal", Schema.Struct<{
+        readonly id: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly displayName: Schema.String;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+    }>, Schema.Struct<{
+        readonly principal: Schema.Struct<{
+            readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+            readonly displayName: Schema.Trim;
+            readonly createdAt: Schema.Int;
+            readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+            readonly handle: Schema.String;
+            readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+            readonly disabledAt: Schema.NullOr<Schema.Int>;
+        }>;
+        readonly fact: Schema.Struct<{
+            readonly kind: Schema.Literal<"principal.created">;
+            readonly after: Schema.Struct<{
+                readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+                readonly displayName: Schema.Trim;
+                readonly createdAt: Schema.Int;
+                readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+                readonly handle: Schema.String;
+                readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+                readonly disabledAt: Schema.NullOr<Schema.Int>;
+            }>;
+        }>;
+    }>, Schema.Union<readonly [typeof PersonAlreadyExists, typeof PersonCallerDenied, typeof PersonInputInvalid, typeof PersonStoreUnavailable]>, NoInfer<readonly []>, false, false, true, false>;
+    readonly disable: import("@house-rules/domain/contract").Operation<"Party.disable", Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+    }>, Schema.Struct<{
+        readonly principal: Schema.Struct<{
+            readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+            readonly displayName: Schema.Trim;
+            readonly createdAt: Schema.Int;
+            readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+            readonly handle: Schema.String;
+            readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+            readonly disabledAt: Schema.NullOr<Schema.Int>;
+        }>;
+        readonly fact: Schema.NullOr<Schema.Struct<{
+            readonly kind: Schema.Literal<"principal.disabled">;
+            readonly before: Schema.Struct<{
+                readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+                readonly displayName: Schema.Trim;
+                readonly createdAt: Schema.Int;
+                readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+                readonly handle: Schema.String;
+                readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+                readonly disabledAt: Schema.NullOr<Schema.Int>;
+            }>;
+            readonly after: Schema.Struct<{
+                readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+                readonly displayName: Schema.Trim;
+                readonly createdAt: Schema.Int;
+                readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+                readonly handle: Schema.String;
+                readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+                readonly disabledAt: Schema.NullOr<Schema.Int>;
+            }>;
+        }>>;
+    }>, Schema.Union<readonly [typeof PersonNotFound, typeof PersonCallerDenied, typeof PersonStoreUnavailable]>, NoInfer<readonly []>, false, true, true, true>;
+    readonly lockActive: import("@house-rules/domain/contract").Operation<"Party.lockActive", Schema.Struct<{
+        readonly handle: Schema.String;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+    }>, Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>, Schema.Union<readonly [typeof PersonNotFound, typeof PrincipalKindRefused, typeof PrincipalDisabledRefused, typeof PersonStoreUnavailable]>, NoInfer<readonly []>, false, false, true, false>;
+    readonly principalsByIds: import("@house-rules/domain/contract").Operation<"Party.principalsByIds", Schema.Struct<{
+        readonly ids: Schema.$Array<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+    }>, Schema.$Array<Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>>, typeof PersonStoreUnavailable, NoInfer<readonly []>, true, false, false, false>;
+    readonly findPrincipal: import("@house-rules/domain/contract").Operation<"Party.findPrincipal", Schema.Struct<{
+        readonly handle: Schema.String;
+    }>, Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>, Schema.Union<readonly [typeof PersonNotFound, typeof PersonStoreUnavailable]>, NoInfer<readonly []>, true, false, false, false>;
+    readonly holdersOf: import("@house-rules/domain/contract").Operation<"Party.holdersOf", Schema.Struct<{
+        readonly role: Schema.NonEmptyString;
+        readonly scope: Schema.optionalKey<Schema.NullOr<Schema.NonEmptyString>>;
+    }>, Schema.Struct<{
+        readonly ids: Schema.$Array<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly truncated: Schema.Boolean;
+    }>, typeof PartyUnavailable, NoInfer<readonly []>, true, false, false, false>;
+};

package/dist/person/principal-operations.js

@@ -0,0 +1,77 @@
+import { ActorId, defineOperation } from "@house-rules/domain/contract";
+import { Schema } from "effect";
+import { PartyUnavailable } from "../organisation/organisation.js";
+import { RoleKey } from "../role/role.js";
+import { PersonAlreadyExists, PersonCallerDenied, PersonInputInvalid, PersonNotFound, PersonStoreUnavailable, } from "./person.js";
+import { CreatePrincipal, CreatedPrincipal, DisabledPrincipal, Principal, PrincipalKind, PrincipalKindRefused, PrincipalDisabledRefused, } from "./principal.js";
+const createPrincipal = defineOperation("Party.createPrincipal", {
+    description: "Create a person or agent principal during trusted provisioning.",
+    input: CreatePrincipal,
+    output: CreatedPrincipal,
+    failure: Schema.Union([
+        PersonAlreadyExists,
+        PersonCallerDenied,
+        PersonInputInvalid,
+        PersonStoreUnavailable,
+    ]),
+    permission: "party:create",
+    transactional: true,
+});
+const disable = defineOperation("Party.disable", {
+    description: "Permanently disable a principal during trusted provisioning.",
+    input: Schema.Struct({ id: ActorId }),
+    output: DisabledPrincipal,
+    failure: Schema.Union([PersonNotFound, PersonCallerDenied, PersonStoreUnavailable]),
+    permission: "party:update",
+    transactional: true,
+    destructive: true,
+    needsApproval: true,
+});
+const lockActive = defineOperation("Party.lockActive", {
+    description: "Lock an active principal of the requested kind until this unit ends.",
+    input: Schema.Struct({ handle: Schema.String, kind: PrincipalKind }),
+    output: Principal,
+    failure: Schema.Union([
+        PersonNotFound,
+        PrincipalKindRefused,
+        PrincipalDisabledRefused,
+        PersonStoreUnavailable,
+    ]),
+    permission: "party:read",
+    transactional: true,
+});
+const principalsByIds = defineOperation("Party.principalsByIds", {
+    description: "Read principal names and standing for a person or system caller.",
+    input: Schema.Struct({ ids: Schema.Array(ActorId) }),
+    output: Schema.Array(Principal),
+    failure: PersonStoreUnavailable,
+    permission: "party:read",
+    readOnly: true,
+});
+const findPrincipal = defineOperation("Party.findPrincipal", {
+    description: "Find a principal by its exact handle, including disabled principals.",
+    input: Schema.Struct({ handle: Schema.String }),
+    output: Principal,
+    failure: Schema.Union([PersonNotFound, PersonStoreUnavailable]),
+    permission: "party:read",
+    readOnly: true,
+});
+const holdersOf = defineOperation("Party.holdersOf", {
+    description: "Read bounded principal ids assigned a role in one exact scope, global when omitted.",
+    input: Schema.Struct({
+        role: RoleKey,
+        scope: Schema.optionalKey(Schema.NullOr(Schema.NonEmptyString)),
+    }),
+    output: Schema.Struct({ ids: Schema.Array(ActorId), truncated: Schema.Boolean }),
+    failure: PartyUnavailable,
+    permission: "party:read",
+    readOnly: true,
+});
+export const PrincipalOperations = {
+    createPrincipal,
+    disable,
+    lockActive,
+    principalsByIds,
+    findPrincipal,
+    holdersOf,
+};

package/dist/person/principal.d.ts

@@ -0,0 +1,126 @@
+import { Schema } from "effect";
+import { Person } from "./person.js";
+export declare const PrincipalKind: Schema.Literals<readonly ["person", "agent"]>;
+export type PrincipalKind = typeof PrincipalKind.Type;
+export declare const PrincipalHandle: Schema.String;
+export declare const Principal: Schema.Struct<{
+    readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+    readonly displayName: Schema.Trim;
+    readonly createdAt: Schema.Int;
+    readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+    readonly handle: Schema.String;
+    readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+    readonly disabledAt: Schema.NullOr<Schema.Int>;
+}>;
+export type Principal = typeof Principal.Type;
+export declare const CreatePrincipal: Schema.Struct<{
+    readonly id: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+    readonly displayName: Schema.String;
+    readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+    readonly handle: Schema.String;
+    readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+}>;
+export type CreatePrincipal = typeof CreatePrincipal.Type;
+export declare const PrincipalCreated: Schema.Struct<{
+    readonly kind: Schema.Literal<"principal.created">;
+    readonly after: Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>;
+}>;
+export declare const PrincipalDisabled: Schema.Struct<{
+    readonly kind: Schema.Literal<"principal.disabled">;
+    readonly before: Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>;
+    readonly after: Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>;
+}>;
+export declare const CreatedPrincipal: Schema.Struct<{
+    readonly principal: Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>;
+    readonly fact: Schema.Struct<{
+        readonly kind: Schema.Literal<"principal.created">;
+        readonly after: Schema.Struct<{
+            readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+            readonly displayName: Schema.Trim;
+            readonly createdAt: Schema.Int;
+            readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+            readonly handle: Schema.String;
+            readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+            readonly disabledAt: Schema.NullOr<Schema.Int>;
+        }>;
+    }>;
+}>;
+export type CreatedPrincipal = typeof CreatedPrincipal.Type;
+export declare const DisabledPrincipal: Schema.Struct<{
+    readonly principal: Schema.Struct<{
+        readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+        readonly displayName: Schema.Trim;
+        readonly createdAt: Schema.Int;
+        readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+        readonly handle: Schema.String;
+        readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+        readonly disabledAt: Schema.NullOr<Schema.Int>;
+    }>;
+    readonly fact: Schema.NullOr<Schema.Struct<{
+        readonly kind: Schema.Literal<"principal.disabled">;
+        readonly before: Schema.Struct<{
+            readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+            readonly displayName: Schema.Trim;
+            readonly createdAt: Schema.Int;
+            readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+            readonly handle: Schema.String;
+            readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+            readonly disabledAt: Schema.NullOr<Schema.Int>;
+        }>;
+        readonly after: Schema.Struct<{
+            readonly id: Schema.brand<Schema.NonEmptyString, "ActorId">;
+            readonly displayName: Schema.Trim;
+            readonly createdAt: Schema.Int;
+            readonly kind: Schema.Literals<readonly ["person", "agent"]>;
+            readonly handle: Schema.String;
+            readonly createdBy: Schema.NullOr<Schema.brand<Schema.NonEmptyString, "ActorId">>;
+            readonly disabledAt: Schema.NullOr<Schema.Int>;
+        }>;
+    }>>;
+}>;
+export type DisabledPrincipal = typeof DisabledPrincipal.Type;
+declare const PrincipalDisabledRefused_base: Schema.Class<PrincipalDisabledRefused, Schema.TaggedStruct<"PrincipalDisabledRefused", {
+    readonly kind: Schema.tag<"forbidden">;
+}>, import("effect/Cause").YieldableError>;
+export declare class PrincipalDisabledRefused extends PrincipalDisabledRefused_base {
+}
+declare const PrincipalKindRefused_base: Schema.Class<PrincipalKindRefused, Schema.TaggedStruct<"PrincipalKindRefused", {
+    readonly kind: Schema.tag<"forbidden">;
+}>, import("effect/Cause").YieldableError>;
+export declare class PrincipalKindRefused extends PrincipalKindRefused_base {
+}
+export declare const legacyPrincipal: (person: Person) => Principal;
+export declare const personOf: ({ id, displayName, createdAt }: Person) => Person;
+export {};