Spec: Typed Owner Identity

[George-RD]

Problem Statement

OpenSpine's owner identity is fragmented across three AppState scalars (owner_user_id: i64, owner_principal_id: Ulid, owner_identity_id: Ulid) and four TaskGrant.user value shapes (stringified principal_id, stringified user_id, literal "owner", literal "kernel"). This fragmentation makes identity-aware audit queries difficult, sources ApprovalRecord.approved_by from static config (not verified surface), and leaves no typed actor dimension on AuditEvent.

Consequences:

• No single source of truth for owner identity
• ApprovalRecord.approved_by is raw config, not verified principal (bug: doesn't record actual approver)
• AuditEvent has no actor link, breaking identity-aware responsibility queries
• Grant MAC-covered user field accepts non-Ulid shapes (type-unsafe)
• Future tenancy/multi-principal models will reopen this spec if not designed for extensibility now

Solution

Introduce a typed PrincipalId(Ulid) newtype and single OwnerPrincipal aggregate to consolidate identity. Retype TaskGrant.user (and RootAuthority.user, SelectionToken.actor) to PrincipalId. Source ApprovalRecord.approved_by from the verified OwnerSurfaceRef::principal_id() instead of config. Add an optional audit actor dimension to AuditEvent. All changes preserve existing grant MACs and invariants (D-006, D-007, AD-146, AD-148).

Key design choices:

• PrincipalId(Ulid) newtype: Serializes identically to Ulid.to_string(), preserving grant MACs for existing sealed grants holding a stringified Ulid. Removes non-Ulid shapes by construction.
• OwnerPrincipal aggregate: Bundles principal_id, identity_id, and Telegram binding (private field, accessible only via channel-binding accessor). Minted once at bootstrap. Replaces three scalars with one source of truth. Carries zero authority fields (D-006).
• Verified surface sourcing: ApprovalRecord.approved_by now set from OwnerSurfaceRef::principal_id() at approval time (pipeline/approval.rs, pipeline/plan_approval.rs), not static config. Historical rows not backfilled (immutability).
• Optional audit actor: AuditEvent gains actor: Option<PrincipalId>, populated from verified surface on owner-authored events (approval, review, escalation), None for system/worker events.
• MAC preservation: RootAuthority::canonical_bytes keeps "user" as mandatory string with identical bytes; PrincipalId serde form matches Ulid.to_string(), so existing MACs remain valid.

User Stories

Auditor: Trace approval lineage

As an auditor reviewing compliance, I want to query which principal approved each action, with confidence it was verified at approval time (not a static config value).

Acceptance: ApprovalRecord.approved_by is a PrincipalId sourced from verified OwnerSurfaceRef. Historical records (pre-change) are immutable; audit queries join approval + grant to recover context.

Bell: Integrate principal identity into per-tenant instances

As Bell (instance-per-tenant product) integrating with OpenSpine, I want owner identity typed so I can later extend (tenant, principal, contact) without reopening the spec.

Acceptance: Design is additive. PrincipalId is channel-neutral; OwnerPrincipal carries no multi-tenant semantics. Future tenancy models can extend without requiring spec changes.

Lyra runtime: Audit identity dimension

As the runtime's audit system, I want to log the principal that authored each owner action (approval, escalation), enabling identity-aware compliance queries.

Acceptance: AuditEvent carries optional typed actor dimension. Queries can filter/aggregate by actor to answer "which actions did the owner approve this week?".

Implementation Decisions

D-001: TaskGrant.user representation

Decision: Retype TaskGrant.user from String to PrincipalId(Ulid) newtype.

Why: Preserves MAC bytes (PrincipalId serde = Ulid.to_string()); removes non-Ulid shapes by construction; kills ~35 construction sites setting user = format!("{}", some_value) or string literals.

Affected: TaskGrant.user, RootAuthority.user (grant_chain.rs), SelectionToken.actor, ~35 mint sites (compose.rs, approval callbacks, worker commissioning).

D-002: Owner-identity aggregate

Decision: Single OwnerPrincipal aggregate (principal_id: PrincipalId, identity_id: Ulid, telegram_binding: i64 via accessor).

Why: One source of truth replacing three scalars. Telegram i64 hidden behind channel-binding accessor (no generic kernel code reads raw i64). Preserves D-006 (identity carries no authority).

Constructor: bootstrap_owner_principal(telegram_id: i64, principal_id: Ulid, identity_id: Ulid) called once at kernel startup. Read-only after bootstrap.

D-003: Audit actor dimension

Decision: Optional typed PrincipalId actor on AuditEvent (not full OwnerSurfaceRef).

Why: Channel-neutral; channel-specific detail stays in grant/review rows. Minimal audit footprint (most events have actor=None).

Population: Some(principal_id) on owner-authored (approval, review, escalation), None on system/worker events.

D-004: ApprovalRecord.approved_by migration

Decision: Retype to PrincipalId; source from verified OwnerSurfaceRef::principal_id() at two callback sites; no backfill of historical rows.

Why: Fixes bug where approvals record config value, not verified principal. Immutability preserves digest-bound evidence integrity. Forward-looking only.

Callbacks: pipeline/approval.rs::handle_draft_approval_callback, pipeline/plan_approval.rs::handle_plan_approval_callback.

D-005: MAC byte preservation

Decision: RootAuthority::canonical_bytes generates identical bytes before/after PrincipalId retype.

Why: Existing sealed grants (holding stringified Ulid in user field) pass MAC verification without modification. New grants set owner PrincipalId correctly; literals "owner"/"kernel" are type-invalid.

Reseal path (if legacy literals exist in store): Detect via query, backfill to canonical owner_principal_id, re-mint grant as valid descendant in chain.

Testing Decisions

Authority-sensitive verification (per conventions.md)

Because this change affects identity resolution, task grant composition, approval recording, and audit:

1. MAC invariant test: Before/after PrincipalId serialization produces identical bytes to Ulid.to_string(); a grant sealed with user="01ARZ3..." verifies identically after TaskGrant.user is retyped to PrincipalId.

2. D-006 invariant (identity ≠ authority): OwnerPrincipal has zero authority fields; PrincipalId type has no authority-granting constructors; composed grant with owner PrincipalId set correctly passes gate() with identical authority.

3. D-007 invariant (grant is only authority): Revoking the grant revokes all authority, regardless of principal_id value. No new authority sources introduced.

4. AD-146 invariant (single owner principal v1): Exactly one OwnerPrincipal minted at bootstrap with principal_id set; all grants in v1 carry the same owner PrincipalId; no code path creates a second principal (v1 is single-owner; tenancy out-of-scope).

5. AD-148 invariant (kernel-owned MAC-covered fields): Mutating principal_id in a sealed grant invalidates its MAC; thread_id (if populated) also MAC-covered.

6. Approval principal sourcing: ApprovalRecord.approved_by set from OwnerSurfaceRef::principal_id(), not state.owner_user_id; approval matching works with PrincipalId comparisons; gate receives PrincipalId.

7. E2E regression: Minimal task with typed identity sent through gate with approval; gate accepts grant, approvals match on PrincipalId, audit log records actor.

Out of Scope

• Tenancy implementation: Bell v1 is instance-per-tenant; tenancy design follows separate decision. This design is additive and leaves room.
• OAuth or multi-principal model: v1 has one bootstrapped owner. Future tenancy/OAuth decisions are orthogonal.
• Channel-specific detail: Surface-specific payload stays in OwnerSurfaceRef accessors, not exposed generically.
• WhatsApp connector: Currently out of scope; AD-148 thread binding waits for channel-agnostic enablement.
• Relationship-keyed disclosure: AD-146 design, separate change.
• Standing rule authority: AD-010 design, separate change.

Further Notes

Invariants preserved:

• ✅ D-006: Identity carries no authority (OwnerPrincipal has zero authority fields)
• ✅ D-007: Task grant is only authority (no new authority sources)
• ✅ AD-146: Single owner principal v1, additive for future tenancy
• ✅ AD-148: Kernel-owned MAC-covered fields (PrincipalId on user, thread_id dormant)

Downstream cutover (post-implementation):

• WorkerIdentity.owner: String → PrincipalId
• OperationAuthorization.owner_principal_id: (already typed, no change)
• SQL queries reading json_extract(grant, '$.user'): String → PrincipalId comparisons

Migration paths:

• Grant MACs: No change; existing sealed grants verify without reseal (PrincipalId serde matches Ulid.to_string())
• Legacy literals (if persisted): Query for non-Ulid user values; backfill to canonical owner_principal_id; re-mint as valid descendants
• ApprovalRecord historical rows: No backfill (immutable, digest-bound evidence); forward-looking queries join with grant

Lane context: Wayfinder map #182; design ticket #188 (closed).

---

🤖 Typed owner identity spec (inline, self-contained)

[coderabbitai]

Coding Plan

Summary

This ticket authors an OpenSpec change document set, not Rust code. The plan produces proposal.md, design.md, four per-area spec delta files, and tasks.md.

The spec deltas define a #[serde(transparent)] PrincipalId(Ulid), an OwnerPrincipal aggregate, and the retyping of grant, selection, approval, and audit identity fields to PrincipalId.

MAC byte preservation is documented and required, because the default ulid serialization matches Ulid::to_string() and composition already stringifies the principal id.

The change preserves D-006, D-007, AD-146, and AD-148, and it validates against openspec --strict with per-requirement Scenario blocks.

Design Choices

Design Choice 1: Spec delta file layout: single `specs.md` or per-area `specs//spec.md`

Options Considered:

1. One combined specs.md file holding all four areas.
2. Per-area delta files under specs/<area>/spec.md, one per capability.

Chosen Option: 2

Rationale: The ticket text names specs.md, but the OpenSpec convention requires one delta file for each affected capability area. The convention and openspec validate --strict expect per-area delta files. Per-area files avoid validation failure.

Design Choice 2: Audit actor requirement placement: new `audit-and-logging` capability or existing `audit-artifact-store`

Options Considered:

1. Create a net-new audit-and-logging capability spec area.
2. Add the AuditEvent.actor requirement as ## ADDED Requirements to the existing audit-artifact-store spec.

Chosen Option: 2

Rationale: The ticket names audit-and-logging, but only audit-artifact-store exists in openspec/specs/. Placing the actor requirement in audit-artifact-store keeps all audit requirements in one capability. This avoids fragmenting the audit spec.

Design Choice 3: Approver-of-record requirement type in `responsibility-contract`

Options Considered:

1. ## ADDED Requirements for a new "approver-of-record MUST be a typed principal" requirement.
2. ## MODIFIED Requirements that extends the existing channel-neutral owner-review requirement.

Chosen Option: 1

Rationale: The spec has no approved_by text today, but it has an "Owner review MUST be channel-neutral and digest-bound" requirement about principal-bound decisions. The approver-of-record concept is a genuinely new normative statement. An ADDED requirement is clearer and does not overload the existing owner-review requirement.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Scaffold the change and author proposal and design

This phase creates the change directory and writes the two narrative documents. These two documents set the problem framing, the domain model, the decision citations, and the MAC-preservation reasoning that the spec deltas and tasks depend on.

Task 1: Create the change directory and author `proposal.md`

Write the change proposal in the modern OpenSpec header format.

• Create openspec/changes/2026-08-20-design-typed-owner-identity/.
• Author proposal.md using the modern header set: ## Layer, ## Authority sensitivity, ## Dependencies, ## Why, ## What Changes, ## Acceptance Criteria, ## Out of Scope.
• State the layer as OpenSpine core and mark authority sensitivity, because the change touches runtime authority fields (TaskGrant.user, RootAuthority.user).
• In ## Dependencies, name the archived implement-identity-store-and-principal change as a satisfied precondition, and cite AD-146, AD-148, D-006, D-007.
• In ## Why, describe the current fragmentation: three untyped AppState owner scalars and four TaskGrant.user value shapes (principal Ulid string, raw Telegram i64 string, literal "owner", literal "kernel"/worker ids).
• In ## What Changes, list the five deliverables: PrincipalId(Ulid), OwnerPrincipal, grant/selection field retyping, ApprovalRecord.approved_by retyping, and optional AuditEvent.actor.
• In ## Out of Scope, state explicit non-goals: no tenancy, no OAuth, no multi-principal, v1 single-owner only.

Task 2: Author `design.md`

Write the domain model, key decisions, alternatives, and MAC-preservation analysis.

• Author design.md with sections: an "Approach"/domain-model section, ## Key decisions, ## Alternatives considered, and a closing "What does not change" section.
• Describe the domain model: PrincipalId(Ulid) as a #[serde(transparent)] newtype, and OwnerPrincipal as a typed aggregate exposing principal_id(), identity_id(), and telegram_binding() accessors. Relate telegram_binding() to the existing OwnerConfig.telegram_user_id, the hashed Identifier{kind: TelegramUserId} on Identity, and OwnerSurfaceRef::verified_telegram, without collapsing the D-006 identity-vs-authority separation.
• Document the MAC byte-preservation analysis: the default ulid Serialize emits the Crockford string identical to Ulid::to_string(), and compose.rs already sets user: input.principal_id.to_string(), so genuine composed grants remain byte-identical after retyping. State that ulid_as_u128/ulid_as_uuid must not be used.
• Document how the four TaskGrant.user value shapes normalize to PrincipalId, and specify the migration path: ApprovalRecord backfill is none; legacy sealed grants that used non-principal literals require reseal only if present. Reference the existing legacy-compatibility pattern in grant_chain.rs (AD-060, AD-148) and the regression-test style in grant_chain/tests.rs.
• Specify that approved_by MUST be sourced from a verified OwnerSurfaceRef principal id, and replace the current raw owner_user_id.to_string() source used in pipeline/approval.rs and pipeline/plan_approval.rs.
• In ## Key decisions, cite AD-146, AD-148, D-006, D-007 inline and explain how each is preserved.
• In ## Alternatives considered, record rejected options (for example, keeping String fields, or a separate audit capability), with reasons.

🤖 Prompt for AI agents

Implement Phase 1: create the change directory and author the two narrative
documents (`proposal.md` and `design.md`) for the OpenSpec change
`2026-08-20-design-typed-owner-identity`.

First, create the directory
`openspec/changes/2026-08-20-design-typed-owner-identity/`.

Then author `proposal.md` using the header set: `## Layer`, `## Authority
sensitivity`, `## Dependencies`, `## Why`, `## What Changes`, `## Acceptance
Criteria`, `## Out of Scope`.
- Set layer to OpenSpine core and mark authority sensitivity, since the change
touches runtime authority fields (`TaskGrant.user`, `RootAuthority.user`).
- Under `## Dependencies`, name the archived
`implement-identity-store-and-principal` change as a satisfied precondition and
cite AD-146, AD-148, D-006, D-007.
- Under `## Why`, describe the current fragmentation across three untyped
`AppState` owner scalars and the four `TaskGrant.user` value shapes (principal
`Ulid` string, raw Telegram `i64` string, literal `"owner"`, literal
`"kernel"`/worker ids).
- Under `## What Changes`, list the five deliverables: `PrincipalId(Ulid)`,
`OwnerPrincipal`, grant/selection field retyping, `ApprovalRecord.approved_by`
retyping, and optional `AuditEvent.actor`.
- Under `## Out of Scope`, state the non-goals: no tenancy, no OAuth, no
multi-principal, v1 single-owner only.

Then author `design.md` with sections: an approach/domain-model section, `## Key
decisions`, `## Alternatives considered`, and a closing "What does not change"
section.
- Describe `PrincipalId(Ulid)` as a `#[serde(transparent)]` newtype and
`OwnerPrincipal` as a typed aggregate exposing `principal_id()`,
`identity_id()`, and `telegram_binding()` accessors. Relate `telegram_binding()`
to `OwnerConfig.telegram_user_id`, the hashed `Identifier{kind: TelegramUserId}`
on `Identity`, and `OwnerSurfaceRef::verified_telegram`, while keeping the D-006
identity-vs-authority separation intact.
- Document the MAC byte-preservation analysis: default `ulid` `Serialize`
matches `Ulid::to_string()`, and `compose.rs` already sets `user:
input.principal_id.to_string()`, so composed grants stay byte-identical after
retyping. State that `ulid_as_u128`/`ulid_as_uuid` must not be used.
- Document how the four `TaskGrant.user` value shapes normalize to
`PrincipalId`, and define the migration path: no `ApprovalRecord` backfill;
legacy sealed grants with non-principal literals require reseal only if present.
Reference the legacy-compatibility pattern in `grant_chain.rs` (AD-060, AD-148)
and the regression-test style in `grant_chain/tests.rs`.
- Specify that `approved_by` MUST come from a verified `OwnerSurfaceRef`
principal id, replacing the raw `owner_user_id.to_string()` source used in
`pipeline/approval.rs` and `pipeline/plan_approval.rs`.
- In `## Key decisions`, cite AD-146, AD-148, D-006, D-007 inline and explain
how each is preserved.
- In `## Alternatives considered`, record rejected options such as keeping
`String` fields or a separate audit capability, with reasons for rejection.

Phase 2: Author the requirement spec deltas

This phase writes the five requirements across four capability areas. Each requirement follows the ADDED/MODIFIED rule from the exploration and includes at least one #### Scenario: block. This phase produces the falsifiable content that tasks.md verifies.

Task 1: Author `specs/identity-store/spec.md` — OwnerPrincipal aggregate

Add the typed owner aggregate requirement.

• Create specs/identity-store/spec.md.
• Use ## MODIFIED Requirements, because the Principal/principal_id/single-owner requirements already exist in openspec/specs/identity-store/spec.md.
• State that the owner MUST be exposed as a typed OwnerPrincipal aggregate with typed accessors for principal_id, identity_id, and telegram_binding, replacing the three separate untyped AppState scalars.
• Preserve AD-146 (single-owner v1) and D-006 (the aggregate carries no authority fields).
• Add Given/When/Then scenarios, including one where the aggregate resolves the owner principal id and one that asserts the aggregate exposes no authority field.

Task 2: Author `specs/core-runtime-schemas/spec.md` — PrincipalId and grant reference typing

Add the newtype requirement and the grant/selection retyping requirement.

• Create specs/core-runtime-schemas/spec.md.
• Use ## ADDED Requirements for a new requirement: a PrincipalId type MUST wrap Ulid and MUST serialize byte-identically to Ulid::to_string().
• Use ## MODIFIED Requirements for the existing "Task grants MUST be explicit live authority objects" and "TaskGrant MUST carry an optional dormant thread_id" requirements, to state that TaskGrant.user, RootAuthority.user, and SelectionToken.actor MUST be typed as PrincipalId, and that this retype MUST NOT change the sealed MAC bytes of grants already composed from a principal id.
• Add scenarios: one asserting serialization equality with Ulid::to_string(), one asserting that a pre-existing sealed grant still verifies after the retype (mirroring pre_egress_grant_mac_still_verifies_after_upgrade), and one asserting that mutating the typed user field invalidates the MAC.

Task 3: Author `specs/responsibility-contract/spec.md` — approver-of-record

Add the typed approver requirement.

• Create specs/responsibility-contract/spec.md.
• Use ## ADDED Requirements for a requirement that ApprovalRecord.approved_by MUST be a PrincipalId sourced from a verified OwnerSurfaceRef, not a raw Telegram user id string.
• Preserve D-007 (approval does not create a second live authority object).
• Add scenarios: one where a verified owner surface produces a typed approver-of-record, and one where an approval without a verified surface fails closed.

Task 4: Author `specs/audit-artifact-store/spec.md` — optional audit actor

Add the optional actor dimension requirement.

• Create specs/audit-artifact-store/spec.md.
• Use ## ADDED Requirements for a requirement that AuditEvent MAY carry an optional actor: Option<PrincipalId> dimension for identity-aware audit trails.
• State that the field MUST default absent for legacy and system rows, and MUST preserve the existing hash-chain behavior for rows that omit it (mirroring the aggregate_id/aggregate_seq backward-compatible pattern).
• Add scenarios: one where an owner-driven audit row records the typed actor, and one where a system row omits the actor and the hash chain still verifies.

🤖 Prompt for AI agents

Implement Phase 2: author the four spec delta files that define the five
requirements for typed owner identity. Each requirement needs at least one `####
Scenario:` block, using Given/When/Then style scenarios.

1. Author `specs/identity-store/spec.md`:
- Use `## MODIFIED Requirements`, since `Principal`/`principal_id`/single-owner
requirements already exist in `openspec/specs/identity-store/spec.md`.
- State that the owner MUST be exposed as a typed `OwnerPrincipal` aggregate
with typed accessors for `principal_id`, `identity_id`, and `telegram_binding`,
replacing the three separate untyped `AppState` scalars.
- Preserve AD-146 (single-owner v1) and D-006 (the aggregate carries no
authority fields).
- Add scenarios: one where the aggregate resolves the owner principal id, and
one asserting the aggregate exposes no authority field.

2. Author `specs/core-runtime-schemas/spec.md`:
- Use `## ADDED Requirements` for a new requirement: a `PrincipalId` type MUST
wrap `Ulid` and MUST serialize byte-identically to `Ulid::to_string()`.
- Use `## MODIFIED Requirements` for the existing "Task grants MUST be explicit
live authority objects" and "TaskGrant MUST carry an optional dormant thread_id"
requirements: state that `TaskGrant.user`, `RootAuthority.user`, and
`SelectionToken.actor` MUST be typed as `PrincipalId`, and that the retype MUST
NOT change the sealed MAC bytes of grants already composed from a principal id.
- Add scenarios: one asserting serialization equality with `Ulid::to_string()`,
one asserting a pre-existing sealed grant still verifies after the retype
(mirror `pre_egress_grant_mac_still_verifies_after_upgrade`), and one asserting
that mutating the typed `user` field invalidates the MAC.

3. Author `specs/responsibility-contract/spec.md`:
- Use `## ADDED Requirements` for a requirement that
`ApprovalRecord.approved_by` MUST be a `PrincipalId` sourced from a verified
`OwnerSurfaceRef`, not a raw Telegram user id string.
- Preserve D-007 (approval does not create a second live authority object).
- Add scenarios: one where a verified owner surface produces a typed
approver-of-record, and one where an approval without a verified surface fails
closed.

4. Author `specs/audit-artifact-store/spec.md`:
- Use `## ADDED Requirements` for a requirement that `AuditEvent` MAY carry an
optional `actor: Option<PrincipalId>` dimension for identity-aware audit trails.
- State the field MUST default absent for legacy and system rows, and MUST
preserve the existing hash-chain behavior for rows that omit it (mirror the
`aggregate_id`/`aggregate_seq` backward-compatible pattern).
- Add scenarios: one where an owner-driven audit row records the typed actor,
and one where a system row omits the actor and the hash chain still verifies.

Phase 3: Author tasks and validate the change

This phase writes the implementation checklist for the eventual code work and validates the whole change against OpenSpec rules. The tasks encode the authority-sensitive verification and MAC-preservation checks called out in the acceptance criteria.

Task 1: Author `tasks.md`

Write the phased, authority-sensitive implementation checklist.

• Author tasks.md as numbered ## N. phases with - [ ] checkboxes.
• Phase 1 (schema + identity layer): add PrincipalId, add OwnerPrincipal, and contract-first serialization tests proving byte equality with Ulid::to_string().
• Phase 2 (grant and selection retyping): retype TaskGrant.user, RootAuthority.user, and SelectionToken.actor, and add a MAC regression test proving pre-existing sealed grants verify without reseal.
• Phase 3 (approver and audit): retype ApprovalRecord.approved_by sourced from a verified OwnerSurfaceRef, and add the optional AuditEvent.actor field with a backward-compatible default.
• Add an explicit authority-sensitive verification phase, labeled as such, that lists checks tied to D-006 (aggregate and records carry no authority field), D-007 (no second live authority object), AD-146 (single-owner preserved), and AD-148 (thread binding unchanged and still MAC-committed only when present).
• Add a final phase for records and landing: decision-log update, openspec validate --changes 2026-08-20-design-typed-owner-identity --strict, and ./scripts/check.sh.

Task 2: Validate the change

Run OpenSpec validation and correct header issues.

• Run openspec validate --changes 2026-08-20-design-typed-owner-identity --strict.
• If validation reports an ADDED ... already exists error for any requirement, change that requirement header to ## MODIFIED Requirements and re-run, per the OpenSpec ceremony rule.
• Confirm every requirement in every delta file includes at least one #### Scenario: block, to satisfy the acceptance criterion "All five requirements include Scenario blocks."

🤖 Prompt for AI agents

Implement Phase 3: author `tasks.md` and validate the whole change.

Author `tasks.md` as numbered `## N.` phases with `- [ ]` checkboxes:
- Phase 1 (schema + identity layer): add `PrincipalId`, add `OwnerPrincipal`,
and contract-first serialization tests proving byte equality with
`Ulid::to_string()`.
- Phase 2 (grant and selection retyping): retype `TaskGrant.user`,
`RootAuthority.user`, and `SelectionToken.actor`, and add a MAC regression test
proving pre-existing sealed grants verify without reseal.
- Phase 3 (approver and audit): retype `ApprovalRecord.approved_by` sourced from
a verified `OwnerSurfaceRef`, and add the optional `AuditEvent.actor` field with
a backward-compatible default.
- Add an explicit authority-sensitive verification phase, labeled as such,
listing checks tied to D-006 (aggregate and records carry no authority field),
D-007 (no second live authority object), AD-146 (single-owner preserved), and
AD-148 (thread binding unchanged and still MAC-committed only when present).
- Add a final phase for records and landing: decision-log update, `openspec
validate --changes 2026-08-20-design-typed-owner-identity --strict`, and
`./scripts/check.sh`.

Then validate the change:
- Run `openspec validate --changes 2026-08-20-design-typed-owner-identity
--strict`.
- If validation reports an `ADDED ... already exists` error for any requirement,
change that requirement's header to `## MODIFIED Requirements` and re-run,
following the OpenSpec ceremony rule.
- Confirm every requirement in every delta file includes at least one `####
Scenario:` block, satisfying the acceptance criterion "All five requirements
include Scenario blocks."

Research

This repository uses OpenSpec to govern change proposals. Each change lives under openspec/changes/<id>/ and holds proposal.md, design.md, tasks.md, and specs/<area>/spec.md delta files. Requirement deltas use ## ADDED/MODIFIED/REMOVED Requirements headers, ### Requirement: titles with MUST/SHALL language, and at least one #### Scenario: block for each requirement. Canonical decisions live in .raw/openspine-decision-log.md (D-0XX) and .raw/openspine-agentos-design-log.md (AD-0XX).

The relevant schema code is in crates/openspine-schemas/src/. Today TaskGrant.user, RootAuthority.user, SelectionToken.user/selected_by, and ApprovalRecord.approved_by are plain String. AppState (in crates/openspine-kernel/src/pipeline/mod.rs) holds three separate owner scalars: owner_user_id: i64, owner_principal_id: Ulid, owner_identity_id: Ulid. Grant chain MACs (grant_chain.rs) commit canonical JSON bytes, so any field byte change invalidates sealed MACs. The ulid crate is pinned at 1.2.1 with serde. Its default Serialize emits the same Crockford string as Ulid::to_string(). Therefore a #[serde(transparent)] PrincipalId(Ulid) is byte-identical to the current stringified form. The baseline identity-store spec (openspec/specs/identity-store/spec.md) already defines Principal/principal_id requirements. The target change directory does not exist yet.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: create the change directory and author the two narrative
documents (`proposal.md` and `design.md`) for the OpenSpec change
`2026-08-20-design-typed-owner-identity`.

First, create the directory
`openspec/changes/2026-08-20-design-typed-owner-identity/`.

Then author `proposal.md` using the header set: `## Layer`, `## Authority
sensitivity`, `## Dependencies`, `## Why`, `## What Changes`, `## Acceptance
Criteria`, `## Out of Scope`.
- Set layer to OpenSpine core and mark authority sensitivity, since the change
touches runtime authority fields (`TaskGrant.user`, `RootAuthority.user`).
- Under `## Dependencies`, name the archived
`implement-identity-store-and-principal` change as a satisfied precondition and
cite AD-146, AD-148, D-006, D-007.
- Under `## Why`, describe the current fragmentation across three untyped
`AppState` owner scalars and the four `TaskGrant.user` value shapes (principal
`Ulid` string, raw Telegram `i64` string, literal `"owner"`, literal
`"kernel"`/worker ids).
- Under `## What Changes`, list the five deliverables: `PrincipalId(Ulid)`,
`OwnerPrincipal`, grant/selection field retyping, `ApprovalRecord.approved_by`
retyping, and optional `AuditEvent.actor`.
- Under `## Out of Scope`, state the non-goals: no tenancy, no OAuth, no
multi-principal, v1 single-owner only.

Then author `design.md` with sections: an approach/domain-model section, `## Key
decisions`, `## Alternatives considered`, and a closing "What does not change"
section.
- Describe `PrincipalId(Ulid)` as a `#[serde(transparent)]` newtype and
`OwnerPrincipal` as a typed aggregate exposing `principal_id()`,
`identity_id()`, and `telegram_binding()` accessors. Relate `telegram_binding()`
to `OwnerConfig.telegram_user_id`, the hashed `Identifier{kind: TelegramUserId}`
on `Identity`, and `OwnerSurfaceRef::verified_telegram`, while keeping the D-006
identity-vs-authority separation intact.
- Document the MAC byte-preservation analysis: default `ulid` `Serialize`
matches `Ulid::to_string()`, and `compose.rs` already sets `user:
input.principal_id.to_string()`, so composed grants stay byte-identical after
retyping. State that `ulid_as_u128`/`ulid_as_uuid` must not be used.
- Document how the four `TaskGrant.user` value shapes normalize to
`PrincipalId`, and define the migration path: no `ApprovalRecord` backfill;
legacy sealed grants with non-principal literals require reseal only if present.
Reference the legacy-compatibility pattern in `grant_chain.rs` (AD-060, AD-148)
and the regression-test style in `grant_chain/tests.rs`.
- Specify that `approved_by` MUST come from a verified `OwnerSurfaceRef`
principal id, replacing the raw `owner_user_id.to_string()` source used in
`pipeline/approval.rs` and `pipeline/plan_approval.rs`.
- In `## Key decisions`, cite AD-146, AD-148, D-006, D-007 inline and explain
how each is preserved.
- In `## Alternatives considered`, record rejected options such as keeping
`String` fields or a separate audit capability, with reasons for rejection.
===============================================================================

Task: 2

Implement Phase 2: author the four spec delta files that define the five
requirements for typed owner identity. Each requirement needs at least one `####
Scenario:` block, using Given/When/Then style scenarios.

1. Author `specs/identity-store/spec.md`:
- Use `## MODIFIED Requirements`, since `Principal`/`principal_id`/single-owner
requirements already exist in `openspec/specs/identity-store/spec.md`.
- State that the owner MUST be exposed as a typed `OwnerPrincipal` aggregate
with typed accessors for `principal_id`, `identity_id`, and `telegram_binding`,
replacing the three separate untyped `AppState` scalars.
- Preserve AD-146 (single-owner v1) and D-006 (the aggregate carries no
authority fields).
- Add scenarios: one where the aggregate resolves the owner principal id, and
one asserting the aggregate exposes no authority field.

2. Author `specs/core-runtime-schemas/spec.md`:
- Use `## ADDED Requirements` for a new requirement: a `PrincipalId` type MUST
wrap `Ulid` and MUST serialize byte-identically to `Ulid::to_string()`.
- Use `## MODIFIED Requirements` for the existing "Task grants MUST be explicit
live authority objects" and "TaskGrant MUST carry an optional dormant thread_id"
requirements: state that `TaskGrant.user`, `RootAuthority.user`, and
`SelectionToken.actor` MUST be typed as `PrincipalId`, and that the retype MUST
NOT change the sealed MAC bytes of grants already composed from a principal id.
- Add scenarios: one asserting serialization equality with `Ulid::to_string()`,
one asserting a pre-existing sealed grant still verifies after the retype
(mirror `pre_egress_grant_mac_still_verifies_after_upgrade`), and one asserting
that mutating the typed `user` field invalidates the MAC.

3. Author `specs/responsibility-contract/spec.md`:
- Use `## ADDED Requirements` for a requirement that
`ApprovalRecord.approved_by` MUST be a `PrincipalId` sourced from a verified
`OwnerSurfaceRef`, not a raw Telegram user id string.
- Preserve D-007 (approval does not create a second live authority object).
- Add scenarios: one where a verified owner surface produces a typed
approver-of-record, and one where an approval without a verified surface fails
closed.

4. Author `specs/audit-artifact-store/spec.md`:
- Use `## ADDED Requirements` for a requirement that `AuditEvent` MAY carry an
optional `actor: Option<PrincipalId>` dimension for identity-aware audit trails.
- State the field MUST default absent for legacy and system rows, and MUST
preserve the existing hash-chain behavior for rows that omit it (mirror the
`aggregate_id`/`aggregate_seq` backward-compatible pattern).
- Add scenarios: one where an owner-driven audit row records the typed actor,
and one where a system row omits the actor and the hash chain still verifies.
===============================================================================

Task: 3

Implement Phase 3: author `tasks.md` and validate the whole change.

Author `tasks.md` as numbered `## N.` phases with `- [ ]` checkboxes:
- Phase 1 (schema + identity layer): add `PrincipalId`, add `OwnerPrincipal`,
and contract-first serialization tests proving byte equality with
`Ulid::to_string()`.
- Phase 2 (grant and selection retyping): retype `TaskGrant.user`,
`RootAuthority.user`, and `SelectionToken.actor`, and add a MAC regression test
proving pre-existing sealed grants verify without reseal.
- Phase 3 (approver and audit): retype `ApprovalRecord.approved_by` sourced from
a verified `OwnerSurfaceRef`, and add the optional `AuditEvent.actor` field with
a backward-compatible default.
- Add an explicit authority-sensitive verification phase, labeled as such,
listing checks tied to D-006 (aggregate and records carry no authority field),
D-007 (no second live authority object), AD-146 (single-owner preserved), and
AD-148 (thread binding unchanged and still MAC-committed only when present).
- Add a final phase for records and landing: decision-log update, `openspec
validate --changes 2026-08-20-design-typed-owner-identity --strict`, and
`./scripts/check.sh`.

Then validate the change:
- Run `openspec validate --changes 2026-08-20-design-typed-owner-identity
--strict`.
- If validation reports an `ADDED ... already exists` error for any requirement,
change that requirement's header to `## MODIFIED Requirements` and re-run,
following the OpenSpec ceremony rule.
- Confirm every requirement in every delta file includes at least one `####
Scenario:` block, satisfying the acceptance criterion "All five requirements
include Scenario blocks."

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!