Skip to content

dependency-operations.md

Latest commit

 

History

History
373 lines (289 loc) · 15 KB

dependency-operations.md

File metadata and controls

373 lines (289 loc) · 15 KB
Raw

Dependency Operations Runbook

Baseline record — not a specification. This document describes as-built or operational state; the normative target is the specification set indexed in docs/spec-policy.md, and where this document conflicts with a specification home, the specification wins.

This runbook defines how production dependency script versions are proposed, reviewed, packaged, retained, registered, pinned, deprecated, and rolled back for 6529Stream.

The contracts make dependency versions immutable. Operationally, that means a dependency change is never an edit to history. It is a new version, with source evidence, checksums, release-manifest coverage, and an explicit collection pin.

6529Stream is still pre-audit and pre-public-beta. This runbook is the minimum release-operations baseline for dependency ceremonies; live deployment manifests, production broadcasts, detached signatures, and external audit packages are still separate launch-gate work.

Scope

This runbook applies when an operator or maintainer:

  • registers a new DependencyRegistry dependency version
  • updates a dependency chunk with addDependencyScriptIndex
  • packages dependency source files under release-artifacts/dependencies/
  • pins an unfrozen collection to a dependency version through StreamCore
  • deprecates a dependency version
  • corrects or rolls back an unfrozen collection after a bad dependency release
  • retains dependency source evidence for auditors, marketplaces, indexers, and collectors

It does not authorize mutation of frozen collection output. Frozen collections must remain tied to their pinned dependency key, version, content hash, registry address, freeze manifest, and event history. If a dependency release, repin, deprecation, source-retention artifact, or metadata output is wrong, follow docs/incident-response.md before changing public readiness status.

Source Of Truth

Surface Source of truth Release evidence
Dependency bytes DependencyRegistry immutable version record DependencyVersionCreated event and getDependencyVersionRecord views
Collection pin StreamCore collection dependency pin DependencyVersionPinned event and collectionDependencyVersionState(collectionId)
Frozen collection proof StreamCore freeze manifest CollectionFrozen event and collectionFreezeManifestHash(collectionId)
Packaged source release-artifacts/dependencies/ descriptor plus source files
Artifact manifest release-artifacts/latest/dependency-artifact-manifest.json generated by scripts/generate_dependency_artifact_manifest.py
Provenance attestation release-artifacts/latest/dependency-provenance-attestation.json generated by scripts/generate_dependency_provenance_attestation.py
Release manifest release-artifacts/latest/release-manifest.json generated by scripts/generate_release_manifest.py
Signable checksums release-artifacts/latest/SHA256SUMS and release-artifacts/latest/release-checksums.json generated by scripts/generate_release_checksums.py
Deployment evidence deployments/examples/, deployments/address-books/, and future live manifests generated deployment artifacts and address books

Required Roles

The production ceremony must identify the acting addresses before any transaction is broadcast:

  • dependency registry function admin for addDependency, addDependencyWithProvenance, addDependencyScriptIndex, and deprecateDependencyVersion
  • collection metadata function admin for StreamCore.updateCollectionInfo
  • release operator who packages source evidence and regenerates release artifacts
  • deployment operator or Safe signer who broadcasts the accepted transactions
  • reviewer who compares packaged source, on-chain bytes, and release artifact output

If one address holds multiple roles, the release notes or deployment manifest must say so explicitly.

Standard Dependency Version Ceremony

1. Proposal

Open or link an issue before registering a production dependency version. The issue must include:

  • target dependency key as a bytes32 value and human label
  • intended deployment version and chain
  • reason for the new version
  • expected source files and licenses
  • compatibility statement for existing collections
  • whether any unfrozen collection will be repinned
  • whether any existing version will be deprecated
  • rollback plan if the version is later rejected

Do not reuse bytes32(0). That key is the no-dependency sentinel.

2. Review

Before packaging or broadcast, reviewers must compare:

  • source files against the intended generative dependency behavior
  • descriptor provenance against the issue, release notes, and deployment manifest
  • byte length against DependencyRegistry.MAX_DEPENDENCY_SCRIPT_CHUNK_BYTES
  • chunk count against DependencyRegistry.MAX_DEPENDENCY_SCRIPT_CHUNKS
  • UTF-8 validity for every chunk and provenance string
  • absence of private keys, RPC URLs with secrets, unreleased drop payloads, or operator-only data
  • license and provenance suitability for open-source publication

Any generated or minified dependency must retain the human-auditable source or build recipe that produced it. The packaged artifact can include both the source and built output when that helps auditability.

3. Package Source Evidence

Package dependency source before broadcast whenever possible.

Use a deployment-scoped directory:

release-artifacts/dependencies/<deployment-version>/<dependency-slug>/

or, for single-file packages, the existing layout:

release-artifacts/dependencies/<deployment-version>/<dependency-slug>.js
release-artifacts/dependencies/<deployment-version>/<dependency-slug>.dependency.json

Each descriptor must use schema 6529stream.dependency-artifact.v1 and record:

  • protocol version
  • deployment version
  • dependency registry key
  • dependency version, once known
  • registry contract label
  • provenance string
  • source registration path
  • repo-relative source files under release-artifacts/dependencies/

For a pre-broadcast proposal where the final on-chain version number is not yet known, use a review descriptor branch or draft PR. The mergeable PR must contain the final version number or clearly state that a later live-deployment artifact PR will fill it before public release.

Run:

python scripts/generate_dependency_artifact_manifest.py
python scripts/generate_dependency_artifact_manifest.py --check
python scripts/generate_dependency_provenance_attestation.py
python scripts/generate_dependency_provenance_attestation.py --check

The provenance attestation consumes the generated dependency artifact manifest and re-validates every descriptor and source-file hash against the files in the checkout. It gives release reviewers a single no-secret JSON document covering dependency identity, descriptor hash, packaged source hash, provenance string, registration notes, validation commands, and the explicit local-baseline limitations. It does not prove that a dependency was registered on a live chain, that a collection was pinned in production, or that public beta is ready.

4. Register The Dependency Version

Register a new dependency version through one of the accepted registry paths:

  • addDependency(key, chunks)
  • addDependencyWithProvenance(key, chunks, provenance)
  • addDependencyScriptIndex(key, index, chunk)

Prefer addDependencyWithProvenance for production because the provenance string gives indexers and auditors an on-chain pointer to the retained source evidence.

After broadcast, record:

  • transaction hash
  • block number
  • caller address
  • dependency key
  • created version
  • content hash from getDependencyScriptContentHashAtVersion
  • provenance from getDependencyVersionProvenance
  • emitted DependencyVersionCreated event

The created on-chain content hash must match the packaged source bytes after the same chunking used in the transaction.

5. Pin Or Re-Pin Collections

StreamCore pins dependency state at collection creation and when updateCollectionInfo runs the full collection update path. The pin records:

  • dependency key
  • latest dependency version at the time of pinning
  • dependency content hash
  • dependency registry address

For an unfrozen collection migration:

  1. Confirm collectionFreezeStatus(collectionId) is false through the accepted public freeze view or release evidence.
  2. Confirm the new dependency version is registered and packaged.
  3. Confirm the collection metadata admin intends to pin the latest version for the same dependency key.
  4. Run updateCollectionInfo with the full collection update index and the intended dependency key.
  5. Capture DependencyVersionPinned(collectionId, key, version, contentHash, registry).
  6. Read collectionDependencyVersionState(collectionId) and compare it with the expected key, version, content hash, and registry address.
  7. Regenerate or retain metadata sample evidence for the affected collection.
  8. Update deployment or release notes with the migration reason and transaction hash.

Repinning is an external metadata change. It must be visible in release notes and any marketplace or indexer communication prepared for the drop.

6. Refresh Release Evidence

After dependency source, descriptors, release docs, deployment manifests, or address books change, run the relevant generators:

python scripts/generate_dependency_artifact_manifest.py
python scripts/generate_dependency_provenance_attestation.py
python scripts/generate_release_manifest.py
python scripts/generate_release_checksums.py

Then run their check modes:

python scripts/generate_dependency_artifact_manifest.py --check
python scripts/generate_dependency_provenance_attestation.py --check
python scripts/generate_release_manifest.py --check
python scripts/generate_release_checksums.py --check

If a live deployment manifest is updated, also run the deployment manifest and address-book generators before refreshing the release manifest and checksum bundle.

7. Publish And Communicate

Before public use, publish or retain:

  • merged PR containing source artifact descriptors and generated manifests
  • release notes or changelog entry
  • dependency version transaction hash
  • collection pin transaction hash, if any
  • generated dependency artifact manifest
  • generated dependency provenance attestation
  • generated release manifest
  • generated checksum bundle
  • detached checksum signature when maintainer signing policy is active
  • marketplace or indexer note if metadata output can change for an unfrozen collection

Frozen Collection Protection

Frozen collections are immutable for this release track.

Operators must not:

  • repin a frozen collection
  • swap the global dependency registry while any collection is frozen
  • deprecate a dependency version and claim that the frozen collection output changed
  • edit release artifacts or manifests to make an old frozen output look like a new output
  • use social convention to override a stored freeze manifest

Allowed operations for frozen collections:

  • retain and publish the original source evidence
  • read and verify the pinned dependency version and content hash
  • deprecate a version for future use while acknowledging existing frozen pins remain valid
  • deploy a new contract or create a new collection under the redeployment ADR if a security incident requires a new path

If a frozen collection depends on a version later found to be unsafe, the incident response runbook must document the risk, the immutable proof, and any new deployment or collection path. It must not imply that the frozen output was mutated.

Deprecation

Deprecation marks a dependency version as disfavored for future use. It does not delete source, alter bytes, alter pinned collections, or invalidate frozen proofs.

Before calling deprecateDependencyVersion(key, version):

  • identify affected collections and whether they are frozen
  • identify unfrozen collections that should repin to a newer version
  • retain source evidence for the deprecated version
  • document the reason, severity, and recommended operator action
  • confirm the deprecation admin and transaction plan

After broadcast:

  • record the DependencyVersionDeprecated event
  • confirm getDependencyVersionRecord reports deprecated = true
  • update release notes, deployment notes, and indexer communication
  • do not remove the source artifact descriptor or file from the release bundle

Rollback And Corrective Releases

Because dependency versions are immutable, rollback means one of these actions:

  • for an unfrozen collection, register a new corrective version and repin the collection to that latest version
  • for an unfrozen collection whose latest dependency bytes should match an old version, register a new version that intentionally restores those old bytes and provenance
  • for a frozen collection, publish incident documentation and, if needed, deploy a new collection or contract path; do not mutate the frozen pin

Rollback issue notes must include:

  • bad version and corrective version
  • affected collection IDs
  • whether each affected collection was frozen or unfrozen
  • deprecation transaction, if used
  • corrective registration transaction
  • repin transaction, if used
  • updated dependency artifact manifest
  • updated release manifest and checksum bundle
  • communication plan for marketplaces, indexers, and collectors

Source-Retention Checklist

A production dependency version is not release-complete until all of these are true:

  • descriptor exists under release-artifacts/dependencies/
  • all referenced source files exist under release-artifacts/dependencies/
  • descriptor paths are repo-relative and do not escape the dependency artifact directory
  • source files contain no secrets or live RPC credentials
  • provenance string points to retained source evidence, not only an opaque external URL
  • license or provenance notes are sufficient for open-source publication
  • dependency artifact manifest is regenerated and checked
  • dependency provenance attestation is regenerated and checked
  • release manifest is regenerated and checked
  • checksum bundle is regenerated and checked
  • live deployment manifest or release notes identify the dependency version transactions before public beta
  • frozen collection pins, if any, still resolve to the original content hash

Local Verification

For a docs-only runbook change, the minimum local gate is:

rg -n "dependency-operations|Dependency Operations|#136" docs release-artifacts ops CHANGELOG.md scripts
python scripts/test_dependency_artifact_manifest.py
python scripts/generate_dependency_artifact_manifest.py --check
python scripts/test_dependency_provenance_attestation.py
python scripts/generate_dependency_provenance_attestation.py --check
python scripts/test_release_manifest.py
python scripts/generate_release_manifest.py --check
python scripts/test_release_checksums.py
python scripts/generate_release_checksums.py --check
python scripts/check_changelog.py
git diff --check

For a production dependency change, also run the full project gate:

make check