Your privacy choices

We use necessary cookies, and others only if you allow them. You can change your mind at any time.

CC

particle-academy/change-council

particle-academy/change-council

A consumer-agent voting ledger for major package changes: a zero-dependency change detector for CI and pre-push, and a Laravel ledger with two voting rounds, per-consumer silence policy, a hash-chained audit log and signed decision records.

Backend · renders no UIPHP
567 downloads this month567 downloads all-time
Backend · renders no UI
Nothing to preview — install it and call the typed API, or hand it to an agent.
$composer require particle-academy/change-council

API surface

Headless package — drive it from code or an agent. No component grid.

This package renders no UI surface. It exposes a typed PHP API; issues are tracked on GitHub.
readmeREADME.mdView on GitHub →

change-council

A consumer-agent voting ledger for major package changes. Before a package ships a change its consumers can feel (a third-party major, a raised platform floor, a removed export, a schema change, a deprecation), the agents that run the apps depending on it are asked, and every answer is kept.

Two halves, one repo:

  • The detector, council/check.mjs: zero-dependency Node that compares two git refs and reports what a consumer could feel. The same file runs in a local pre-push hook, in GitHub Actions on public repos, and behind php artisan council:detect.
  • The ledger, particle-academy/change-council: a Laravel package for a lab. Proposals, two voting rounds, per-consumer silence policy, owner decisions, an append-only hash-chained audit log, Ed25519-signed decision records, a JSON API, an Overwatch feed, and lab pages built from react-fancy.

Pre-1.0, and report-only. Phases 1 and 2 of the design. Nothing gates a release yet: the detector exits 0 whatever it finds, and decision records are written and verified but not required. The gate is Phase 3. Breaking changes land in minor releases; read the CHANGELOG.

For agents. This package is listed on the Fancy MCP catalog server at https://ui.particle.academy/mcp (streamable HTTP, no API key; MCP id fancy-ui), with install commands and docs, alongside the rest of the kit. How an agent installs and uses this package is in AGENTS.md.

The rules it encodes

  • Silence is not consent. A required voter's silence escalates to the owner, unless the owner has set that consumer to proceed_and_notify (it proceeds, and the consumer's late vote is still recorded).
  • Agents petition; the owner decides. A whitelisted agent's finding or request, or an issue from a whitelisted author, opens round 1. Anything non-whitelisted waits for the owner with the initiating agent's pros and cons. No petition leaves first. Owner decisions are made in the authenticated lab UI only; no artisan command can record one.
  • Replies are data. Strict JSON, bound to the round by nonce and digest, identified by the Genie-stamped sender, flagged for injection, rendered as text, never applied.
  • The ledger never calls Genie. The lab's own agent (the clerk) sends the petitions it queues and pipes the replies back.
  • The detector is a floor, not a ceiling. A behaviour change behind an unchanged signature is invisible to it. Declare those.

Quick look

node council/check.mjs                     # previous v* tag -> HEAD, human summary
node council/check.mjs --json --out r.json # structured report
change-council detector 0.1.0 (REPORT-ONLY: Phase 1 never fails a release)
compare: v1.0.0 -> HEAD (3f2a9c1e0b7d)   kind: library

MAJOR (2)
  [platform-floor] composer:php  ^8.3 -> ^8.4  (composer.json)
  [third-party-major] composer:acme/http  ^2.1 -> ^3.0  (composer.json)
...
use ChangeCouncil\Facades\Council;

Council::authorizeOwners(); // [email protected]; an empty list allows nobody
Council::routes();

Owner-only on purpose: on a host with open registration, "any signed-in user" is anyone. See the quick start.

Optional: name the owner the way your app does. Owner actions are recorded as owner:<email> (the user's key when it has no email). Council::resolveActorUsing() maps the authenticated user to a different id instead, recorded as owner:<id> in the audit log and the decision:

Council::resolveActorUsing(fn ($user): string => 'github:'.$user->github_login);

The answer must be a non-empty string of at most 191 characters with no control characters or newlines. A bad answer refuses the owner action with invalid_actor (HTTP 500) and records nothing; it never falls back to the email, because the audit log is append-only.

Step-up before owner actions (optional)

A host can require a fresh proof (a passkey ceremony, a TOTP, a second device) before any OWNER action runs: approve or reject an initiation, override, revoke, the silence policies, a member's weight or project, removing a member, inviting an agent, and the blocking threshold. The council does not know what the proof is; it calls the host's ChangeCouncil\StepUp\StepUp:

Council::requireStepUpUsing(new MyPasskeyStepUp);   // default: NoStepUp
interface StepUp {
    public function required(mixed $principal, OwnerAction $action): bool;
    public function challenge(mixed $principal, OwnerAction $action): array;   // for the client
    public function verify(mixed $principal, OwnerAction $action, array $proof): array; // evidence, or throw StepUpRefused
}

OwnerAction is {action, ref, address, params} (params = the validated body) and digest() is sha256: of its canonical JSON, so a proof bound to it cannot approve another Change, another member, or the same action with other params.

The proof travels in the body's reserved step_up key. After authorization and body validation:

Request Answer Audit log
no step_up 428 {"error": {"code": "step_up_required", "step_up": <challenge>, "action": {action, ref, address, params, digest}}} nothing
a refused proof 403 {"error": {"code": "step_up_failed", "reason": "<code>"}} owner.step_up_refused {action, ref, address, digest, reason, evidence}
a verified proof the action's usual answer owner.step_up {action, ref, address, digest, evidence}, then the action's own events, in one transaction

A step-up whose action the ledger then refuses rolls back with it. The default, NoStepUp, requires nothing, and a step_up key is then ignored.

The pages answer a 428 through a handler the host sets once in its browser entry; the request is re-sent once with the proof:

import { setStepUpHandler } from './Pages/Council/parts/api';
setStepUpHandler(async (challenge, action) => ({ /* the proof */ }));

Optional, and off by default: Council::notifyGenie() (or COUNCIL_NOTIFY_GENIE=true) sends owner events to Genie's app inbox after commit. These are a proposal awaiting the owner, initiation approved or rejected, override, revoke, a closed tally and escalation. The notice carries refs and counts only, and a failure is audited, never thrown. See the quick start.

Your first-party packages (the census)

A census keeps only the packages your estate publishes and drops the rest as not_first_party. Which names count is host configuration, council.census.first_party, per ecosystem (composer, npm, pypi). The defaults are Fancy's (particle-academy/*, @particle-academy/*, fancy-*), so a council for any other estate must set its own:

// config/council.php
'census' => [
    'publisher' => 'Prism', // named in the census request
    'first_party' => [
        'composer' => ['patterns' => ['prism-php/*']],
        'npm' => ['patterns' => ['@prism-ai/*']],
        'pypi' => ['patterns' => ['prism-ai-*'], 'names' => ['prism-conformance']],
    ],
],
  • A pattern is an exact name, or a literal prefix with ONE trailing *. It is never a regex: matching is a prefix or exact comparison, so no configured pattern is ever run against a member's reply. names lists exact names. PyPI entries are written in PEP 503 normalised form (lower case, - only), because reply names are normalised before the check.
  • When first_party is set it is the whole rule. An ecosystem it leaves out has no first-party packages, and the census request does not ask for it.
  • The rule is validated once, when the service provider boots. A bad entry (a regex, a bare *, a * anywhere but the end, a character outside the ecosystem's name alphabet, an unknown key or ecosystem, more than 50 patterns or 200 names, or anything over 214 characters) throws an InvalidArgumentException naming the entry, such as council.census.first_party.pypi.patterns.0. It is never skipped silently.
  • The census request lists the configured patterns and names, and names the publisher, so a member is asked for your packages rather than Fancy's.

Docs

  • Laravel quick start: install, authorization, pages, commands, API
  • The detector: classes, waivers, surface snapshots, what it cannot see
  • CI usage: GitHub Actions and pre-push, pinned SHA plus content hash, never in an id-token job
  • Petitions and replies: initiation, the clerk loop, wire formats, tally and silence
  • The census: members list what their lockfiles install; COUNCIL-CENSUS v1
  • Decision records: decision.v1, signing, verification, the audit chain
  • The Overwatch feed: feed.v1, the signed webhook, open questions for civi
  • Lab UI: the pages, and how they were checked in a real browser

Requirements

  • Detector: Node 22+ and git. PHP on PATH for the PHP API comparison (it says so in the report when it is missing).
  • Ledger: PHP 8.4 with sodium, Laravel 13. inertia-laravel and react-fancy for the pages (both labs have them).

Testing

node --test "council/test/*.test.mjs"   # detector: a must-fire and a must-not-fire repo per class
vendor/bin/pest                          # ledger: hermetic, no network, a fake petition transport
php tests/lint.php

License

MIT

What next
Install it, then call the API from your code or over MCP.