feat: implement governed service directory

docs/SERVICE_DIRECTORY_CONCEPT.md

@@ -4,6 +4,12 @@ GovOPlaN Portal should expose a role-aware service directory. The directory is
 not a marketing catalogue; it is the user-facing map of what a person can do in
 the configured institution.
 
+Portal owns presentation, discovery, entry, and channel-specific availability.
+It must not become the long-term owner of the institutional service definition.
+A shared Services contract should own the versioned promise independently so
+Cases, Forms, Workflow Engine, Reporting, external publication, and more than
+one portal surface can consume the same definition.
+
 ## Purpose
 
 The service directory should help users find the right administrative action
@@ -34,11 +40,22 @@ A service entry should describe:
 - policy and availability blockers
 - user-facing explanation and required documents
 - audit and evidence expectations
+- version and effective interval
+- legal or organizational basis, deadlines, fees, remedies, and service-level
+  expectations
+- responsible organization/function, mandate/jurisdiction, result/decision,
+  publication, and records bindings
 
 The portal should request service contributions through core-mediated
 capability and UI contribution contracts. It must not import domain module
 internals.
 
+The first implementation may consume module-contributed service definitions.
+Create a separate `govoplan-services` repository only when definitions require
+independent persistence/lifecycle and are consumed outside Portal by at least
+one other procedure or publication surface. Extraction must keep stable service
+keys and compatibility for existing Portal links.
+
 Service visibility must consume access semantics through kernel capabilities:
 
 - `access.semanticDirectory` resolves the actor's identity, account,
@@ -56,3 +73,54 @@ The directory should explain unavailable services when the reason is useful:
 missing role, disabled module, tenant policy, missing connector, maintenance
 mode, or unavailable external provider. It should hide only services that are
 irrelevant or intentionally undiscoverable by policy.
+
+## Implemented Slice
+
+`portal.service_directory` consumes the optional `services.definitions`
+capability. It returns only tenant-scoped definitions and distinguishes
+`available`, `unavailable`, and `hidden` states. Draft, retired,
+outside-effective-time, and audience-inapplicable services are hidden. A
+suspended service or missing required module/capability remains discoverable
+with stable reason codes and its configured explanation reference.
+
+The definition provider remains responsible for access and policy filtering.
+Portal cannot widen its result and returns an empty directory when no provider
+is installed. No service definition is persisted in Portal.
+
+Tenant/package specializations are derived before presentation through Core's
+restrictive Service rule. They carry their parent version and may narrow
+audience, channels, effective time, and publication or add prerequisites,
+required evidence, legal bases, and bindings. They cannot silently loosen the
+system/package definition.
+
+Policy, Mandate, connector, maintenance, and configuration requirements are
+evaluated through the optional `services.availability` capability. Module and
+capability requirements are checked against the active registry, and audience
+requirements against the supplied actor projection. Unknown requirements fail
+closed. Each requirement declares whether failure remains visible with an
+explanation or makes the entry undiscoverable.
+
+`GET /api/v1/portal/services` and the `/portal` WebUI expose this projection.
+The API derives audience tokens from the authenticated principal instead of
+accepting caller-provided audience claims. Generic `public` and `authenticated`
+tokens are combined with stable account, identity, group, role, active function,
+and organization-unit tokens. Function slugs are included only after the
+optional Access semantic directory confirms an active, effective, same-tenant
+assignment. Missing or failing directory providers narrow the result.
+
+The WebUI provides bounded search, availability filtering, explanations, and
+one launch action. `POST /api/v1/portal/services/{service_id}/launch` resolves
+the entry again at launch time so a stale browser projection cannot bypass a
+new audience, publication, effective-time, module, or capability restriction.
+Direct URL entries return only validated local or credential-free HTTP(S)
+redirects.
+
+Case, form, and workflow bindings delegate to owner capabilities. Their launch result
+must retain the exact Service reference, tenant, binding kind, target reference,
+and replay-safe idempotency key. Portal never writes their tables. Missing
+launchers produce `service.launcher.missing:<kind>` and make the entry visibly
+unavailable. Forms Runtime now provides a definition-aware launcher when Forms
+and Forms Runtime are active. It resolves an exact published
+`<form-id>/<revision>`, validates launch values, and retains Service/binding
+provenance. Reduced installations still fail closed rather than simulating a
+submission in Portal.