rastack 0.0.50 → 0.0.52

package/dist/define/index.d.ts

@@ -22,14 +22,31 @@
  * });
  * ```
  */
+/**
+ * Every constraint a scalar builder may be handed, merged — the shape the
+ * runtime value carries so a manifest can be assembled without the compiler.
+ */
+export interface ScalarFieldOptions {
+    maxLength?: number;
+    unique?: boolean;
+    primaryKey?: boolean;
+    default?: unknown;
+    null?: boolean;
+    autoNow?: boolean;
+    autoNowAdd?: boolean;
+}
 /**
  * A scalar field. The literal `__rastackScalar` type is what the compiler
  * reads; `Nullable` phantom-carries the `null: true` option so {@link RowOf}
- * can add `| null` to the inferred row type.
+ * can add `| null` to the inferred row type. The authored options ride along
+ * on the runtime value too, so `manifestFromResources()` can build the same
+ * manifest `rastack compile` emits — with no compile step at all.
  */
 export interface Scalar<T extends string, Nullable extends boolean = boolean> {
     readonly __rastackScalar: T;
     readonly __rastackNullable?: Nullable;
+    /** The constraint options as authored — carried at runtime. */
+    readonly options?: ScalarFieldOptions;
 }
 /** Whether an options literal declares `null: true` (as a type). */
 type NullOf<O> = O extends {
@@ -37,12 +54,16 @@ type NullOf<O> = O extends {
 } ? true : false;
 /**
  * A foreign-key field. `App`/`Model` are carried as string-literal type
- * arguments so the compiler can recover the relation target purely from types.
+ * arguments so the compiler can recover the relation target purely from
+ * types; the target thunk is *also* kept on the runtime value so
+ * `manifestFromResources()` can recover the relation with no compiler.
  */
 export interface Ref<App extends string, Model extends string> {
     readonly __rastackRef: true;
     readonly __app: App;
     readonly __model: Model;
+    /** The authored `() => Resource` thunk — carried at runtime. */
+    readonly target?: () => ResourceType<App, Model, any>;
 }
 export interface StringOptions {
     maxLength?: number;
@@ -67,24 +88,24 @@ export interface DateOptions {
     null?: boolean;
 }
 /**
- * Field builders. Each returns a phantom value whose *type* encodes the field
- * kind; the runtime object is never used at compile time (the compiler analyses
- * the source, it does not execute it) but is real so the DSL is also usable at
- * runtime if a consumer wants it.
+ * Field builders. Each returns a value whose *type* encodes the field kind
+ * (what the compiler reads — it analyses the source, it does not execute it)
+ * and whose runtime shape keeps the authored options/target, so the same
+ * definition doubles as its own manifest via `manifestFromResources()`.
  */
 export declare const s: {
-    string<const O extends StringOptions = StringOptions>(_opts?: O): Scalar<"string", NullOf<O>>;
-    int<const O extends NumberOptions = NumberOptions>(_opts?: O): Scalar<"int", NullOf<O>>;
-    float<const O extends NumberOptions = NumberOptions>(_opts?: O): Scalar<"float", NullOf<O>>;
-    bool<const O extends BoolOptions = BoolOptions>(_opts?: O): Scalar<"bool", NullOf<O>>;
-    datetime<const O extends DateOptions = DateOptions>(_opts?: O): Scalar<"datetime", NullOf<O>>;
-    uuid<const O extends StringOptions = StringOptions>(_opts?: O): Scalar<"uuid", NullOf<O>>;
+    string<const O extends StringOptions = StringOptions>(opts?: O): Scalar<"string", NullOf<O>>;
+    int<const O extends NumberOptions = NumberOptions>(opts?: O): Scalar<"int", NullOf<O>>;
+    float<const O extends NumberOptions = NumberOptions>(opts?: O): Scalar<"float", NullOf<O>>;
+    bool<const O extends BoolOptions = BoolOptions>(opts?: O): Scalar<"bool", NullOf<O>>;
+    datetime<const O extends DateOptions = DateOptions>(opts?: O): Scalar<"datetime", NullOf<O>>;
+    uuid<const O extends StringOptions = StringOptions>(opts?: O): Scalar<"uuid", NullOf<O>>;
     /**
      * A foreign key. The target is `() => SomeResource`; the compiler resolves
-     * the relation from the *type* `Ref<App, Model>` this returns — it does not
-     * need to run the thunk.
+     * the relation from the *type* `Ref<App, Model>` this returns, and the
+     * runtime keeps the thunk so `manifestFromResources()` can resolve it too.
      */
-    ref<A extends string, M extends string>(_thunk: () => ResourceType<A, M, any>): Ref<A, M>;
+    ref<A extends string, M extends string>(thunk: () => ResourceType<A, M, any>): Ref<A, M>;
 };
 export type AnyField = Scalar<string> | Ref<string, string>;
 /** Local-first sync configuration (mirrors the old Python `class Sync:`). */
@@ -103,17 +124,34 @@ export interface SyncOptions {
  * - `ownerField` — the field that records the owning identity (the verified
  *   token `sub`). Rows are only listed/read/written by their owner; the field
  *   is stamped from the token on create and immutable on update.
+ * - `groupField` — the field that records the owning *group* (a verified
+ *   `cognito:groups` value). Rows are only visible to members of their group,
+ *   and the dataset defaults to per-group physical partitioning.
  * - `scope: "owner"` — additionally *physically* partitions the resource's
  *   Iceberg table per identity (`tenants/{sub}/{app}.db/{model}/…`), so
  *   object-storage credentials (e.g. Cognito Identity Pool temp creds) can be
  *   IAM-restricted to `tenants/${"${cognito-identity.amazonaws.com:sub}"}/*`.
+ *   `scope: "group"` partitions per group instead (`groups/{name}/…`);
+ *   `scope: "shared"` keeps one table.
  * - `adminGroups` — token groups (`cognito:groups`) that bypass row filters.
+ *
+ * Class/interface entities express the same policy in the type system — the
+ * `Owner`/`Group` field brands and `IsAuthenticated`/`AdminGroups<…>`/
+ * `OwnerScoped` markers from `rastack/auth`.
  */
 export interface AccessOptions {
     ownerField?: string;
-    scope?: "owner" | "shared";
+    groupField?: string;
+    scope?: "owner" | "group" | "shared";
     adminGroups?: string[];
 }
+/**
+ * The resource-level permission gate — which paths an identity may hit at all.
+ * Enforced by `rastack-api-core` before any row is read; mirrored client-side
+ * by `rastack/auth`'s `can()` so components hide what the server would reject.
+ * Unset means `authenticated` — secure by default.
+ */
+export type Permission = "authenticatedOrReadOnly" | "authenticated" | "public";
 /**
  * One edge of a resource's state machine. `from` is the state (or states) the
  * transition may fire from, `to` the state it enters, and `set` the effect —
@@ -172,7 +210,7 @@ export interface ResourceOptions {
     /** Local-first replication config. */
     sync?: SyncOptions;
     /** Access policy (secure by default). */
-    permission?: "authenticatedOrReadOnly" | "authenticated" | "public";
+    permission?: Permission;
     /** Row-level security + physical tenant partitioning. */
     access?: AccessOptions;
     /** Declarative state machine over one field, enforced on every write surface. */
@@ -229,4 +267,30 @@ export type RowOf<R> = R extends ResourceType<string, string, infer F, ResourceO
 } & {
     [K in keyof F]: FieldValueOf<F[K]>;
 } : never;
-export {};
+/** The `"app.model"` registry key a `resource()` definition implies. */
+export type EntityKeyOf<R> = R extends ResourceType<infer A, infer M, any, ResourceOptions> ? `${A}.${M}` : never;
+/**
+ * The `EntityTypes` registry entries a module of `resource()` definitions
+ * implies — the *hand-written* alternative to the `rastack-env.d.ts` that
+ * `rastack compile` emits. Point it at your resources module once and the
+ * registry tracks it forever, with no compile step in the loop:
+ *
+ * ```ts
+ * // rastack-env.d.ts — written once by you, never regenerated
+ * import type { EntityTypesOf } from "rastack/define";
+ * declare module "rastack/hooks/registry" {
+ *   interface EntityTypes
+ *     extends EntityTypesOf<typeof import("./resources/airports")> {}
+ * }
+ * ```
+ *
+ * Non-resource exports are dropped, so `typeof import("…")` over a whole
+ * module is safe. (Class entities carry their own row type — they never need
+ * the registry; interfaces still register via the compile-emitted file.)
+ */
+export type EntityTypesOf<M> = {
+    [K in keyof M as EntityKeyOf<M[K]>]: RowOf<M[K]>;
+};
+export { isResourceValue, manifestFromResources, resourceModel, toManifest, } from "./manifest";
+export type { AnyResourceValue, ManifestInput } from "./manifest";
+export type { Manifest, ResourceModel } from "../compile/model";

package/dist/define/index.js

@@ -24,40 +24,40 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.s = void 0;
+exports.toManifest = exports.resourceModel = exports.manifestFromResources = exports.isResourceValue = exports.s = void 0;
 exports.resource = resource;
 /**
- * Field builders. Each returns a phantom value whose *type* encodes the field
- * kind; the runtime object is never used at compile time (the compiler analyses
- * the source, it does not execute it) but is real so the DSL is also usable at
- * runtime if a consumer wants it.
+ * Field builders. Each returns a value whose *type* encodes the field kind
+ * (what the compiler reads — it analyses the source, it does not execute it)
+ * and whose runtime shape keeps the authored options/target, so the same
+ * definition doubles as its own manifest via `manifestFromResources()`.
  */
 exports.s = {
-    string(_opts) {
-        return { __rastackScalar: "string" };
+    string(opts) {
+        return { __rastackScalar: "string", options: opts };
     },
-    int(_opts) {
-        return { __rastackScalar: "int" };
+    int(opts) {
+        return { __rastackScalar: "int", options: opts };
     },
-    float(_opts) {
-        return { __rastackScalar: "float" };
+    float(opts) {
+        return { __rastackScalar: "float", options: opts };
     },
-    bool(_opts) {
-        return { __rastackScalar: "bool" };
+    bool(opts) {
+        return { __rastackScalar: "bool", options: opts };
     },
-    datetime(_opts) {
-        return { __rastackScalar: "datetime" };
+    datetime(opts) {
+        return { __rastackScalar: "datetime", options: opts };
     },
-    uuid(_opts) {
-        return { __rastackScalar: "uuid" };
+    uuid(opts) {
+        return { __rastackScalar: "uuid", options: opts };
     },
     /**
      * A foreign key. The target is `() => SomeResource`; the compiler resolves
-     * the relation from the *type* `Ref<App, Model>` this returns — it does not
-     * need to run the thunk.
+     * the relation from the *type* `Ref<App, Model>` this returns, and the
+     * runtime keeps the thunk so `manifestFromResources()` can resolve it too.
      */
-    ref(_thunk) {
-        return { __rastackRef: true };
+    ref(thunk) {
+        return { __rastackRef: true, target: thunk };
     },
 };
 /** Define a resource. Capture app/model (and options) as literal types. */
@@ -72,3 +72,9 @@ function resource(app, model, fields, options = {}) {
         options,
     };
 }
+// The runtime manifest builder — a resource() definition is its own manifest.
+var manifest_1 = require("./manifest");
+Object.defineProperty(exports, "isResourceValue", { enumerable: true, get: function () { return manifest_1.isResourceValue; } });
+Object.defineProperty(exports, "manifestFromResources", { enumerable: true, get: function () { return manifest_1.manifestFromResources; } });
+Object.defineProperty(exports, "resourceModel", { enumerable: true, get: function () { return manifest_1.resourceModel; } });
+Object.defineProperty(exports, "toManifest", { enumerable: true, get: function () { return manifest_1.toManifest; } });

package/dist/define/manifest.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The runtime manifest builder — `resource()` definitions are their own
+ * manifest, **no `rastack compile` step required**.
+ *
+ * The DSL values carry everything the canonical manifest needs at runtime
+ * (field kinds, constraint options, FK target thunks, resource options), so
+ * this module assembles the exact `schema.rastack.json` shape the compiler
+ * emits — same fields, same relations, same normalisation — as a pure
+ * function:
+ *
+ * ```tsx
+ * import { Airport, Terminal, Flight } from "./resources/airports";
+ *
+ * <RAStackProvider mode="local" manifest={[Airport, Terminal, Flight]}>
+ * ```
+ *
+ * The compiler (`tools/src/compile/analyze.ts`) imports the option
+ * normalisers below, so the two paths cannot drift: `rastack compile` remains
+ * the way to get class/interface entities, `openapi.json`, and the artifacts
+ * the Rust backend and admin read — but the typed hooks and the in-browser
+ * engine need only this.
+ *
+ * Everything here is browser-safe: no `typescript`, no filesystem.
+ */
+import type { AccessModel, AdminModel, Manifest, ResourceModel, SyncModel } from "../compile/model";
+import type { ResourceType } from "./index";
+/** Any `resource()` value, generics erased. */
+export type AnyResourceValue = ResourceType<string, string, any, any>;
+/** Everything `toManifest()` understands — see {@link toManifest}. */
+export type ManifestInput = Manifest | object | string | AnyResourceValue | readonly AnyResourceValue[];
+/** Whether a value is a `resource()` definition. */
+export declare function isResourceValue(value: unknown): value is AnyResourceValue;
+/**
+ * One `resource()` value → its canonical {@link ResourceModel} — the same
+ * shape `rastack compile` derives from the source, produced from the runtime
+ * value instead.
+ */
+export declare function resourceModel(res: AnyResourceValue): ResourceModel;
+/**
+ * Assemble the canonical manifest from `resource()` values at runtime —
+ * accepts the values themselves, arrays of them, or whole module namespaces
+ * (`import * as resources from "./resources"`), in any mix. Output order
+ * matches the compiler's (app, then model), so the result is byte-for-byte
+ * the manifest `rastack compile` would emit for the same definitions.
+ */
+export declare function manifestFromResources(...inputs: Array<AnyResourceValue | readonly AnyResourceValue[] | Record<string, unknown>>): Manifest;
+/**
+ * Normalise anything a provider may be handed as "the manifest": a compiled
+ * manifest (object or JSON string), a `resource()` value, an array of them,
+ * or a module namespace containing them. This is what lets
+ * `<RAStackProvider manifest={[Airport, Terminal]}>` work with no compiled
+ * `schema.rastack.json` anywhere.
+ */
+export declare function toManifest(input: ManifestInput | null | undefined): Manifest | undefined;
+/**
+ * Attach a normalised `transitions` block to a resource and derive what the
+ * machine implies about its state field: the `states` become the field's
+ * allowed-value set (`enum` in OpenAPI, the `member` gate in validation), and
+ * `initial` becomes its default when the field doesn't declare one.
+ */
+export declare function applyTransitions(resource: ResourceModel, raw: unknown): void;
+export declare function normaliseSync(sync: any): SyncModel | undefined;
+export declare function normaliseAccess(access: any): AccessModel | undefined;
+export declare function normaliseAdmin(admin: any): AdminModel | false | undefined;

package/dist/define/manifest.js

@@ -0,0 +1,259 @@
+"use strict";
+/**
+ * The runtime manifest builder — `resource()` definitions are their own
+ * manifest, **no `rastack compile` step required**.
+ *
+ * The DSL values carry everything the canonical manifest needs at runtime
+ * (field kinds, constraint options, FK target thunks, resource options), so
+ * this module assembles the exact `schema.rastack.json` shape the compiler
+ * emits — same fields, same relations, same normalisation — as a pure
+ * function:
+ *
+ * ```tsx
+ * import { Airport, Terminal, Flight } from "./resources/airports";
+ *
+ * <RAStackProvider mode="local" manifest={[Airport, Terminal, Flight]}>
+ * ```
+ *
+ * The compiler (`tools/src/compile/analyze.ts`) imports the option
+ * normalisers below, so the two paths cannot drift: `rastack compile` remains
+ * the way to get class/interface entities, `openapi.json`, and the artifacts
+ * the Rust backend and admin read — but the typed hooks and the in-browser
+ * engine need only this.
+ *
+ * Everything here is browser-safe: no `typescript`, no filesystem.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isResourceValue = isResourceValue;
+exports.resourceModel = resourceModel;
+exports.manifestFromResources = manifestFromResources;
+exports.toManifest = toManifest;
+exports.applyTransitions = applyTransitions;
+exports.normaliseSync = normaliseSync;
+exports.normaliseAccess = normaliseAccess;
+exports.normaliseAdmin = normaliseAdmin;
+const transitions_1 = require("../validate/transitions");
+/** Whether a value is a `resource()` definition. */
+function isResourceValue(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        value.__rastack === "resource");
+}
+/**
+ * One `resource()` value → its canonical {@link ResourceModel} — the same
+ * shape `rastack compile` derives from the source, produced from the runtime
+ * value instead.
+ */
+function resourceModel(res) {
+    const fields = [];
+    const relations = [];
+    for (const [name, value] of Object.entries((res.fields ?? {}))) {
+        const field = runtimeField(res, name, value);
+        if (!field)
+            continue;
+        fields.push(field);
+        if (field.type === "fk" && field.relation) {
+            relations.push({
+                field: name,
+                target: `${field.relation.app}.${field.relation.model}`,
+                kind: "fk",
+            });
+        }
+    }
+    const options = (res.options ?? {});
+    const model = {
+        app: res.app,
+        model: res.model,
+        fields,
+        relations,
+        sync: normaliseSync(options.sync),
+        admin: normaliseAdmin(options.admin),
+        search: options.search,
+        ordering: options.ordering,
+        permission: options.permission,
+        access: normaliseAccess(options.access),
+    };
+    applyTransitions(model, options.transitions);
+    return model;
+}
+/** Resolve one runtime field value to its {@link FieldModel}. */
+function runtimeField(res, name, value) {
+    if (!value || typeof value !== "object")
+        return undefined;
+    const field = value;
+    // Foreign key: the runtime value keeps the `() => Resource` thunk, so the
+    // relation target is recovered by calling it — the runtime twin of the
+    // compiler's "read the Ref<App, Model> type arguments" step.
+    if (field.__rastackRef === true) {
+        const target = field.target?.();
+        if (!isResourceValue(target)) {
+            throw new Error(`manifestFromResources: ${res.app}.${res.model}.${name} is an s.ref(...) whose target thunk did not return a resource() value`);
+        }
+        return {
+            name,
+            type: "fk",
+            relation: { app: target.app, model: target.model },
+        };
+    }
+    if (typeof field.__rastackScalar !== "string")
+        return undefined;
+    const model = {
+        name,
+        type: field.__rastackScalar,
+    };
+    // Constraint mapping mirrors the compiler's `applyConstraints` exactly.
+    const opts = field.options;
+    if (opts && typeof opts === "object") {
+        if (typeof opts.maxLength === "number")
+            model.maxLength = opts.maxLength;
+        if (opts.unique === true)
+            model.unique = true;
+        if (opts.primaryKey === true)
+            model.primaryKey = true;
+        if (opts.null === true)
+            model.null = true;
+        if (opts.default !== undefined)
+            model.default = opts.default;
+    }
+    return model;
+}
+/**
+ * Assemble the canonical manifest from `resource()` values at runtime —
+ * accepts the values themselves, arrays of them, or whole module namespaces
+ * (`import * as resources from "./resources"`), in any mix. Output order
+ * matches the compiler's (app, then model), so the result is byte-for-byte
+ * the manifest `rastack compile` would emit for the same definitions.
+ */
+function manifestFromResources(...inputs) {
+    const resources = collectResources(inputs).map(resourceModel);
+    resources.sort((a, b) => a.app === b.app ? a.model.localeCompare(b.model) : a.app.localeCompare(b.app));
+    return { version: 1, resources };
+}
+/** Flatten values / arrays / module namespaces into the resource list. */
+function collectResources(inputs) {
+    const out = [];
+    const seen = new Set();
+    const push = (res) => {
+        if (!seen.has(res)) {
+            seen.add(res);
+            out.push(res);
+        }
+    };
+    for (const input of inputs) {
+        if (isResourceValue(input)) {
+            push(input);
+        }
+        else if (Array.isArray(input)) {
+            for (const item of input)
+                if (isResourceValue(item))
+                    push(item);
+        }
+        else if (input && typeof input === "object") {
+            for (const item of Object.values(input)) {
+                if (isResourceValue(item))
+                    push(item);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Normalise anything a provider may be handed as "the manifest": a compiled
+ * manifest (object or JSON string), a `resource()` value, an array of them,
+ * or a module namespace containing them. This is what lets
+ * `<RAStackProvider manifest={[Airport, Terminal]}>` work with no compiled
+ * `schema.rastack.json` anywhere.
+ */
+function toManifest(input) {
+    if (input === null || input === undefined)
+        return undefined;
+    if (typeof input === "string")
+        return JSON.parse(input);
+    if (Array.isArray(input) || isResourceValue(input)) {
+        return manifestFromResources(input);
+    }
+    const record = input;
+    // A compiled manifest passes through untouched.
+    if (Array.isArray(record.resources))
+        return input;
+    // A module namespace of resource() exports builds one.
+    const values = Object.values(record).filter(isResourceValue);
+    if (values.length)
+        return manifestFromResources(values);
+    return input;
+}
+// ---------------------------------------------------------------------------
+// Option normalisers — shared with the compiler (`compile/analyze.ts`), so
+// the runtime and compiled manifests can never disagree about a resource.
+// ---------------------------------------------------------------------------
+/**
+ * Attach a normalised `transitions` block to a resource and derive what the
+ * machine implies about its state field: the `states` become the field's
+ * allowed-value set (`enum` in OpenAPI, the `member` gate in validation), and
+ * `initial` becomes its default when the field doesn't declare one.
+ */
+function applyTransitions(resource, raw) {
+    const transitions = (0, transitions_1.normalizeTransitions)(raw);
+    if (!transitions)
+        return;
+    resource.transitions = transitions;
+    const stateField = resource.fields.find((f) => f.name === transitions.field);
+    if (stateField && stateField.type !== "fk") {
+        stateField.options = [...transitions.states];
+        if (stateField.default === undefined && transitions.initial !== undefined) {
+            stateField.default = transitions.initial;
+        }
+    }
+}
+function normaliseSync(sync) {
+    if (!sync || typeof sync !== "object")
+        return undefined;
+    const mode = sync.mode === "local" ? "local" : "server";
+    if (mode === "server" && !sync.confirmed) {
+        // A bare server resource carries no sync semantics.
+        return undefined;
+    }
+    const model = { mode };
+    if (typeof sync.scope === "string")
+        model.scope = sync.scope;
+    if (Array.isArray(sync.confirmed))
+        model.confirmed = sync.confirmed;
+    if (sync.load === "lazy")
+        model.load = "lazy";
+    if (sync.clientIds === true)
+        model.clientIds = true;
+    return model;
+}
+function normaliseAccess(access) {
+    if (!access || typeof access !== "object")
+        return undefined;
+    const model = {};
+    if (typeof access.ownerField === "string")
+        model.ownerField = access.ownerField;
+    if (typeof access.groupField === "string")
+        model.groupField = access.groupField;
+    if (access.scope === "owner" ||
+        access.scope === "group" ||
+        access.scope === "shared") {
+        model.scope = access.scope;
+    }
+    else if (model.groupField) {
+        // Group-owned datasets are physically partitioned per group by default —
+        // that is their point. `scope: "shared"` opts out explicitly.
+        model.scope = "group";
+    }
+    if (Array.isArray(access.adminGroups)) {
+        model.adminGroups = access.adminGroups.filter((g) => typeof g === "string");
+    }
+    return Object.keys(model).length ? model : undefined;
+}
+function normaliseAdmin(admin) {
+    if (admin === false)
+        return false;
+    if (!admin || typeof admin !== "object")
+        return undefined;
+    const model = {};
+    if (Array.isArray(admin.listDisplay))
+        model.listDisplay = admin.listDisplay;
+    return model;
+}

package/dist/define/markers.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Entity-level authorization markers — auth as *TypeScript types*.
+ *
+ * Class and interface entities have no options bag, so their access policy is
+ * expressed the same way their columns are: in the type system. Attach a
+ * marker with `implements` (classes) or `extends` (interfaces) and the
+ * compiler reads the policy straight off the heritage clause:
+ *
+ * ```ts
+ * import { AdminGroups, IsAuthenticated, Owner, Group } from "rastack/auth";
+ *
+ * // Per-user rows: RLS on `owner`, staff sees everything.
+ * export class Itinerary implements IsAuthenticated, AdminGroups<"staff"> {
+ *   owner!: string & Owner;
+ *   notes!: string;
+ * }
+ *
+ * // Group-owned dataset: rows belong to a team and are *physically stored*
+ * // under that team's own storage prefix (groups/{team}/…).
+ * export class Report implements IsAuthenticated, AdminGroups<"staff"> {
+ *   team!: string & Group;
+ *   title!: string;
+ * }
+ * ```
+ *
+ * The markers are phantom types: every property is optional and never exists
+ * at runtime, so `implements` needs no members and instances stay plain data.
+ * Each marker family uses its own phantom key, so markers combine freely —
+ * while two *permission* markers on one entity conflict in the type checker,
+ * which is exactly right.
+ *
+ * JSDoc equivalents exist for every marker (`@rastackPermission`,
+ * `@rastackAdminGroups staff, ops`, `@rastackScope owner|group|shared`, and
+ * field-level `@owner` / `@group`), mirroring the column-constraint tags.
+ */
+/** The permission gate carried in the type system. */
+export interface PermissionOf<P extends string> {
+    readonly __rastackPermission?: P;
+}
+/** Every path requires a verified identity (this is also the default). */
+export interface IsAuthenticated extends PermissionOf<"authenticated"> {
+}
+/** Anonymous callers may read (list/retrieve); writes require identity. */
+export interface IsAuthenticatedOrReadOnly extends PermissionOf<"authenticatedOrReadOnly"> {
+}
+/** No gate — every caller may read and write. Opt-in, never the default. */
+export interface IsPublic extends PermissionOf<"public"> {
+}
+/**
+ * Token groups (`cognito:groups`) that bypass row-level security on this
+ * entity — the "is admin" role, driven from scopes: `implements
+ * AdminGroups<"staff" | "ops">`. Members see and act on every row.
+ */
+export interface AdminGroups<G extends string> {
+    readonly __rastackAdminGroups?: G;
+}
+/** Storage scope carried in the type system. */
+export interface ScopeOf<S extends string> {
+    readonly __rastackScope?: S;
+}
+/**
+ * Physically partition the entity's table per identity
+ * (`tenants/{sub}/…`) — the prefix object-storage IAM can fence per user.
+ * Combine with an `Owner` field brand.
+ */
+export interface OwnerScoped extends ScopeOf<"owner"> {
+}
+/**
+ * Physically partition the entity's table per group (`groups/{name}/…`).
+ * This is the default whenever a `Group` field brand is present — declare it
+ * only for emphasis or with a JSDoc-configured group field.
+ */
+export interface GroupScoped extends ScopeOf<"group"> {
+}
+/**
+ * Keep rows in one shared table (row-level filters still apply). Use to opt a
+ * `Group`-branded entity out of the default per-group physical partitioning.
+ */
+export interface SharedStorage extends ScopeOf<"shared"> {
+}