feat(#577): sharing via GrantStore + admin-gated promotion + cron write-guard (P3)

[Weegy]

Summary

Phase 3 of #577 (skills as scope-owned, shareable artifacts). Adds sharing via GrantStore, admin-gated promotion, and the cron write-guard — service-layer only. The admin-gated HTTP route itself is deliberately deferred (see "Not in this PR").

Base: feat/577-skill-artifacts-p2 (P2, #768), NOT main. Stacked — merge order is #767 (P1) -> #768 (P2) -> this PR.

What's in this PR

Cron write-guard (#577 Kernkonzept #6 — "automations may not modify skills, as an enforced guard, not a convention")

• src/services/skillLifecycle.ts: assertHumanActor(actorScope) / SkillAutomationWriteBlocked. Checks ScopeId.kind === 'system' — scopeId.ts's own header already documents that kind as "no human is present in any of them" (routine/schedule/conductor/conductor-builder), so this needed no new taxonomy, just reusing Scope model with audience-floor permission intersection for shared rooms #575's existing one.
• src/services/skillLifecycleStore.ts: assignPersonalOwner and transition now take an actorScope and call the guard before any query runs — a blocked write never reaches the database. Verified at both the pure-function level and the pg-gated level (the pg test asserts the row is unchanged after a rejected cron write, not just that the call threw).

Admin-gated promotion (#577 Kernkonzept #5 — "no direct creation in org/team scope, only admin-gated promotion")

• New promoteSkillOwnerScope(skillId, targetScope, opts) on PgSkillOwnershipLifecycleStore — the only way a skill ever reaches group/org ownership (mirroring assignPersonalOwner, which only ever assigns personal). Enforces:
  • the cron guard (same as above);
  • the skill must already be published — an unreviewed draft has no business reaching a wider audience;
  • re-signs the manifest at the new ownerScope, same status — since ownerScope is a signed field (Skills as scope-owned, shareable artifacts (grants, org promotion, git skill packs) #577 P1), promotion is a signature-changing event, not just a column update.
• "Admin-gated" itself (an authenticated-session check) is intentionally left to the route layer this method doesn't have — this store method has no notion of roles, only of the cron guard and the published-only invariant.

Sharing = a grant, not a parallel ACL (#577 Kernkonzept #5)

• New src/services/skillSharing.ts. Encodes "skill X is shared with principal Y" as a Capability string (skill:read:<skillId>) and resolveSharedSkillIds(principal, roles, grants) turns a resolved capability set (via Scope model with audience-floor permission intersection for shared rooms #575's resolveCapabilities) back into the ReadonlySet<string> that P2's resolveSkillByName (SkillResolutionContext.sharedSkillIds) needs for its shared bucket. Denials subtract from grants — same rule audienceFloor.ts applies. Consumes GrantStore/resolveCapabilities only — zero edits to grants.ts.
• Deliberately does NOT collapse an unresolved role lookup (a partial/thrown role source) to an empty set at this layer — SharedSkillIdsResult keeps that fact visible, distinct from "nothing is actually shared". toSharedSkillIdsSet is the explicit fail-closed adapter for callers who just want the resolver's plain-set input. The module header explains why fail-closed is safe HERE specifically (it can only hide a skill from the resolver, never leak one), unlike on the audience-floor path where the same collapse would be dangerous.

Test coverage

• test/skillSharing.test.ts (15 pure tests): capability round-trip, direct-grant resolution, role-grant union, denial subtraction, unresolved-vs-empty distinction, the fail-closed adapter.
• test/skillLifecycle.test.ts (+2 tests): assertHumanActor passes for every non-system ScopeId kind, throws SkillAutomationWriteBlocked (with the right actorScope attached) for all 4 system origins.
• test/skillOwnershipLifecycleStore.pg.test.ts (+6 pg-gated tests): cron guard on all three mutating methods (assignPersonalOwner, transition, promoteSkillOwnerScope) verifying the row is untouched after rejection; full promotion flow to an org home and to a team (group) home; promotion refused on a draft skill.

Mutation evidence

#	Mutation	Result
C	assertHumanActor never throws (guard disabled)	4 tests fail: the pure all-origins test, plus all 3 pg-gated cron-guard tests (assignPersonalOwner, transition, promoteSkillOwnerScope)
D	Dropped the lifecycleStatus !== 'published' gate on promoteSkillOwnerScope	1 pg-gated test fails: promoteSkillOwnerScope refuses a draft skill

Both mutations reverted after confirming failure; git diff --stat on the mutated files matched only the legitimate P3 diff afterward (no residue).

Full-suite regression

6962 tests / 6950 pass / 0 fail / 12 pre-existing skips, both npm test (non-pg) and the pg-gated suites run against an ephemeral local Postgres.

Blast radius

• 3 files from P1 modified further (skillLifecycle.ts, skillLifecycleStore.ts, and their tests) — all additive/threading changes (new exports, a new required parameter on two existing methods, a new method). No behavior change to what P1 already shipped for the transitions it already covered.
• 2 new files (skillSharing.ts + its test).
• @omadia/channel-sdk consumed only (resolveCapabilities, GrantStore, Principal, RoleSourceRegistry) — zero edits to grants.ts, consistent with the binding surface separation.
• No route, no src/index.ts change — see below.

Not in this PR (explicitly deferred, with reasoning)

• The admin-gated HTTP route. Wiring a session-authenticated Express route means touching src/index.ts (the shared app-bootstrap file, ~3800 lines, high concurrent-edit traffic across this repo's parallel issue-harness sessions) and correctly replicating the existing req.session.omadia_user_id auth chain used elsewhere (e.g. routes/bulkPromotion.ts). A promotion endpoint with a subtly wrong auth check is a real security regression, not something to rush. promoteSkillOwnerScope itself is complete and fully tested; mounting it behind a route + session auth is a natural fit for P4 (admin UI), which needs a concrete endpoint contract anyway.
• Team/org membership sourcing for P2's resolver (still pre-resolved-input by design).
• Git skill-pack import (pinned/tracked refs, SSRF-guarded fetcher) — out of scope for the whole P1-P4 cut per the original issue triage.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}