@phis/contracts 0.2.0

package/dist/addon.d.ts

@@ -0,0 +1,259 @@
+/**
+ * What a phi-server Add-on declares or implements.
+ *
+ * This package exists so an Add-on has something to build against that is not phi-server itself.
+ * phi-server is a private application without an export surface; an Add-on published to a registry
+ * could not depend on it, and a type import into the application's internals would bind an Add-on to a
+ * file path that can move without anybody noticing.
+ *
+ * The admission rule is strict, and it is the only thing keeping this from becoming a junk drawer:
+ * nothing enters unless at least one Add-on must declare or implement it. No validation, no helpers,
+ * no node builtins -- the Add-on states, and Core checks. If something here ever does more than hand
+ * back a constant, it is in the wrong package.
+ */
+import type { PhiServerAddonCapabilities, PhiServerAddonJobHandler, PhiServerSiteAccess } from "./capabilities.js";
+import type { PhiServerCoreCapabilityId, PhiServerServiceKind } from "./core.js";
+import type { PhiServerAddonQueryCatalog } from "./queries.js";
+import type { PhiServerAddonSchemaDescriptor } from "./schema.js";
+export declare const PHI_SERVER_ADDON_MANIFEST_VERSION: 1;
+export declare const PHI_SERVER_ADDON_ABI_VERSION: 1;
+export type PhiServerAddonAuthPolicy = "internal" | "site-user" | "site-admin" | "operator";
+export type PhiServerAddonHttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT";
+export type PhiServerAddonApiRouteDescriptor = {
+    id: string;
+    method: PhiServerAddonHttpMethod;
+    path: string;
+    handler: string;
+    auth: PhiServerAddonAuthPolicy;
+    siteScoped: boolean;
+    bodyLimitBytes?: number;
+    rateLimitClass?: string;
+    timeoutMs?: number;
+};
+export type PhiServerAddonHookDescriptor = {
+    id: string;
+    method: PhiServerAddonHttpMethod;
+    path: string;
+    handler: string;
+    bodyLimitBytes: number;
+    rateLimitClass: string;
+    timeoutMs: number;
+    /**
+     * Whether this hook is told which Site it was called for, through `x-phi-site-key`.
+     *
+     * A hook is unauthenticated by construction -- that is what makes it reachable by a payment provider
+     * or by somebody else's Core. Without a Site it also has no capabilities at all, because every one of
+     * them is Site-scoped, so a hook could until now verify a signature and touch no data. Stating the
+     * Site is what makes a public read possible; it grants nothing else, and the caller is still nobody.
+     *
+     * Optional, and absent means false: a hook written before this field existed had not forgotten it.
+     */
+    siteScoped?: boolean;
+};
+export type PhiServerAddonCapabilityDescriptor = {
+    id: string;
+    interfaceDigest: string;
+};
+/**
+ * One implementation of a Core-owned service kind.
+ *
+ * `providerKey` is what a Storage Profile row stores, so it must stay stable across releases of the
+ * Add-on; `factoryExport` names the entry in the runtime's `serviceFactories` map, which is how Core
+ * reaches the implementation without a dynamic import. The interface digest is checked against what
+ * this release offers, so an Add-on built for an older interface is refused rather than called.
+ */
+export type PhiServerAddonServiceProviderDescriptor = {
+    serviceKind: PhiServerServiceKind;
+    providerKey: string;
+    interfaceDigest: string;
+    factoryExport: string;
+    requiredCoreCapabilities: PhiServerCoreCapabilityId[];
+};
+export type PhiServerAddonJobDescriptor = {
+    id: string;
+    handler: string;
+    /**
+     * How often this job expects to run, for the operator to read -- never a schedule Core keeps.
+     *
+     * phi-server serves from several instances, so an in-process timer would fire once per instance for
+     * one intended run. The operator schedules `phis addon job run`, which is one runner by construction,
+     * and this field tells them what the Add-on had in mind.
+     */
+    suggestedInterval?: "hourly" | "daily" | "weekly";
+};
+/**
+ * One setting an operator may configure for this Add-on.
+ *
+ * Declared so `phis addon config` can list what is configurable, refuse a name nobody declared, and
+ * check a value against its type before it is stored -- the same bargain as the schema and query
+ * descriptors, one step smaller.
+ */
+export type PhiServerAddonSettingDescriptor = {
+    name: string;
+    type: "text" | "integer" | "boolean";
+    /** Shown by the CLI when it lists what an Add-on can be configured with. */
+    description?: string;
+    /** Answered when the operator has set nothing. Absent means the Add-on must handle null. */
+    default?: string | number | boolean;
+};
+/**
+ * Who may hand out one of this Add-on's roles.
+ *
+ * Declared rather than coded, which is the whole point: the Add-on's author decides the policy, and
+ * Core enforces it. A running Add-on cannot rewrite what is in a manifest the digest covers, so "the
+ * Add-on decides who may grant" and "an Add-on cannot widen what it was granted" stop contradicting
+ * each other.
+ *
+ * `siteAccess` names one of the Site's own claims; `role` names another role of this same Add-on. A
+ * Site Admin may always grant any role of any Add-on, so a graph that reaches nobody still has a way in.
+ */
+export type PhiServerAddonRoleGrantPolicy = {
+    siteAccess: PhiServerSiteAccess;
+} | {
+    role: string;
+};
+/**
+ * One role this Add-on defines, in its own vocabulary.
+ *
+ * A role answers "may this person do this at all", where there is no row yet to judge -- may they submit
+ * an offering, open the agent workspace, approve somebody else's work. What may be done to a particular
+ * row stays the row's question: ownership for their own, the group ladder for shared ones.
+ *
+ * Core never interprets the name. It stores assignments, answers `has()`, and enforces `grantableBy`;
+ * what `reviewer` means is the Add-on's business and stays there.
+ */
+export type PhiServerAddonRoleDescriptor = {
+    name: string;
+    description?: string;
+    grantableBy: PhiServerAddonRoleGrantPolicy;
+};
+export type PhiServerAddonManifestV1 = {
+    manifestVersion: typeof PHI_SERVER_ADDON_MANIFEST_VERSION;
+    addonId: string;
+    packageName: string;
+    packageVersion: string;
+    serverAbi: string;
+    capabilities: PhiServerAddonCapabilityDescriptor[];
+    serviceProviders: PhiServerAddonServiceProviderDescriptor[];
+    requiredCoreCapabilities: PhiServerCoreCapabilityId[];
+    apiRoutes: PhiServerAddonApiRouteDescriptor[];
+    hooks: PhiServerAddonHookDescriptor[];
+    jobs: PhiServerAddonJobDescriptor[];
+    /**
+     * What an operator may configure. Absent means nothing is.
+     *
+     * Optional, like every field added after this manifest version was already in the wild. A required
+     * addition would make an installed Add-on's stored manifest unreadable the moment Core is upgraded --
+     * and its author had not forgotten anything, the field did not exist when they built it. The initial
+     * fields may demand an explicit `null`, because no stored manifest predates them; later ones must
+     * define what absence means and accept it.
+     */
+    settings?: PhiServerAddonSettingDescriptor[];
+    /**
+     * The roles this Add-on defines. Absent means it defines none.
+     *
+     * Optional for the same reason `settings` is: a manifest built before the field existed had not
+     * forgotten it. A name is frozen from the first assignment -- renaming one orphans every grant that
+     * points at it, silently, because the grant is stored as text and text does not follow a rename.
+     */
+    roles?: PhiServerAddonRoleDescriptor[];
+    /**
+     * The tables this Add-on owns, or null when it owns none.
+     *
+     * There is no list of migration steps beside it. The descriptor is the desired shape; what has been
+     * applied is recorded in the database, and Core derives the difference.
+     */
+    schema: PhiServerAddonSchemaDescriptor | null;
+    /**
+     * The statements this Add-on may run against its own tables, or null when it runs none.
+     *
+     * Declared for the same reason the tables are: Core derives the SQL once, so what an installed
+     * Add-on can do to its data is readable before it does it, and nothing is assembled per request.
+     *
+     * Optional for the reason `settings` is: it arrived after the manifest version was in the wild.
+     */
+    queries?: PhiServerAddonQueryCatalog | null;
+    /** The version of `schema`, or 0 when there is none. */
+    migrationVersion: number;
+};
+export type PhiServerAddonRequestContext = {
+    addonId: string;
+    requestId: string;
+    method: PhiServerAddonHttpMethod;
+    url: string;
+    headers: Headers;
+    body: Uint8Array;
+    path: string;
+    pathParams: Readonly<Record<string, string>>;
+    site: {
+        id: number;
+        key: string;
+    } | null;
+    actor: {
+        kind: "operator";
+        id: string;
+    } | {
+        kind: "user";
+        id: number;
+    } | {
+        kind: "internal";
+        id: null;
+    } | null;
+    /**
+     * What Core hands this request, bound to the Site and actor above.
+     *
+     * Only what the manifest declared arrives. A capability is not fetched, looked up, or constructed by
+     * the Add-on -- it is here or it is not, and it was already decided before the handler ran.
+     */
+    capabilities: PhiServerAddonCapabilities;
+    signal: AbortSignal;
+};
+export type PhiServerAddonHandler = (context: PhiServerAddonRequestContext) => Promise<Response> | Response;
+/**
+ * A service factory, as the runtime exports it.
+ *
+ * Core states the shape of `config` and `context` per service kind; the manifest's interface digest is
+ * what makes that agreement checkable. The factory receives schema-validated profile configuration and
+ * a restricted context, never a database handle or a general secret accessor.
+ */
+export type PhiServerAddonServiceFactory = (config: unknown, context: unknown) => unknown;
+export type PhiServerAddonRuntimeV1 = {
+    manifest: PhiServerAddonManifestV1;
+    apiHandlers?: Readonly<Record<string, PhiServerAddonHandler>>;
+    hookHandlers?: Readonly<Record<string, PhiServerAddonHandler>>;
+    serviceFactories?: Readonly<Record<string, PhiServerAddonServiceFactory>>;
+    jobHandlers?: Readonly<Record<string, PhiServerAddonJobHandler>>;
+};
+export type PhiServerAddonRuntimeModuleV1 = {
+    phiServerAddon: PhiServerAddonRuntimeV1;
+};
+export type PhiServerAddonBuildEntry = {
+    enabled: boolean;
+    manifestDigest: string;
+    manifest: PhiServerAddonManifestV1;
+    load: () => Promise<PhiServerAddonRuntimeModuleV1>;
+};
+export type PhiServerAddonBuildManifest = Readonly<Record<string, PhiServerAddonBuildEntry>>;
+/**
+ * One installed Add-on, as the operator's desired state records it.
+ *
+ * The entry carries the descriptors as well as the digests. Code and description then travel together
+ * as one per-instance unit, and the database is left to say only whether the Add-on may run. The two
+ * digests bind the three apart: `manifestDigest` covers the descriptors below, `artifactDigest` covers
+ * the file in the install root, and the loader refuses a file that no longer matches.
+ */
+export type PhiServerAddonDesiredStateEntry = {
+    addonId: string;
+    packageName: string;
+    packageVersion: string;
+    manifestDigest: string;
+    /** SHA-256 of the installed artifact, and the cache key its load address carries. */
+    artifactDigest: string;
+    /** The validated descriptors, as read from the artifact at installation. */
+    manifest: PhiServerAddonManifestV1;
+    enabled: boolean;
+};
+export type PhiServerAddonDesiredState = {
+    formatVersion: 1;
+    addons: PhiServerAddonDesiredStateEntry[];
+};

package/dist/addon.js

@@ -0,0 +1,15 @@
+/**
+ * What a phi-server Add-on declares or implements.
+ *
+ * This package exists so an Add-on has something to build against that is not phi-server itself.
+ * phi-server is a private application without an export surface; an Add-on published to a registry
+ * could not depend on it, and a type import into the application's internals would bind an Add-on to a
+ * file path that can move without anybody noticing.
+ *
+ * The admission rule is strict, and it is the only thing keeping this from becoming a junk drawer:
+ * nothing enters unless at least one Add-on must declare or implement it. No validation, no helpers,
+ * no node builtins -- the Add-on states, and Core checks. If something here ever does more than hand
+ * back a constant, it is in the wrong package.
+ */
+export const PHI_SERVER_ADDON_MANIFEST_VERSION = 1;
+export const PHI_SERVER_ADDON_ABI_VERSION = 1;

package/dist/capabilities.d.ts

@@ -0,0 +1,240 @@
+/**
+ * What Core hands an Add-on, as opposed to what it checks about one.
+ *
+ * A capability reaches an Add-on already bound to the request it belongs to: the Site and the acting
+ * user are closed over, not passed in. There is therefore no argument through which an Add-on could
+ * name another Site or ask about somebody else -- the restriction is the shape of the thing rather
+ * than a check inside it. `PhisMediaStorageServiceContext` binds a Provider to its own secret in the
+ * same way and for the same reason.
+ *
+ * Only the capabilities an Add-on's manifest declared, and this release offers, are present. The rest
+ * are absent rather than throwing: an Add-on that reaches for one it did not declare finds `undefined`
+ * at the point where it made the mistake.
+ */
+import type { PhiServerDataCapabilityV1 } from "./queries.js";
+/**
+ * The cumulative group levels, by name.
+ *
+ * Names rather than numbers cross this boundary. The bits are Core's business, an Add-on has no reason
+ * to do arithmetic on them, and a value that never leaves Core is one an Add-on cannot come to depend
+ * on. Each level does everything the one before it does and one thing more.
+ */
+export declare const PHI_SERVER_GROUP_LEVELS: readonly ["member", "author", "editor", "manager"];
+export type PhiServerGroupLevel = (typeof PHI_SERVER_GROUP_LEVELS)[number];
+/**
+ * What an actor wants to do to one row.
+ *
+ * Creating is absent on purpose. There is no row to ask about yet, and whether an Add-on may write at
+ * all is settled before its handler runs.
+ */
+export type PhiServerRowIntent = "read" | "update" | "delete";
+/**
+ * A Site capability an Add-on may ask after, named symbolically.
+ *
+ * An Add-on never states a role flag. Which capabilities are askable is then a decision, and Core is
+ * free to change what a role means without an installed Add-on holding a stale bitmask.
+ */
+export declare const PHI_SERVER_SITE_ACCESS: {
+    readonly siteAdmin: "site-admin";
+    readonly developerTools: "developer-tools";
+    readonly structureAuthoring: "structure-authoring";
+    readonly contentEditing: "content-editing";
+    readonly publishing: "publishing";
+    readonly siteMedia: "site-media";
+    readonly support: "support";
+    readonly accounting: "accounting";
+};
+export type PhiServerSiteAccess = (typeof PHI_SERVER_SITE_ACCESS)[keyof typeof PHI_SERVER_SITE_ACCESS];
+/**
+ * The authorization capability: `@phis/server/authorization:v1`.
+ *
+ * It answers questions and grants nothing. There is no operation here that changes a role, a
+ * membership, or an owner, and there must not be one -- a single capability declaration would then be
+ * permission to rewrite the authorization model rather than permission to consult it.
+ *
+ * `mayActOnRow` is the reason this exists. The scope columns on an Add-on's tables are Core's:
+ * `ownerScoped` and `groupScoped` mean Core wrote `owner_user_id` and `group_id`, so Core can read
+ * them back and apply the ladder itself. The Add-on names a row and an intent; it never reproduces the
+ * rule, which is what keeps one rule from becoming one implementation per package.
+ *
+ * A table that is neither owner- nor group-scoped has nothing for this to decide and always answers
+ * false: absence of a scope is not absence of a restriction.
+ */
+export type PhiServerAuthorizationCapabilityV1 = {
+    /**
+     * Whether the acting user may do this to one row of one of this Add-on's own tables.
+     *
+     * `table` is a table of this Add-on's schema under the name its descriptor gave it; another
+     * Add-on's table is not addressable, because the schema is derived from the caller rather than
+     * taken from the argument. A row that does not exist answers false rather than raising -- "may I"
+     * about something absent has no other honest answer.
+     */
+    mayActOnRow(input: {
+        table: string;
+        id: number | string;
+        intent: PhiServerRowIntent;
+    }): Promise<boolean>;
+    /** The level the acting user effectively holds in one group, or null when they are not in it. */
+    groupLevel(groupId: number): Promise<PhiServerGroupLevel | null>;
+    /** Whether the acting user holds one Site capability, with the Core Admin override applied. */
+    hasSiteAccess(access: PhiServerSiteAccess): Promise<boolean>;
+};
+/**
+ * The capabilities a handler may find on its context, keyed as the Core catalog keys them.
+ *
+ * Optional throughout: presence follows the manifest, and a capability this release does not offer
+ * stops the Add-on at the dispatcher rather than arriving as a broken object.
+ */
+export type PhiServerAddonCapabilities = {
+    authorization?: PhiServerAuthorizationCapabilityV1;
+    data?: PhiServerDataCapabilityV1;
+    storage?: PhiServerStorageCapabilityV1;
+    secrets?: PhiServerSecretsCapabilityV1;
+    groups?: PhiServerGroupsCapabilityV1;
+    settings?: PhiServerSettingsCapabilityV1;
+    roles?: PhiServerRolesCapabilityV1;
+};
+/**
+ * The roles capability: `@phis/server/roles:v1`.
+ *
+ * Answers whether the acting user holds one of the roles this Add-on declared, and nothing about who
+ * they are. There is no writer, for the reason `settings:v1` and `secrets:v1` have none: an Add-on able
+ * to grant its own roles could grant itself whatever those roles guard.
+ *
+ * Only declared roles are answered. A grant stored against a name this release no longer declares is not
+ * handed over, the same way a stored setting nobody declared is not -- so an Add-on never sees a role it
+ * does not know, whatever has accumulated across versions.
+ */
+export type PhiServerRolesCapabilityV1 = {
+    /** Whether the acting user holds this role here. False when nobody is acting. */
+    has(role: string): Promise<boolean>;
+    /** Every declared role the acting user holds, in declaration order. */
+    all(): Promise<readonly string[]>;
+};
+/**
+ * The storage capability: `@phis/server/storage:v1`.
+ *
+ * A private object store, bound to this Add-on and this Site. Keys are the Add-on's own and relative:
+ * Core puts them under a prefix it derives, and never hands the physical key back. An Add-on therefore
+ * cannot store an address, and cannot reach another Add-on's objects or another Site's by constructing
+ * one -- the same rule the install root follows, where a stored string never becomes an import
+ * specifier.
+ *
+ * This is not the Media library. Assets that a person uploads, browses, and references belong in a
+ * Media Space with its folders, quotas and delivery policies. This is for what an Add-on keeps for
+ * itself: a release artifact, a generated preview, an export waiting to be fetched.
+ */
+export type PhiServerStorageCapabilityV1 = {
+    put(input: {
+        key: string;
+        body: Uint8Array;
+        contentType: string;
+    }): Promise<{
+        key: string;
+        byteSize: number;
+    }>;
+    /** Null rather than throwing for an object that is not there. */
+    get(key: string): Promise<{
+        body: Uint8Array;
+        contentType: string;
+    } | null>;
+    head(key: string): Promise<{
+        key: string;
+        byteSize: number;
+        contentType: string;
+    } | null>;
+    /** Whether an object was removed. Removing what is not there is not an error. */
+    remove(key: string): Promise<boolean>;
+    /** The Add-on's own keys under a prefix, relative as they were given. */
+    list(prefix?: string): Promise<string[]>;
+};
+/**
+ * The secrets capability: `@phis/server/secrets:v1`.
+ *
+ * An Add-on reads the secrets an operator set for it and no others. The owner is bound here, so there
+ * is no argument through which another Add-on's reference could be named -- the resolver enforces the
+ * same rule a second time, because the two are different kinds of mistake.
+ *
+ * There is no writer. An operator sets a secret with `phis secret set`; a package that could write its
+ * own would be a package that could plant one.
+ */
+export type PhiServerSecretsCapabilityV1 = {
+    /** The value, or null when the operator has not configured it. */
+    read(name: string): Promise<string | null>;
+};
+/**
+ * What an Add-on may learn about a person.
+ *
+ * Deliberately the same projection one group member gets of another: a display name, a company only
+ * where the group discloses it, and never an address. An Add-on renders "listed by" and nothing more.
+ */
+export type PhiServerUserProjection = {
+    userId: number;
+    displayName: string | null;
+    companyName: string | null;
+};
+/**
+ * The groups capability: `@phis/server/groups:v1`.
+ *
+ * Group facts. What follows from them -- may this actor do this -- is `authorization:v1`.
+ *
+ * Every answer is bounded by the acting user: an Add-on sees the groups its actor is in and the people
+ * its actor could already see in them. It cannot become a directory of a Site's users, because there is
+ * no question here that reaches past the actor's own membership.
+ */
+export type PhiServerGroupsCapabilityV1 = {
+    /** The groups the acting user belongs to on this Site. */
+    myGroups(): Promise<Array<{
+        id: number;
+        key: string;
+        name: string;
+    }>>;
+    /** The members of one group the acting user is in, projected as a member sees them. */
+    members(groupId: number): Promise<PhiServerUserProjection[]>;
+    /**
+     * One person, if the acting user shares a group with them.
+     *
+     * Null otherwise, and null is the whole point: it is what stops a row's owner id from becoming a
+     * lookup into everybody.
+     */
+    user(userId: number): Promise<PhiServerUserProjection | null>;
+};
+/**
+ * The settings capability: `@phis/server/settings:v1`.
+ *
+ * What an operator configures and an Add-on reads: a commission rate, a moderation switch, an endpoint.
+ * Distinct from `secrets:v1` on purpose -- a percentage is not a credential, and asking the secret store
+ * to hold one would make "what is configured here" unreadable to the operator who configured it.
+ *
+ * There is no writer. Settings are the operator's, set with `phis addon config set`, and an Add-on that
+ * could write its own would be able to widen what it was given.
+ *
+ * A setting the operator has not set answers with the declared default, so an Add-on has one shape to
+ * handle rather than two, and `null` means genuinely unset with no default to fall back to.
+ */
+export type PhiServerSettingsCapabilityV1 = {
+    read(name: string): Promise<string | number | boolean | null>;
+    all(): Promise<Readonly<Record<string, string | number | boolean | null>>>;
+};
+/**
+ * What a job receives.
+ *
+ * No request, no headers, and above all no actor: a job is the Add-on acting on its own data, not a
+ * person acting through it. That is why the row-level ladder does not apply inside one, and why a job
+ * is reachable only from `phis addon job run` and never from a route -- an Add-on that could start its
+ * own job from a request would have built itself a way around the ladder.
+ */
+export type PhiServerAddonJobContext = {
+    addonId: string;
+    jobId: string;
+    /** This run, for correlating what the job logs with what the operator started. */
+    runId: string;
+    /** The Site this run is for. A job always runs against exactly one. */
+    site: {
+        id: number;
+        key: string;
+    };
+    capabilities: PhiServerAddonCapabilities;
+    signal: AbortSignal;
+};
+export type PhiServerAddonJobHandler = (context: PhiServerAddonJobContext) => Promise<void> | void;

package/dist/capabilities.js

@@ -0,0 +1,37 @@
+/**
+ * What Core hands an Add-on, as opposed to what it checks about one.
+ *
+ * A capability reaches an Add-on already bound to the request it belongs to: the Site and the acting
+ * user are closed over, not passed in. There is therefore no argument through which an Add-on could
+ * name another Site or ask about somebody else -- the restriction is the shape of the thing rather
+ * than a check inside it. `PhisMediaStorageServiceContext` binds a Provider to its own secret in the
+ * same way and for the same reason.
+ *
+ * Only the capabilities an Add-on's manifest declared, and this release offers, are present. The rest
+ * are absent rather than throwing: an Add-on that reaches for one it did not declare finds `undefined`
+ * at the point where it made the mistake.
+ */
+/**
+ * The cumulative group levels, by name.
+ *
+ * Names rather than numbers cross this boundary. The bits are Core's business, an Add-on has no reason
+ * to do arithmetic on them, and a value that never leaves Core is one an Add-on cannot come to depend
+ * on. Each level does everything the one before it does and one thing more.
+ */
+export const PHI_SERVER_GROUP_LEVELS = ["member", "author", "editor", "manager"];
+/**
+ * A Site capability an Add-on may ask after, named symbolically.
+ *
+ * An Add-on never states a role flag. Which capabilities are askable is then a decision, and Core is
+ * free to change what a role means without an installed Add-on holding a stale bitmask.
+ */
+export const PHI_SERVER_SITE_ACCESS = {
+    siteAdmin: "site-admin",
+    developerTools: "developer-tools",
+    structureAuthoring: "structure-authoring",
+    contentEditing: "content-editing",
+    publishing: "publishing",
+    siteMedia: "site-media",
+    support: "support",
+    accounting: "accounting",
+};

package/dist/core.d.ts

@@ -0,0 +1,66 @@
+/**
+ * What Core offers, named once so both sides can spell it the same way.
+ *
+ * An Add-on declares which Core capabilities it needs and which Core-owned service kinds it
+ * implements. Those names are an agreement between two artifacts that ship separately, which is
+ * exactly what this package is for -- and until they lived here, an Add-on author had to read them out
+ * of phi-server, a private application they never receive. The S3 Storage Add-on carried the media
+ * storage digest as a copied hex literal for that reason.
+ *
+ * This list is a promise, not a plan. A capability appears here when Core delivers it, never before:
+ * an Add-on that finds a name here must be able to rely on it. `images:v1` is therefore absent.
+ *
+ * Still no node builtins. The digests are stated rather than derived, so a manifest stays readable
+ * without hashing anything -- Core recomputes them and checks, which is where that belongs.
+ */
+/** The Core capabilities an Add-on may require. */
+export declare const PHI_SERVER_CORE_CAPABILITIES: {
+    readonly authentication: "@phis/server/authentication:v1";
+    /**
+     * "May this actor", in all three of its sources: does the row belong to them, what level do they
+     * hold in its group, and what may they do on this Site at all. It is spelled out rather than
+     * shortened to `auth` because the shortening would sit one letter away from `authentication` and
+     * mean the opposite half of the same word.
+     */
+    readonly authorization: "@phis/server/authorization:v1";
+    /** Running the queries the manifest declared against this Add-on's own tables. */
+    readonly data: "@phis/server/data:v1";
+    readonly threads: "@phis/server/threads:v1";
+    readonly resourceLinks: "@phis/server/resource-links:v1";
+    readonly support: "@phis/server/support:v1";
+    /** Group facts -- which groups exist, who is in them. What follows from them is `authorization`. */
+    readonly groups: "@phis/server/groups:v1";
+    readonly storage: "@phis/server/storage:v1";
+    /** Reading the secrets an operator set for this Add-on, and no others. */
+    readonly secrets: "@phis/server/secrets:v1";
+    /** Reading what an operator configured for this Add-on on this Site. */
+    readonly settings: "@phis/server/settings:v1";
+    /** Whether the acting user holds one of this Add-on's own declared roles. */
+    readonly roles: "@phis/server/roles:v1";
+};
+export type PhiServerCoreCapabilityId = (typeof PHI_SERVER_CORE_CAPABILITIES)[keyof typeof PHI_SERVER_CORE_CAPABILITIES];
+/**
+ * The Core-owned service kinds an Add-on may implement.
+ *
+ * A service kind is not a capability. A capability is something Core offers an Add-on; a service kind
+ * is something Core already owns and an Add-on supplies an implementation of -- S3 for Media Storage,
+ * LDAP for a Directory. Core keeps selecting the configured implementation itself.
+ */
+export declare const PHI_SERVER_SERVICE_KINDS: {
+    readonly mediaStorage: "@phis/server/service/media-storage";
+    readonly directory: "@phis/server/service/directory";
+};
+export type PhiServerServiceKind = (typeof PHI_SERVER_SERVICE_KINDS)[keyof typeof PHI_SERVER_SERVICE_KINDS];
+/**
+ * The digest of the interface each service kind currently has.
+ *
+ * An Add-on puts the digest of the interface it was built against into its manifest. Core compares it
+ * with what this release offers and refuses the Add-on when they differ -- at install, with the value
+ * quoted back, rather than at the first call. Whoever changes the shape of an interface raises its
+ * version and replaces the digest here, and every Add-on built against the old one is refused.
+ *
+ * The digest is `sha256("phi-server-service-kind:<kind>:v<interface version>")`. That recipe is
+ * documented for whoever has to produce the next value; nothing needs to run it to read a manifest.
+ */
+export declare const PHI_SERVER_SERVICE_INTERFACE_VERSIONS: Readonly<Record<PhiServerServiceKind, number>>;
+export declare const PHI_SERVER_SERVICE_INTERFACE_DIGESTS: Readonly<Record<PhiServerServiceKind, string>>;