@prefig/upact 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project uses [semantic versioning](https://semver.org/) from v1.0.0 onward; v0.x breaking changes are permitted between minor versions.
+
+---
+
+## [0.1.1] — 2026-05-01
+
+Additive spec amendments: lifecycle and provenance on `Upactor`. Ships `@prefig/upact-oidc` as the third reference adapter.
+
+### Added
+
+- `IdentityLifecycle` type: `{ expires_at?: Date; renewable: 'reauth' | 'represence' | 'never' }`. Optional on `Upactor.lifecycle`; the OIDC adapter populates it from JWT `exp`. Non-OIDC adapters may omit it.
+- `Upactor.provenance?: { substrate: string; instance?: string }` — cross-IDP disambiguation; the OIDC adapter populates it from the OIDC issuer URL. Optional; non-OIDC adapters may omit it.
+- `@prefig/upact-oidc`: OIDC reference adapter. PKCE (S256), signed-cookie state, transparent session refresh, scope policy that structurally excludes `email` / `phone` / `address` / `groups` at construction time.
+
+---
+
+## [0.1.0] — 2026-05-01
+
+First public draft. Establishes the `Upactor` primitive, the `IdentityPort` contract, the `AuthError` vocabulary, and the Session opacity guarantee. Ships with two reference adapters (`@prefig/upact-supabase`, `@prefig/upact-simplex`) and the five-test contributor audit.
+
+### Added
+
+- `Upactor` type: `{ id: string; display_hint?: string; capabilities: ReadonlySet<Capability> }` — the minimal port-facing identity object. Named to draw on the UML Actor lineage and the upact brand.
+- `Capability` vocabulary: `'email' | 'recovery'` (audit-trimmed; extensible via §5.2 registry process at v0.2+).
+- `IdentityPort` interface: `authenticate`, `currentUpactor`, `invalidate`, `issueRenewal`.
+- `AuthError` and `AuthErrorCode`: normative six-member error vocabulary (`credential_invalid`, `credential_rejected`, `substrate_unavailable`, `identity_unavailable`, `rate_limited`, `auth_failed`).
+- `Session` type and `createSession` factory: opaque runtime value that passes sixteen-vector reflection suite in `tests/runtime.test.ts`.
+- `SubstrateUnavailableError`: typed error class for adapter-to-application substrate failure signalling.
+- `SPEC.md`: first public draft, covering Upactor (§4), capability vocabulary (§5), port operations (§6), Session opacity and adapter conformance (§7), security considerations (§10), and the deferred-decisions register (§12).
+- `CONTRIBUTING.md`: five-test contributor audit and AI-Involvement trailer convention.
+- `GOVERNANCE.md`: v0.x maintainer posture and v1.0 working-group target.
+- `CONFORMANCE.md`: conformance template with filled-in Supabase reference adapter example.
+- `docs/adapter-shapes.md`: Supabase (enforcement camp) and SimpleX (pre-conforming) adapter shape sketches; OIDC forward-looking sketch for Phase C.
+- `docs/cross-adapter-findings.md`: F1–F4, F6, G1 cross-substrate observations.
+
+### Changed
+
+- `UserIdentity` deprecated in favour of `Upactor`. The alias `UserIdentity = Upactor` remains for v0.1.x compatibility and will be removed in v0.2.
+
+### Removed (from earlier drafts)
+
+- Speculative capability vocabulary entries (`messaging`, `p2p_matching`, `presence`) — no concrete consumer per audit; SimpleX ships with `[]`.
+- Convene, Reticulum, and fediverse-DID adapter sketches — no shipped adapter, no concrete consumer; return to `docs/adapter-shapes.md` when their adapters ship.

package/CONFORMANCE.md

@@ -0,0 +1,162 @@
+# Conformance statement template
+
+Copy this template into your adapter package as `CONFORMANCE.md` and fill in each section. A filled-in example for the Supabase reference adapter follows the template.
+
+---
+
+## Template
+
+```markdown
+# Conformance: <adapter package name>
+
+**Spec version:** upact vX.Y
+**Package version:** X.Y.Z
+**Date:** YYYY-MM-DD
+
+## Substrate
+
+<Name and brief description of the substrate. Include whether it is enforcement-camp or pre-conforming.>
+
+## Threat model
+
+<What threat model does this adapter serve? See SPEC.md §10 for the taxonomy (casual coordination / anonymous-pseudonymous / adversarial-context). What does the substrate protect against, and what does it not protect against?>
+
+## Capabilities self-declared
+
+`[ <list of Capability values this adapter may return, or empty for []> ]`
+
+For each capability listed, name the concrete consumer (the application code that gates on it).
+
+## AuthError mapping table
+
+| Substrate error | AuthErrorCode |
+|---|---|
+| <substrate error> | <code> |
+
+## Session opacity
+
+This adapter uses `createSession` from `@prefig/upact` for Session construction.
+
+OR
+
+This adapter does not use `createSession`. The adapter's Session implementation passes the sixteen-vector reflection test at `tests/back-channel.test.ts` (vectors: JSON.stringify, Object.keys, Object.getOwnPropertyNames, Reflect.ownKeys, Object.getOwnPropertySymbols, for-in, structuredClone, util.inspect, direct property access by name, Object spread, wrapped JSON.stringify, and cast access to common substrate-property names).
+
+## Adapter back-channel closure
+
+This adapter passes a sixteen-vector reflection test (`tests/back-channel.test.ts`) asserting that no sentinel substrate token leaks through the adapter instance.
+
+## Deviations from SHOULD clauses
+
+<List any SHOULD clauses from the spec that this adapter does not follow, and the reason. If none, write "None.">
+
+## Identifier derivation
+
+<Describe how the `Upactor.id` is derived from the substrate's user identifier. If it is a hashed derivation, name the hash function and any prefix truncation. If it is a direct mapping, explain why the substrate identifier is already opaque.>
+```
+
+---
+
+## Example: `@prefig/upact-supabase`
+
+# Conformance: @prefig/upact-supabase
+
+**Spec version:** upact v0.1
+**Package version:** 0.1.0
+**Date:** 2026-05-01
+
+## Substrate
+
+Supabase Auth — a managed PostgreSQL-backed identity service. `auth.users` is the substrate user record. Enforcement-camp substrate: the Supabase `User` object exposes email, phone, JWT claims, `app_metadata`, and `user_metadata`; the adapter strips all of these except what is needed to populate the three `Upactor` fields.
+
+## Threat model
+
+Casual coordination. Supabase Auth is a centralised service operated by Supabase, Inc. It is not appropriate for adversarial-context deployments where substrate-operator trust is not granted. The adapter is designed for applications where the substrate's leakiness is acceptable in exchange for Supabase's ergonomics and reliability.
+
+## Capabilities self-declared
+
+`['email', 'recovery']` — for users with a confirmed email address (non-empty `user.email`).
+`[]` — for users without a confirmed email address.
+
+Concrete consumer: dyad M1 UI gates on `capabilities.has('email')` to show or hide email-related settings. `recovery` is bundled with `email` because the same email address that identifies the user is the recovery channel; they are not independently affords.
+
+## AuthError mapping table
+
+| Substrate error | AuthErrorCode |
+|---|---|
+| `AuthApiError` (invalid credentials, wrong password) | `credential_rejected` |
+| `AuthApiError` (user not found) | `credential_rejected` |
+| `AuthApiError` (email not confirmed) | `credential_rejected` |
+| `AuthApiError` (rate limit) | `rate_limited` |
+| Network error / Supabase unreachable | `substrate_unavailable` |
+| Malformed substrate User (no `id` field) | `auth_failed` |
+| Unknown error | `auth_failed` |
+
+Note: Supabase conflates "user not found" with "wrong password" as credential-stuffing resistance. Both surface as `credential_rejected`. `identity_unavailable` is not emitted by this adapter.
+
+## Session opacity
+
+This adapter uses `createSession` from `@prefig/upact` for Session construction.
+
+## Adapter back-channel closure
+
+This adapter passes a sixteen-vector reflection test at `tests/back-channel.test.ts`. Sentinel values for `__internalToken`, `__anonKey`, and `__url` on a mock `SupabaseClient` are verified unreachable through JSON.stringify, Object.keys, Object.getOwnPropertyNames, Reflect.ownKeys, Object.getOwnPropertySymbols, for-in, structuredClone, util.inspect, direct property access by name, Object spread, wrapped JSON.stringify, and cast access to `client`, `supabase`, `_client`.
+
+## Deviations from SHOULD clauses
+
+None.
+
+## Identifier derivation
+
+`Upactor.id` is set directly from `user.id` — the Supabase Auth UUID. Supabase UUIDs are opaque random identifiers (`gen_random_uuid()`); they are not derivable from user-supplied identifiers (email, phone). No hashing is applied. The raw UUID is not email-shaped and carries no information about the user visible at the application layer.
+
+---
+
+## Example: `@prefig/upact-simplex`
+
+# Conformance: @prefig/upact-simplex
+
+**Spec version:** upact v0.1
+**Package version:** 0.1.0
+**Date:** 2026-05-01
+
+## Substrate
+
+SimpleX Chat daemon — a local IPC process exposing a JSON command API. Pre-conforming substrate: the SimpleX local profile carries `localDisplayName`, `agentUserId` (UUID), and a handful of status flags. There is no central directory; profiles are application-scoped and anonymous. The adapter is thin — mostly type translation.
+
+## Threat model
+
+Anonymous / pseudonymous coordination. The SimpleX substrate has no central directory and uses anonymous unidirectional queues. The substrate's natural shape is already aligned with upact's privacy minima. This adapter is appropriate for deployments where pseudonymity is a requirement and correlation across sessions is undesirable.
+
+## Capabilities self-declared
+
+`[]` — no capabilities declared for v0.1.
+
+The SimpleX substrate affords messaging (`sendMessage`, `receiveMessage`) and peer-to-peer matching. Neither is surfaced through the upact port at v0.1: no shipped consumer gates on a `messaging` or `p2p_matching` capability check. Per the minimum-viable discipline (CONTRIBUTING.md), capabilities land when a concrete consumer surfaces them.
+
+## AuthError mapping table
+
+| Substrate error | AuthErrorCode |
+|---|---|
+| `DaemonError { kind: 'unreachable' }` | `substrate_unavailable` |
+| `DaemonError { kind: 'not-found' }` | `identity_unavailable` |
+| `DaemonError { kind: 'rejected' }` | `credential_rejected` |
+| `DaemonError { kind: 'invalid-profile' }` | `credential_invalid` |
+| `DaemonError { kind: 'unknown' }` | `auth_failed` |
+| Unknown error | `auth_failed` |
+| Malformed substrate User (no `agentUserId`) | `auth_failed` |
+
+## Session opacity
+
+This adapter uses `createSession` from `@prefig/upact` for Session construction.
+
+## Adapter back-channel closure
+
+This adapter passes a sixteen-vector reflection test at `tests/back-channel.test.ts`. Sentinel values for `__internalToken`, `__socketPath`, and `__profileData` on a mock `SimpleXClient` are verified unreachable through all standard reflection vectors and cast access to `client`, `simpleXClient`, `_client`.
+
+## Deviations from SHOULD clauses
+
+None.
+
+## Identifier derivation
+
+`Upactor.id` is derived from `user.agentUserId` (a UUID string) via `SHA-256(agentUserId).slice(0, 32)` — the first 32 hex characters of the SHA-256 digest. The derivation is deterministic per `agentUserId` (stable across sessions for the same profile) and not reversible from the application layer. The hash is implemented with the Web Crypto API (`crypto.subtle.digest`).

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to upact
+
+## How the spec grows
+
+upact operates on **inverse kinematics**: the spec grows from concrete consumer need, not from speculative design. A change to `SPEC.md`, `src/types.ts`, or the capability vocabulary begins with an adapter author or application developer who needs something the current spec does not provide — not the other way around.
+
+Before proposing a spec change, run the five-test audit below. All five tests apply; a change that fails any one does not land.
+
+### The five-test audit
+
+**1. Concrete-need.** Does a shipped or actively-in-development adapter *require* this change to function correctly? "Would be useful for" is not sufficient. Name the adapter and the specific operation that fails without the change.
+
+**2. Minimum-viable.** Is this the smallest change to the spec (types, MUST clauses, capability vocabulary) that satisfies the concrete need? If a narrower change would work, make that one instead.
+
+**3. Substrate-agnosticism.** Does the change make sense for at least two structurally different substrates — one enforcement-camp, one pre-conforming (see `docs/adapter-shapes.md`)? A change that only works for one substrate shape is a substrate-specific extension, not a spec change.
+
+**4. Binding-integrity.** Does the change preserve the self-binding contract? Spec changes MUST NOT:
+  - Expose additional substrate fields through the port (email, phone, IP, substrate-internal handles)
+  - Add OPTIONAL fields to `Upactor` whose presence reveals substrate-type information to the application
+  - Weaken the Session opacity guarantee (§7.4)
+  - Weaken the adapter back-channel closure requirement (§7.5)
+
+**5. Disclosure.** Does the change require documentation of a new disclosure obligation for conforming adapters — in the conformance statement (§9), the security considerations (§10), or the deferred-decisions register (§12)?
+
+### Worked example: adding `lifecycle`
+
+When `lifecycle: { expires_at?: number; renewable: ... }` was first proposed for `Upactor`, the audit looked like this:
+
+- **Concrete-need:** OIDC adapter needs `jwt.exp` for cookie renewal decisions. Named consumer: dyad M2 SvelteKit layout, `+layout.server.ts` session check. — *passes.*
+- **Minimum-viable:** Could the adapter just re-call `issueRenewal` instead? Yes, for dyad M2. The field is pre-emptive. — *fails.*
+- **Result:** Deferred to §12 (D-SPEC-4). Returns when the OIDC adapter concretely needs it.
+
+### Worked example: SimpleX `messaging` capability
+
+When `messaging` was proposed as a capability for `@prefig/upact-simplex`:
+
+- **Concrete-need:** SimpleX affords messaging. No current dyad UI gates on `capabilities.has('messaging')`. No shipped consumer. — *fails.*
+- **Result:** `@prefig/upact-simplex` ships with `capabilities = []`. Capability lands when a consumer surfaces.
+
+## Adapter conformance
+
+New adapters MUST pass the five-test audit for any spec amendment their design requires. Adapters that work within the existing spec need not run the audit — the spec is already there.
+
+All adapters MUST:
+
+1. Ship a `CONFORMANCE.md` (template in this repo) declaring the spec version, substrate, threat model, capability self-declaration, and `AuthError` mapping table.
+2. Ship a sixteen-vector reflection test (see `@prefig/upact-supabase/tests/back-channel.test.ts`) asserting that no sentinel substrate token leaks through the adapter instance.
+3. Use `createSession` from `@prefig/upact` for Session construction, or pass an equivalent sixteen-vector test suite.
+
+## AI-Involvement trailers
+
+upact acknowledges LLM contributions to normative content under an `AI-Involvement` trailer on git commits. The trailer records the character of AI involvement so readers can calibrate the provenance of what they are reading.
+
+```
+AI-Involvement: <tier>
+```
+
+Five tiers:
+
+| Tier | When to use |
+|---|---|
+| `autonomous` | AI generated the full commit with no human review of content (rare; avoid for normative paths) |
+| `authored` | AI wrote the primary content; human reviewed and accepted with minor edits |
+| `collaborative` | Human and AI contributed substantial portions; hard to separate authorship |
+| `assisted` | Human wrote the primary content; AI provided suggestions or structured material the human evaluated |
+| `commit-message-only` | AI wrote only the commit message; content is human-authored |
+
+The trailer is advisory, not mechanical. Its purpose is honest attribution, not compliance theatre. Use the tier that most accurately describes the commit.
+
+Normative paths (`SPEC.md`, `src/types.ts`, capability vocabulary) that carry `autonomous` or `authored` tiers are permitted at v0.1. This posture is revisited before v1.0.
+
+## Spec versioning and stability
+
+- v0.x: breaking changes between minor versions are permitted. The maintainer (Theodore Evans) makes decisions.
+- v1.0: first stable version. Decisions about the core capability vocabulary (§5.1) and MUST clauses (§7) move to a working group of ≥3 conforming-adapter authors. See `GOVERNANCE.md`.
+
+## What goes in the deferred-decisions register
+
+`SPEC.md §12` is the register of features that passed the concrete-need test *eventually* — meaning a concrete need exists in principle — but failed minimum-viable or substrate-agnosticism, or whose consumer is not yet shipped. Items enter the register with a brief rationale; they reactivate when the consumer surfaces or a shipped adapter forces the question.
+
+Do not treat §12 entries as a backlog. They are a deliberate holding pattern, not a roadmap.
+
+## Submissions
+
+- Open an issue before a PR for anything that touches `SPEC.md` or `src/types.ts`.
+- Adapter packages are independent repos under the `@prefig/` namespace; open issues on the relevant adapter repo.
+- Discussion happens in issues. Normative decisions land in commits. The commit message carries the decision; the issue carries the context.

package/GOVERNANCE.md

@@ -0,0 +1,34 @@
+# Governance
+
+## v0.x (current)
+
+Theodore Evans is the maintainer. Decisions about the spec, capability vocabulary, and normative content are made by the maintainer, informed by adapter authors and application developers through issues and PRs.
+
+The inverse-kinematics principle (see `CONTRIBUTING.md`) is the primary constraint on spec growth. The maintainer applies it consistently; so should anyone making a case for a change.
+
+Decisions are recorded in commits to `SPEC.md` and `ROADMAP.md`, not in issue threads. Issue threads carry context; the commit is the decision.
+
+## v1.0 (target)
+
+Decisions about the core capability vocabulary (§5.1) and MUST clauses (§7) move to a working group of ≥3 conforming-adapter authors at v1.0. A *conforming-adapter author* is an organisation or individual who:
+
+- Maintains a published `@prefig/upact-*` package that passes the sixteen-vector reflection test,
+- has shipped a `CONFORMANCE.md` against a specific version of the spec, and
+- is actively maintaining the adapter (a PR or release in the last twelve months).
+
+The working group operates on rough consensus. When rough consensus is absent, the maintainer retains casting vote.
+
+Additions to the capability vocabulary after v1.0 require a working group decision AND demonstration of:
+
+1. Implementation by ≥2 independent conforming adapters, and
+2. Consumption by ≥1 shipped application.
+
+Changes to MUST clauses require the same bar plus a migration period during which the old behaviour remains valid.
+
+## Forks
+
+upact is dual-licensed (CC BY 4.0 / Apache-2.0; see `LICENSE` and `LICENSE-CODE`). Forks are permitted; they are asked to rename the package to avoid registry confusion. Forked packages that claim upact conformance MUST reference the specific version of the spec they conform to in their `CONFORMANCE.md`.
+
+## Conflicts
+
+Disputes about spec interpretation go to the issue tracker. The maintainer resolves them by issuing a normative clarification (a commit to `SPEC.md`). Disputes about governance itself go to the working group at v1.0; before v1.0, they go to the maintainer.