first commit

docs/api-stack/api/api-auth/src/capability-id/capability-id.md

@@ -0,0 +1,85 @@
+# `capability-id` — `"auth.session"` contribution
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Pins this package's `CapabilityId` contribution as a stand-alone literal type
+plus runtime constant. The `CapabilityId` union in
+`@suaveplan/api-types/capabilities` already enumerates `"auth.session"`
+directly; this module ties the api-auth package to that identifier so any
+future rename surfaces here first as a build break.
+
+Exporting the runtime literal as `AUTH_SESSION_CAPABILITY_ID` lets plugin
+manifests declare `requires: [AUTH_SESSION_CAPABILITY_ID] as const` without
+hard-coding the string at the manifest site — refactor-safe and centrally
+documented.
+
+## Features
+
+- Compile-time `const _assignable: CapabilityId = AUTH_SESSION_CAPABILITY_ID`
+  asserts membership at build time. If `api-types` ever drops the token, this
+  package fails to type-check rather than silently regressing.
+- Type and value are exported together so the consumer can pick the form that
+  fits the call site without re-stringifying.
+
+## Usage: Basic
+
+```ts
+import { AUTH_SESSION_CAPABILITY_ID } from "@suaveplan/api-auth/capability-id";
+
+const requires = [AUTH_SESSION_CAPABILITY_ID] as const;
+```
+
+## Usage: Advanced
+
+Use the literal type to constrain a manifest builder helper:
+
+```ts
+import {
+    AUTH_SESSION_CAPABILITY_ID,
+    type AuthSessionCapabilityId,
+} from "@suaveplan/api-auth/capability-id";
+import type { CapabilityId } from "@suaveplan/api-types/capabilities";
+
+function manifestRequires<const T extends readonly CapabilityId[]>(req: T): T {
+    return req;
+}
+
+const requires = manifestRequires([
+    AUTH_SESSION_CAPABILITY_ID,
+    "logger",
+] satisfies readonly (AuthSessionCapabilityId | "logger")[]);
+```
+
+## API Reference
+
+| Symbol                          | Kind | Description                                  |
+|---------------------------------|------|----------------------------------------------|
+| `AuthSessionCapabilityId`       | type | The literal `"auth.session"`.                |
+| `AUTH_SESSION_CAPABILITY_ID`    | const| `"auth.session"` runtime value.               |
+
+## Implementation Notes
+
+- The `void _assignable` keeps the assignment from being tree-shaken; without
+  it Rollup MAY drop the line and the build-time assertion silently regresses
+  to no-op.
+- This module is import-time-only — no behaviour at runtime beyond the
+  string literal binding.
+- The literal is exported as both a `type` and a runtime `const` deliberately:
+  consumers that build manifests imperatively want the runtime value; consumers
+  that constrain compile-time-only structures (a `definePlugin` builder, for
+  example) want the literal type. Re-stringifying `"auth.session"` at the
+  consumer side would defeat the purpose of having the package central.
+- The pairing with `@suaveplan/api-types/capabilities` is deliberately
+  one-directional. `api-types` is the source of truth for the closed union;
+  this package only re-asserts membership and binds the runtime value. If a
+  future change wanted to flip the relationship — have api-auth contribute via
+  declaration merging instead — that would require relaxing the `CapabilityId`
+  union in api-types to be `open` (i.e. `string & { brand }`), which is a
+  larger contract change documented as out-of-scope here.
+- The runtime constant uses a type annotation rather than `as const`: the
+  annotation makes the assignable check above explicit, and `as const` would
+  widen any future enum-style rewrite.