Establish clean starting point: workplan, access model, INTENT amendments

Add SHARD-WP-0001 workplan backed by the StateHub yawex-requirements
workstream (6 design tasks, all todo). Includes access-model blueprint,
NetKingdom integration requirements draft, and INTENT amendments for
open-by-default authorization delegated to external identity providers.

docs/requirements-user-engine-netkingdom.md

@@ -0,0 +1,88 @@
+# Requirements — what shard-wiki needs from user-engine & net-kingdom
+
+Status: **draft for review** · Date: 2026-06-08
+
+Derived from `access-model-blueprint.md`. These are the integration contracts shard-wiki
+needs to climb from L0 (open, standalone) to L4 (multi-tenant enterprise) **without
+changing its core**. They are requirements *on* the NetKingdom domain repos, to be
+negotiated with their owners — not assumptions about their current implementation.
+
+Reference deployment roles:
+- **net-kingdom** — IAM/SSO backend. Issues and validates identities. OIDC/PKCE in
+  lightweight mode (KeyCape: Authelia + LLDAP + privacyIDEA), Keycloak/SAML in expanded
+  mode. Owns authentication, credentials, MFA, the NetKingdom IAM Profile.
+- **user-engine** — headless user-domain service: accounts, memberships, profiles,
+  catalogs, projections, audit, events. Owns the *membership/role/tenant* read model
+  shard-wiki authorizes against.
+
+shard-wiki authorizes; it never authenticates or stores identity. Everything below is a
+**read or emit** contract — shard-wiki must not need write access to identity data.
+
+---
+
+## A. From net-kingdom (authentication / IAM)
+
+1. **Token issuance & validation (OIDC/PKCE).** A standard OIDC relationship shard-wiki can
+   register as a confidential or public client; ability to validate presented access/ID
+   tokens (JWKS endpoint or introspection). Lightweight mode must work without Keycloak.
+2. **Stable subject identifier.** A durable `sub` that does not change across renames/email
+   changes, usable as the Principal key.
+3. **Tenant claim.** A claim that identifies the tenant/organization a token is scoped to
+   (claim name TBD), so shard-wiki can map token → tenant → root entity.
+4. **Group/role claims (optional fast path).** If groups/roles can ride in the token, L3/L4
+   decisions need no extra round-trip. Otherwise shard-wiki resolves them via user-engine (B).
+5. **Expanded-mode parity.** The same claim contract must hold when the backend is swapped
+   to Keycloak/SAML, so climbing L3→L4 is a deployment change, not a shard-wiki change.
+6. **Logout / token revocation signal** so shard-wiki can drop cached Principals.
+
+## B. From user-engine (membership / authorization read model)
+
+1. **Resolve principal → memberships.** Given a `sub` (and tenant), return the principal's
+   group/role memberships relevant to wiki access. Read-only, low-latency, cacheable with a
+   stated TTL.
+2. **Tenant ↔ root-entity mapping.** A way to resolve which tenant(s) a principal belongs to
+   and how those map to shard-wiki root entities. Either user-engine owns this mapping or it
+   exposes the primitives for shard-wiki to hold it as config.
+3. **Role vocabulary.** An agreed, minimal role set that maps onto shard-wiki actions:
+   `reader → read`, `author → read+write+patch`, `maintainer → +merge+administer`. Custom
+   roles allowed but must declare which actions they grant.
+4. **Profile lookup for attribution.** Given a `sub`, return display name / handle so edits
+   and signatures are attributable (the L1 "sign your edits" need, generalized).
+5. **Stable, versioned read API.** A versioned contract (REST/gRPC) for B1–B4 so shard-wiki
+   isn't coupled to user-engine internals; INTENT requires stable adapter contracts.
+6. **Bulk/batch resolution.** Resolving memberships for many principals (e.g. rendering a
+   BackLinks/history view) must not be N+1; provide batch lookup.
+
+## C. Audit / events (shard-wiki → user-engine)
+
+1. **Audit event sink.** shard-wiki emits access-relevant events (page read-denied,
+   write, patch, merge, admin change) to user-engine's audit/event stream. Need the
+   **event schema** and transport (user-engine already lists "audit" and "events" as owned
+   concerns — align to that).
+2. **Non-blocking emission.** Audit emission must be async/best-effort so an audit outage
+   never blocks a wiki write (history in Git remains the source of truth regardless).
+
+## D. Cross-cutting / non-functional
+
+1. **Graceful degradation contract.** A defined behavior when the provider is unreachable in
+   L2+: shard-wiki **fails closed** (denies), and must be able to distinguish "provider down"
+   from "principal unauthorized" for operability. (L0/L1 never depend on the provider.)
+2. **No secret custody in shard-wiki.** Client secrets / keys are provisioned and rotated by
+   net-kingdom; shard-wiki consumes them via the deployment's secret mechanism, never stores
+   or commits them. (Consistent with INTENT non-goal on secret storage.)
+3. **Offline authorization.** After Principal resolution, decisions must be computable without
+   per-page network calls (carry claims on the Principal or cache memberships).
+4. **Capability-progression alignment.** The integration should slot into NetKingdom's
+   C0–C6 ladder so shard-wiki's L0–L4 modes correspond to recognizable NetKingdom capability
+   levels rather than introducing a parallel scheme.
+
+---
+
+## Next actions
+
+- [ ] Send this as a **capability request / interface negotiation** to the netkingdom domain
+      (user-engine + net-kingdom owners) via the state hub.
+- [ ] Lock the **token claim contract** (A2–A4) and the **membership read API** (B1–B5) first
+      — they gate everything L2+.
+- [ ] Define shard-wiki's **audit event schema** (C1) against user-engine's existing audit model.
+- [ ] Resolve blueprint open questions §6 once the above are answered.