@phis/contracts 0.2.0

package/dist/core.js

@@ -0,0 +1,70 @@
+/**
+ * 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 const PHI_SERVER_CORE_CAPABILITIES = {
+    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.
+     */
+    authorization: "@phis/server/authorization:v1",
+    /** Running the queries the manifest declared against this Add-on's own tables. */
+    data: "@phis/server/data:v1",
+    threads: "@phis/server/threads:v1",
+    resourceLinks: "@phis/server/resource-links:v1",
+    support: "@phis/server/support:v1",
+    /** Group facts -- which groups exist, who is in them. What follows from them is `authorization`. */
+    groups: "@phis/server/groups:v1",
+    storage: "@phis/server/storage:v1",
+    /** Reading the secrets an operator set for this Add-on, and no others. */
+    secrets: "@phis/server/secrets:v1",
+    /** Reading what an operator configured for this Add-on on this Site. */
+    settings: "@phis/server/settings:v1",
+    /** Whether the acting user holds one of this Add-on's own declared roles. */
+    roles: "@phis/server/roles:v1",
+};
+/**
+ * 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 const PHI_SERVER_SERVICE_KINDS = {
+    mediaStorage: "@phis/server/service/media-storage",
+    directory: "@phis/server/service/directory",
+};
+/**
+ * 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 const PHI_SERVER_SERVICE_INTERFACE_VERSIONS = {
+    [PHI_SERVER_SERVICE_KINDS.mediaStorage]: 1,
+    [PHI_SERVER_SERVICE_KINDS.directory]: 1,
+};
+export const PHI_SERVER_SERVICE_INTERFACE_DIGESTS = {
+    [PHI_SERVER_SERVICE_KINDS.mediaStorage]: "45a871522511f7d77841ca8dd0113b423b3cfd4cb921f143cd1d3d116cab6952",
+    [PHI_SERVER_SERVICE_KINDS.directory]: "2cac7397c7beb1b8e71fc67f5cae3be89182dddf096895570a15deafa1adbfc9",
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./addon.js";
+export * from "./capabilities.js";
+export * from "./core.js";
+export * from "./media-storage.js";
+export * from "./queries.js";
+export * from "./schema.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./addon.js";
+export * from "./capabilities.js";
+export * from "./core.js";
+export * from "./media-storage.js";
+export * from "./queries.js";
+export * from "./schema.js";

package/dist/media-storage.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The Media Storage service kind, as a Provider implements it.
+ *
+ * Core owns the upload lifecycle -- `init` and `finalize` stay Core routes for every Provider -- and a
+ * Provider states how a body is to be delivered and settles the staged object once it lands. Nothing
+ * here reaches a database, a request, or a secret store: the Provider gets configuration and a context,
+ * and answers about objects.
+ */
+export declare const PHI_LOCAL_MEDIA_STORAGE_PROVIDER_ID: "@phis/server/storage-local";
+export type PhisMediaStorageProviderId = `@${string}/${string}`;
+export type PhisMediaStorageConfig = {
+    storageKeyPrefix: string;
+    rootDir: string;
+};
+export type PhisMediaObjectInput = {
+    storageKey: string;
+    body: Buffer | Uint8Array;
+    contentType: string;
+    metadata?: Record<string, string>;
+};
+export type PhisMediaObjectStreamInput = {
+    storageKey: string;
+    body: ReadableStream<Uint8Array>;
+    contentType: string;
+    metadata?: Record<string, string>;
+};
+export type PhisMediaObjectHead = {
+    storageKey: string;
+    byteSize: number;
+    contentType: string;
+    etag: string;
+    metadata: Record<string, string>;
+    lastModifiedAt: string;
+};
+/**
+ * How a Client is to deliver one upload body.
+ *
+ * This is the Provider-neutral half of the upload contract: init answers with a plan, and a generic
+ * executor carries it out without knowing which Provider issued it. Before the plan existed the rule
+ * "one PUT, to our own route, with the file's content type" lived only in the Client, which is exactly
+ * what a Provider that takes the body directly cannot satisfy.
+ *
+ * The union is meant to grow. A Provider that needs several requests for one body -- S3 multipart --
+ * adds a variant here rather than a second upload lifecycle, and the executor refuses a `kind` it does
+ * not know instead of falling back to a PUT that would go to the wrong place. What a Provider needs
+ * reported back once the body has landed travels through `completion`, opaque to Core.
+ */
+export type PhiMediaUploadPlan = {
+    kind: "proxy-stream";
+    /** A Core route on this origin: the body streams through the Server, with the session cookie. */
+    url: string;
+    method: "PUT";
+    headers?: Record<string, string>;
+} | {
+    kind: "presigned-put";
+    /** The Provider's own endpoint. Site credentials must never be attached to it. */
+    url: string;
+    method: "PUT";
+    headers: Record<string, string>;
+    expiresAt: string;
+};
+export type PhiMediaUploadPlanKindKey = PhiMediaUploadPlan["kind"];
+export type PhiMediaUploadPlanInput = {
+    token: string;
+    storageKey: string;
+    contentType: string;
+    sizeBytes: number;
+    expiresAt: string;
+    /**
+     * Where Core itself receives a body, for a Provider that cannot take one directly.
+     *
+     * Core owns its route table, so the address is handed to the adapter rather than assembled by it.
+     */
+    proxyUploadUrl: string;
+};
+export type PhiMediaUploadCompletionInput = {
+    storageKey: string;
+    /** Whatever the plan's issuer asked the Client to bring back. Core passes it through unread. */
+    completion?: unknown;
+};
+export interface PhisMediaStorageAdapter {
+    putObject(input: PhisMediaObjectInput): Promise<PhisMediaObjectHead>;
+    putObjectStream(input: PhisMediaObjectStreamInput): Promise<PhisMediaObjectHead>;
+    getObject(storageKey: string): Promise<Buffer | null>;
+    /**
+     * The first bytes of an object, for deciding what it actually is without moving it.
+     *
+     * Separate from `getObject` because the answer needs a few kilobytes and an object may be gigabytes:
+     * a Provider that stores remotely reads a range rather than the body, so identifying an upload costs
+     * one small request whatever was uploaded.
+     */
+    readObjectHead(storageKey: string, byteLength: number): Promise<Buffer | null>;
+    /**
+     * Settles a staged object onto its final key without moving it through Core.
+     *
+     * `finalize` used to read the whole staged body and write it back, which is a download plus an upload
+     * of every byte for a Provider that stores remotely -- impossible for a multipart object and wasteful
+     * for anything large. A Provider that can copy in place does; the Local adapter copies on disk.
+     */
+    copyObject(input: {
+        sourceKey: string;
+        targetKey: string;
+        contentType: string;
+        metadata?: Record<string, string>;
+    }): Promise<PhisMediaObjectHead | null>;
+    headObject(storageKey: string): Promise<PhisMediaObjectHead | null>;
+    deleteObject(storageKey: string): Promise<boolean>;
+    listPrefix(prefix: string): Promise<PhisMediaObjectHead[]>;
+    /** States how the Client is to deliver this body. */
+    createUploadPlan(input: PhiMediaUploadPlanInput): Promise<PhiMediaUploadPlan>;
+    /**
+     * Settles the staged object once the Client says it is done, and answers what actually landed.
+     *
+     * `null` means nothing is there, which is how Core tells an unfinished upload from a finished one.
+     * A Provider that assembles parts does it here; one that received the whole body simply looks.
+     */
+    completeUpload(input: PhiMediaUploadCompletionInput): Promise<PhisMediaObjectHead | null>;
+    /**
+     * States which browser origins may deliver a body straight to this Provider.
+     *
+     * A presigned plan is a cross-origin request, so without this the browser refuses to send it and no
+     * server ever learns why. The origins are Core's to know -- they are the Sites the Provider serves --
+     * and applying them is the Provider's, because only it knows how its storage expresses the rule.
+     *
+     * An empty list withdraws the permission rather than widening it. A Provider a browser never
+     * addresses directly, such as the Local one, implements this as a no-op; there is no capability flag
+     * to check, because a Provider that cannot say no to a body it never receives has nothing to say.
+     */
+    applyCorsPolicy(origins: readonly string[]): Promise<void>;
+    /**
+     * What makes two Storage Profiles the same physical storage.
+     *
+     * A CORS rule belongs to the storage, not to the Site, so two Sites sharing one bucket need one rule
+     * carrying both origins -- and applying each Site's rule in turn would leave whichever went last.
+     * Core cannot work this out: which configuration fields identify a storage and which merely divide
+     * it is the Provider's own business, and a prefix separates Sites inside one storage rather than
+     * making two.
+     *
+     * The value is opaque to Core and is only ever compared, so it must be stable across releases and
+     * must never contain a credential.
+     */
+    storageIdentity(): string;
+}
+/**
+ * What a Provider factory is handed besides its configuration.
+ *
+ * A Provider needs credentials and must not be able to reach anything else. The context therefore
+ * carries no database handle and no general secret accessor: `readSecret` resolves the one reference
+ * its own Storage Profile names, and there is no argument that could make it resolve another.
+ *
+ * It is asynchronous because a secret is fetched, and lazy because a Provider that never uploads
+ * anything should never need one. The Local Provider ignores the context entirely.
+ */
+export type PhisMediaStorageServiceContext = {
+    providerId: PhisMediaStorageProviderId;
+    /** The Site whose profile this is, for diagnostics; not an authorization input. */
+    siteKey: string | null;
+    /** The profile's own secret, or null when the profile names none. */
+    readSecret: () => Promise<string | null>;
+};

package/dist/media-storage.js

@@ -0,0 +1,9 @@
+/**
+ * The Media Storage service kind, as a Provider implements it.
+ *
+ * Core owns the upload lifecycle -- `init` and `finalize` stay Core routes for every Provider -- and a
+ * Provider states how a body is to be delivered and settles the staged object once it lands. Nothing
+ * here reaches a database, a request, or a secret store: the Provider gets configuration and a context,
+ * and answers about objects.
+ */
+export const PHI_LOCAL_MEDIA_STORAGE_PROVIDER_ID = "@phis/server/storage-local";

package/dist/queries.d.ts

@@ -0,0 +1,171 @@
+/**
+ * What an Add-on says about the queries it runs.
+ *
+ * The same bargain as the schema descriptor, one step further: an Add-on ships no SQL for its tables
+ * and none for its statements either. It declares named queries, Core derives the statements once, and
+ * the Add-on invokes them by name with parameters. Nothing is assembled at request time, so `phis-cli`
+ * can show an operator every statement an installed Add-on is able to run -- which a query builder
+ * handed out at runtime could never do.
+ *
+ * The vocabulary is poorer than SQL on purpose, and poorer than the schema descriptor's in one further
+ * way: there are no joins. A join to a Core table would make the kernel's shape an Add-on's dependency,
+ * and a join between two Add-ons' tables is already forbidden. A query that needs one is either cut
+ * wrong or wants a Core service.
+ */
+/** What a declared parameter holds. Narrower than the column vocabulary: these travel as values. */
+export type PhiServerAddonQueryParameterType = "integer" | "bigInteger" | "text" | "boolean" | "instant" | "uuid";
+export type PhiServerAddonQueryParameter = {
+    name: string;
+    type: PhiServerAddonQueryParameterType;
+    /** Whether the caller may pass null. Absent means it may not. */
+    nullable?: boolean;
+};
+/**
+ * Where a value in a query comes from.
+ *
+ * `actor` is the point of the list. "My rows" is the commonest filter there is, and letting an Add-on
+ * pass the acting user's id would mean trusting it to pass the right one. Core substitutes its own
+ * bound actor, so the query cannot be aimed at somebody else -- the same reason the capability closes
+ * over the Site instead of taking it as an argument.
+ */
+export type PhiServerAddonQueryValue = {
+    kind: "parameter";
+    name: string;
+} | {
+    kind: "literal";
+    value: string | number | boolean;
+}
+/** The acting user's id, substituted by Core. Null when nobody is acting, which matches nothing. */
+ | {
+    kind: "actor";
+} | {
+    kind: "now";
+};
+export type PhiServerAddonQueryComparison = "=" | "<>" | "<" | "<=" | ">" | ">=";
+/**
+ * A condition, as a tree of a closed set of shapes.
+ *
+ * No expressions, no functions, no pattern matching. `LIKE` is absent for the reason regular
+ * expressions are absent from the schema descriptor: its escaping and collation behaviour differ
+ * between database systems, and taking it would buy back the dependency this exists to remove. Text
+ * search is a Core service, not a query the Add-on writes.
+ */
+export type PhiServerAddonQueryCondition = {
+    kind: "compare";
+    column: string;
+    operator: PhiServerAddonQueryComparison;
+    value: PhiServerAddonQueryValue;
+} | {
+    kind: "isNull";
+    column: string;
+    negated?: boolean;
+} | {
+    kind: "in";
+    column: string;
+    values: PhiServerAddonQueryValue[];
+} | {
+    kind: "all";
+    conditions: PhiServerAddonQueryCondition[];
+} | {
+    kind: "any";
+    conditions: PhiServerAddonQueryCondition[];
+};
+export type PhiServerAddonQueryOrdering = {
+    column: string;
+    direction: "asc" | "desc";
+};
+export type PhiServerAddonQueryAssignment = {
+    column: string;
+    value: PhiServerAddonQueryValue;
+};
+/**
+ * Reading rows of one of this Add-on's tables.
+ *
+ * `limit` is required and bounded. An unbounded read is how an Add-on takes an instance down with a
+ * table that grew, and "the caller will pass a sensible one" is not a bound.
+ */
+export type PhiServerAddonSelectQueryDescriptor = {
+    kind: "select";
+    name: string;
+    table: string;
+    /** Absent means every declared column. Core's scope columns are never among them. */
+    columns?: string[];
+    where?: PhiServerAddonQueryCondition;
+    orderBy?: PhiServerAddonQueryOrdering[];
+    limit: number;
+    offsetParameter?: string;
+};
+/**
+ * Adding a row.
+ *
+ * The scope columns are absent by construction: `siteScoped`, `groupScoped` and `ownerScoped` mean Core
+ * writes them, so there is nowhere here to name one. Core fills the Site and the actor from the bound
+ * context; the group comes from a declared parameter because a row can belong to any group the actor is
+ * in, and Core refuses one they are not.
+ */
+export type PhiServerAddonInsertQueryDescriptor = {
+    kind: "insert";
+    name: string;
+    table: string;
+    values: PhiServerAddonQueryAssignment[];
+    /** Names the parameter carrying the group id, and is required for a group-scoped table. */
+    groupParameter?: string;
+};
+/**
+ * Changing or removing exactly one row, addressed by its primary key.
+ *
+ * There is no `where` here and no bulk form. Core checks `mayActOnRow` against the row before it
+ * writes, and a check that has to be remembered is one that eventually is not -- so the shape makes it
+ * unskippable rather than the discipline. An Add-on that needs to rewrite many rows at once is doing
+ * something Core should be doing for it.
+ */
+export type PhiServerAddonUpdateQueryDescriptor = {
+    kind: "update";
+    name: string;
+    table: string;
+    set: PhiServerAddonQueryAssignment[];
+    /** Names the parameter carrying the row's primary key value. */
+    idParameter: string;
+};
+export type PhiServerAddonDeleteQueryDescriptor = {
+    kind: "delete";
+    name: string;
+    table: string;
+    idParameter: string;
+};
+export type PhiServerAddonQueryDescriptor = PhiServerAddonSelectQueryDescriptor | PhiServerAddonInsertQueryDescriptor | PhiServerAddonUpdateQueryDescriptor | PhiServerAddonDeleteQueryDescriptor;
+/** The most rows one declared `select` may return, whatever it asks for. */
+export declare const PHI_SERVER_ADDON_QUERY_MAX_LIMIT: 500;
+export type PhiServerAddonQueryCatalog = {
+    parameters: Readonly<Record<string, PhiServerAddonQueryParameter[]>>;
+    queries: PhiServerAddonQueryDescriptor[];
+};
+export type PhiServerAddonQueryArguments = Readonly<Record<string, string | number | boolean | null>>;
+export type PhiServerAddonQueryRow = Readonly<Record<string, unknown>>;
+/**
+ * Running the declared queries: `@phis/server/data:v1`.
+ *
+ * Every call names a query the manifest declared. There is no method that takes SQL, a table, or a
+ * condition, because an Add-on that could pass one of those at request time would be holding a
+ * database handle with extra steps.
+ *
+ * A mutation answers how many rows it touched. Zero from an `update` or `delete` means the row was not
+ * there or was not the caller's to change, and the two are deliberately the same answer: telling them
+ * apart would report the existence of a row the caller may not have.
+ */
+export type PhiServerDataCapabilityV1 = {
+    select(name: string, args?: PhiServerAddonQueryArguments): Promise<PhiServerAddonQueryRow[]>;
+    /** Returns the inserted row, with the scope columns Core filled in. */
+    insert(name: string, args?: PhiServerAddonQueryArguments): Promise<PhiServerAddonQueryRow | null>;
+    update(name: string, args?: PhiServerAddonQueryArguments): Promise<number>;
+    delete(name: string, args?: PhiServerAddonQueryArguments): Promise<number>;
+    /**
+     * One unit of work. Everything inside commits together or not at all.
+     *
+     * The handle offers the same four operations and nothing else -- no commit, no rollback, no
+     * savepoint. Returning ends the transaction; throwing rolls it back. An Add-on cannot leave one
+     * open, because it never holds the thing that would stay open.
+     */
+    transaction<T>(body: (tx: PhiServerDataTransactionV1) => Promise<T>): Promise<T>;
+};
+export type PhiServerDataTransactionV1 = Omit<PhiServerDataCapabilityV1, "transaction">;

package/dist/queries.js

@@ -0,0 +1,16 @@
+/**
+ * What an Add-on says about the queries it runs.
+ *
+ * The same bargain as the schema descriptor, one step further: an Add-on ships no SQL for its tables
+ * and none for its statements either. It declares named queries, Core derives the statements once, and
+ * the Add-on invokes them by name with parameters. Nothing is assembled at request time, so `phis-cli`
+ * can show an operator every statement an installed Add-on is able to run -- which a query builder
+ * handed out at runtime could never do.
+ *
+ * The vocabulary is poorer than SQL on purpose, and poorer than the schema descriptor's in one further
+ * way: there are no joins. A join to a Core table would make the kernel's shape an Add-on's dependency,
+ * and a join between two Add-ons' tables is already forbidden. A query that needs one is either cut
+ * wrong or wants a Core service.
+ */
+/** The most rows one declared `select` may return, whatever it asks for. */
+export const PHI_SERVER_ADDON_QUERY_MAX_LIMIT = 500;

package/dist/schema.d.ts

@@ -0,0 +1,173 @@
+/**
+ * What an Add-on says about the tables it owns.
+ *
+ * An Add-on ships no SQL. It states the shape it wants and Core derives the statements, which is what
+ * lets an Add-on outlive a change of database system and what turns most of the rules in section 15 of
+ * the Add-on contract from something checked afterwards into something that cannot be expressed at all.
+ *
+ * The vocabulary is deliberately poorer than SQL. There are no triggers, functions, views, expression or
+ * partial indexes, and no free-form check, because each of those would be SQL again and would put back
+ * exactly what this removes. An Add-on that needs one of them is either cut wrong or needs a Core
+ * service.
+ */
+export declare const PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION: 1;
+/**
+ * What a column holds, said abstractly so Core can map it.
+ *
+ * `identity` is a generated key and may appear only in a primary key; the width is Core's business, not
+ * the Add-on's.
+ */
+export type PhiServerAddonColumnType = "identity" | "smallInteger" | "integer" | "bigInteger" | "text" | "string" | "boolean" | "instant" | "json" | "uuid" | "binary";
+/** The closed vocabulary a default may be drawn from. Anything wider would be an expression. */
+export type PhiServerAddonColumnDefault = {
+    kind: "literal";
+    value: string | number | boolean;
+} | {
+    kind: "now";
+};
+/**
+ * A Core table an Add-on may point at, named symbolically.
+ *
+ * An Add-on never writes `phis.sites(id)`. Core is then free to rename its own tables without breaking
+ * an installed Add-on, and which Core tables are referenceable becomes a decision instead of a
+ * consequence of what happens to be reachable.
+ *
+ * A group exists only inside a Site, so a table pointing at `core.group` must be Site-scoped and Core
+ * binds the pair rather than the id alone. Core never references a group any other way, and an Add-on
+ * that could would be able to name a group belonging to a different Site.
+ */
+export declare const PHI_SERVER_ADDON_CORE_REFERENCES: {
+    readonly site: "core.site";
+    readonly user: "core.user";
+    readonly group: "core.group";
+};
+export type PhiServerAddonCoreReference = (typeof PHI_SERVER_ADDON_CORE_REFERENCES)[keyof typeof PHI_SERVER_ADDON_CORE_REFERENCES];
+/**
+ * A delete rule, offered as two values and no third.
+ *
+ * An Add-on must not be able to refuse a Core deletion: an operator who cannot delete a user because an
+ * installed package forbids it is looking at a constraint error from code they may not know they have.
+ */
+export type PhiServerAddonDeleteRule = "cascade" | "setNull";
+export type PhiServerAddonValueColumnDescriptor = {
+    name: string;
+    type: PhiServerAddonColumnType;
+    /** Required for `string`, forbidden otherwise. */
+    maxLength?: number;
+    nullable?: boolean;
+    unique?: boolean;
+    default?: PhiServerAddonColumnDefault;
+};
+/**
+ * A column that points at something, and therefore has no type of its own.
+ *
+ * Its type is whatever it references, which is Core's to know: a Core key may be a different width than
+ * an Add-on would guess, and stating one here would be a guess that compiles. This is also the only
+ * shape a foreign key takes -- there is no separate list of them, and no composite key, because a
+ * reference that needs two columns is pointing at something an Add-on should not be reaching into.
+ */
+export type PhiServerAddonReferenceColumnDescriptor = {
+    name: string;
+    /** A Core table under its symbolic name, or one of this Add-on's own tables. */
+    references: PhiServerAddonCoreReference | {
+        table: string;
+    };
+    nullable?: boolean;
+    unique?: boolean;
+    /** `setNull` requires a nullable column. */
+    onDelete: PhiServerAddonDeleteRule;
+};
+export type PhiServerAddonColumnDescriptor = PhiServerAddonValueColumnDescriptor | PhiServerAddonReferenceColumnDescriptor;
+/**
+ * A constraint, in structured form.
+ *
+ * These belong in the first version of a descriptor and are the one part that does not wait: a column
+ * can be added later and an index can be added later, but a constraint added later meets the rows that
+ * are already there.
+ *
+ * Regular expressions are absent on purpose. Their syntax differs between database systems, and taking
+ * them would buy back the dependency this file exists to remove.
+ */
+export type PhiServerAddonTableConstraintDescriptor = {
+    kind: "range";
+    name: string;
+    column: string;
+    min?: number;
+    max?: number;
+    exclusiveMin?: boolean;
+    exclusiveMax?: boolean;
+} | {
+    kind: "enumeration";
+    name: string;
+    column: string;
+    values: string[];
+} | {
+    kind: "notEmpty";
+    name: string;
+    column: string;
+} | {
+    kind: "columnComparison";
+    name: string;
+    left: string;
+    operator: "<" | "<=" | ">" | ">=";
+    right: string;
+}
+/** For the polymorphic row: exactly `nonNullCount` of `columns` is set. */
+ | {
+    kind: "nullCardinality";
+    name: string;
+    columns: string[];
+    nonNullCount: number;
+};
+export type PhiServerAddonIndexDescriptor = {
+    name: string;
+    columns: string[];
+    unique?: boolean;
+};
+export type PhiServerAddonTableDescriptor = {
+    name: string;
+    /**
+     * Core adds the Site column, its foreign key, and its cascade, and puts the Site filter into every
+     * query that reads this table. The Add-on neither writes the column nor is able to forget it.
+     *
+     * This is more than a reference column: it is the boundary a query is compiled against. A table that
+     * merely wants to mention a Site uses a reference column instead.
+     */
+    siteScoped?: boolean;
+    /**
+     * Core adds the owner column and its foreign key, and answers whether a row belongs to the acting
+     * user. The Add-on neither writes the column nor decides what "own" means, which is the point: the
+     * rule that a person may edit and delete what they created is one rule, not one per package.
+     *
+     * The column is nullable and a deleted user leaves it null rather than taking the rows along. A row
+     * without an owner therefore belongs to nobody, and no membership level reaches it through ownership.
+     *
+     * This is authority, not history. A table that only wants to record who created a row uses an
+     * ordinary `core.user` reference column, which grants nothing.
+     */
+    ownerScoped?: boolean;
+    /**
+     * Core adds the group column and binds it to the Site's group, which makes the group membership
+     * levels applicable to this table. Requires `siteScoped`, because a group has no meaning without one.
+     *
+     * As with the Site, this is more than a reference column: it says the rows are group property and are
+     * read through a membership level. A table that merely wants to mention a group uses a `core.group`
+     * reference column instead.
+     */
+    groupScoped?: boolean;
+    columns: PhiServerAddonColumnDescriptor[];
+    primaryKey: string[];
+    indexes?: PhiServerAddonIndexDescriptor[];
+    constraints?: PhiServerAddonTableConstraintDescriptor[];
+};
+/**
+ * The shape an Add-on's schema should have -- not the steps to reach it.
+ *
+ * `version` is the schema version the manifest reports, and Core compares this description against the
+ * one it recorded to decide what to run.
+ */
+export type PhiServerAddonSchemaDescriptor = {
+    descriptorVersion: typeof PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION;
+    version: number;
+    tables: PhiServerAddonTableDescriptor[];
+};

package/dist/schema.js

@@ -0,0 +1,29 @@
+/**
+ * What an Add-on says about the tables it owns.
+ *
+ * An Add-on ships no SQL. It states the shape it wants and Core derives the statements, which is what
+ * lets an Add-on outlive a change of database system and what turns most of the rules in section 15 of
+ * the Add-on contract from something checked afterwards into something that cannot be expressed at all.
+ *
+ * The vocabulary is deliberately poorer than SQL. There are no triggers, functions, views, expression or
+ * partial indexes, and no free-form check, because each of those would be SQL again and would put back
+ * exactly what this removes. An Add-on that needs one of them is either cut wrong or needs a Core
+ * service.
+ */
+export const PHI_SERVER_ADDON_SCHEMA_DESCRIPTOR_VERSION = 1;
+/**
+ * A Core table an Add-on may point at, named symbolically.
+ *
+ * An Add-on never writes `phis.sites(id)`. Core is then free to rename its own tables without breaking
+ * an installed Add-on, and which Core tables are referenceable becomes a decision instead of a
+ * consequence of what happens to be reachable.
+ *
+ * A group exists only inside a Site, so a table pointing at `core.group` must be Site-scoped and Core
+ * binds the pair rather than the id alone. Core never references a group any other way, and an Add-on
+ * that could would be able to name a group belonging to a different Site.
+ */
+export const PHI_SERVER_ADDON_CORE_REFERENCES = {
+    site: "core.site",
+    user: "core.user",
+    group: "core.group",
+};