kumwe / contribution

v0.1.1 2026-09-07 19:20 UTC

Requires

• php: ^8.5

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• squizlabs/php_codesniffer: ^4.0

Apache-2.0

Published on Packagist.org on 2026-09-07 19:20 UTC

README

Neutral contribution owners, explicit surface policies and bounded deterministic data registries. Requires PHP 8.5 with no other runtime dependencies. Namespace: Kumwe\Contribution. Apache-2.0.

Install and use

Install the published release with an exact pre-1.0 pin:

composer require kumwe/contribution:0.1.1
php vendor/kumwe/contribution/examples/typed-consumer.php vendor/autoload.php

Exact pins are required before 1.0. Review release verification before upgrading. The complete runnable example ships in examples/typed-consumer.php.

use Kumwe\Contribution\ContributionOwner;
use Kumwe\Contribution\SurfaceIdentifierPolicy;
use Kumwe\Contribution\OwnedContributionRegistry;

$owner = ContributionOwner::extension('acme/catalog');
$policy = SurfaceIdentifierPolicy::dotted('catalog');
$owner->assertOwns('acme.catalog.summary', $policy);
$registry = new OwnedContributionRegistry($policy, maximumEntries: 100);

Implement ContributionDefinition's identifier()/toArray() for your declaration, then register it. The registry validates ownership and freezes a bounded data snapshot; no implementation object is retained. Exact-owner lookup returns a copy or null; owner removal cannot delete another owner's entries. Identifier order is bytewise deterministic. Nested document order and numeric values are preserved without canonical JSON, hashing or precision conversion.

Composition and guarantees

Every surface explicitly chooses dotted() or slash() policy. Surface names never activate special rules. Typed dotted markers, core exemptions, slash namespace aliases and index kinds are explicit options. Integration defines the Core contract and compatibility with explicit policies.

No provider, factory, container alias or configuration key is exported. Construct immutable values directly. Supply a mutable registry per composition; no concurrent-writer/process guarantee, transactions, I/O or external effects. Host trust, authorization, lifecycle, manifest reconciliation, active runtime generation, executable dispatch, persistence and recovery remain outside this package. Owner identity is never a security credential.

Identifier input is limited to 256 bytes; policy lists/capacity are bounded. Snapshots enforce depth/node/string/byte limits, reject objects/resources/non-finite numbers and detach PHP references. Returned arrays cannot mutate stored state. ContributionRejected extends InvalidArgumentException with a stable readonly reason; diagnostics do not echo submitted payloads.

Public API documents every public member, limit and error. See architecture, security, release protocol and release evidence.

Verify

composer install
composer check

The gate includes Composer validation/security audit, release parser, syntax, member docs, architecture, reflected API manifests, Composer autoload/example, PSR-12, PHPStan max, hostile/behavior tests and built-ZIP installation as a dependency in an isolated no-dev authoritative consumer. php tests/run.php runs behavior tests without Composer. composer manifests:record regenerates a deliberately changed API manifest.

Core consumes these types directly or through a compatible Extension SDK release. Verify the installed package identities and retain host integration tests. No legacy aliases, remaps or production fallback are supplied.