Skip to content

docs: establish the Depends dependency-declaration semantic - #51

Merged
dskvr merged 2 commits into
masterfrom
nap-depends-semantic
Jun 17, 2026
Merged

docs: establish the Depends dependency-declaration semantic#51
dskvr merged 2 commits into
masterfrom
nap-depends-semantic

Conversation

@dskvr

@dskvr dskvr commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Summary

An audit of merged and proposed NAPs surfaced valid cross-NAP dependencies — a miner publishes through relay, identity/media byte fields resolve through resource, and relay.event embeds a resource-owned type. These edges are legitimate but were declared only implicitly, as bare spec ids in prose. This introduces a track-level semantic to declare them, by domain, with a kind and strength — and an owner/importer rule that resolves the one real wire entanglement.

Changes

  • AGENTS.md — new section "Dependencies — declare, don't imply":
    • Each NAP names dependencies in a Depends: preamble block, by domain (aligned with shell.supports() and the manifest ["requires", …] tag), never a bare spec id in prose.
    • Kind: wire (embeds a type owned by another domain) · capability (calls another domain's surface) · layering (shell-internal, invisible to the napplet).
    • Strength: required (gate on shell.supports) · optional (degrade gracefully).
    • Owner/importer rule: a wire dependency is directional — one owner defines the shared type, importers reference it and MUST NOT redefine it. Mutual amendment is a bug.
    • Doc-sync table extended for Depends: blocks, the Deps column, and wire-dependency edits.
  • NAP-WORD-TEMPLATE / NAP-N-TEMPLATE — add the Depends: block (supersedes the ad-hoc Requires: field in NAP-N).
  • README — add a Deps column to both registries (NAP-WORD and NAP-N), giving a registry-level dependency graph.

Downstream

🤖 Generated with Claude Code

@dskvr @claude
docs: establish the Depends dependency-declaration semantic
ff3b81e 
NAPs legitimately rest on other NAPs (a miner publishes through `relay`; an
identity surface points byte fields at `resource`). Until now those edges were
implicit in prose with bare spec ids. Introduce a track-level semantic to
declare them explicitly.

- AGENTS.md: new "Dependencies — declare, don't imply" section. Each NAP names
  its dependencies in a `Depends:` preamble block, by domain, tagged with a
  kind (wire | capability | layering) and strength (required | optional). Add
  the owner/importer rule that kills wire entanglement: a `wire` dependency is
  directional — one owner defines the shared type, importers reference it and
  MUST NOT redefine it. Extend the doc-sync table accordingly.
- NAP-WORD-TEMPLATE / NAP-N-TEMPLATE: add the `Depends:` block (replacing the
  ad-hoc `Requires:` field in NAP-N).
- README: add a Deps column to both registries, giving a registry-level
  dependency graph; declared by domain, never spec id.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-RELAY: declare resource dependency; pin owner/importer
128f11c 
Adopt the Depends semantic (#51). relay imports the
ResourceSidecarEntry type owned by the resource domain — it never redefines it.
Add the Depends block and sharpen the import wording so the wire dependency is
directional, not mutual.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-RESOURCE: own the type, not the carrier's wire
9dbb4d2 
Adopt the Depends semantic (#51) and enforce the owner/importer
rule. resource owns the ResourceSidecarEntry type and the hydration contract;
it no longer "amends" relay's wire. The carrier domain (e.g. relay) owns its own
resources? field, default-OFF policy, and allowlist. This de-entangles the one
mutual-amendment edge in the registry into a directional dependency.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-IDENTITY: declare dependencies via the Depends semantic
b9cec0a 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-MEDIA: declare dependencies via the Depends semantic
0fa8e5b 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-UPLOAD: declare dependencies via the Depends semantic
5a69555 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-VALUE: declare dependencies via the Depends semantic
384ee80 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-OUTBOX: declare dependencies via the Depends semantic
08fb85b 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-CVM: declare dependencies via the Depends semantic
a97135b 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-POW: declare dependencies via the Depends semantic
de9ee99 
Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-1: replace Requires with the Depends semantic
902b5c7 
Adopt the Depends block (#51): transport and any further domains
declared by domain with kind and strength, superseding the ad-hoc Requires field.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-2: replace Requires with the Depends semantic
fdd0afb 
Adopt the Depends block (#51): transport and any further domains
declared by domain with kind and strength, superseding the ad-hoc Requires field.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-3: replace Requires with the Depends semantic
ea541dd 
Adopt the Depends block (#51): transport and any further domains
declared by domain with kind and strength, superseding the ad-hoc Requires field.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-4: replace Requires with the Depends semantic
5262de5 
Adopt the Depends block (#51): transport and any further domains
declared by domain with kind and strength, superseding the ad-hoc Requires field.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-5: replace Requires with the Depends semantic
1efbce1 
Adopt the Depends block (#51): transport and any further domains
declared by domain with kind and strength, superseding the ad-hoc Requires field.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@dskvr @claude
docs: correct Deps for NAP-IDENTITY and NAP-CVM
2c6277a 
On rollout, identity's relay mention and cvm's relay mention proved to be
comparisons / boundary notes, not dependency edges. Drop them so the Deps
column matches the specs' Depends blocks.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@dskvr
dskvr merged commit 8aba65c into master Jun 17, 2026
dskvr added a commit that referenced this pull request Jun 17, 2026
@dskvr @claude
NAP-IDENTITY: read-only user identity queries (#12)
a802d35 
* spec: add NUB-IDENTITY -- read-only user identity queries

Defines the identity NUB with 9 query methods (getPublicKey, getRelays,
getProfile, getFollows, getList, getZaps, getMutes, getBlocked, getBadges).
All queries are strictly read-only. No signing, encryption, or decryption
is exposed through this interface.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: clarify picture/banner URLs flow through NUB-RESOURCE

Adds a note paragraph after the ProfileData interface clarifying that
napplets fetch picture and banner bytes via window.napplet.resource.bytes(url)
per NUB-RESOURCE. Napplets cannot use direct <img src=https://...> loads
under the NIP-5D iframe sandbox (sandbox='allow-scripts', no
allow-same-origin); the shell is the sole network-fetch broker.

No wire change, no type change — documentation-only addition. Pre-amendment
napplets that already use resource.bytes(url) for these fields continue to
work; the clarification only documents the existing contract more clearly.

The standard NUB-RESOURCE policy (private-IP block list at DNS-resolution
time, MIME byte-sniffing, optional SVG rasterization) applies — there is no
privileged 'identity bytes' path that bypasses Default Resource Policy.

* docs: rename proposal terminology to NAP

* Stop identity users from polling for signer readiness

The identity interface now defines a snapshot-plus-push flow so napplets can get the current shell-user pubkey once and react to later signer changes without polling. The spec keeps shell-user identity separate from the NIP-5D source-bound napplet session identity and uses an empty pubkey string for signed-out states.

Constraint: Existing request/result wire format remains the baseline for identity queries

Rejected: Require napplets to poll getPublicKey until non-empty | creates runtime churn and stale subscriptions

Confidence: high

Scope-risk: narrow

Directive: Keep identity.changed about shell-user identity only; do not use it to renegotiate napplet session identity

Tested: git diff --check

Not-tested: No runtime implementation exists in this repo

* Use unpadded numbered NAP template notation

This PR branch now uses NAP-N / NAP-{N} and unpadded examples instead of fixed-width NAP-NN or NAP-01 style wording. That keeps the open identity PR aligned with the unbounded numbered-NAP convention.

Constraint: Numbered NAPs are unbounded; leading zero and NN notation imply a 99-spec limit

Rejected: Update only numbered NAP PRs | this branch still carried stale documentation templates

Confidence: high

Scope-risk: narrow

Directive: Keep numbered NAP identifiers unpadded in docs, templates, files, titles, and PR bodies

Tested: git diff --cached --check; rg for padded NAP references

Not-tested: GitHub merge state until post-push audit

* docs(NAP-IDENTITY): align header to seam framing (Domain + web binding)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* chore: move NAP-IDENTITY spec into naps/ directory

Relocate NAP-IDENTITY.md -> naps/NAP-IDENTITY.md to match the naps/ layout (#37).
Repoint the README registry link where present.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* NAP-IDENTITY: declare dependencies via the Depends semantic

Adopt the Depends block (#51): the domains this NAP rests on,
declared by domain with kind and strength.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: drop .planning/ and stale SPEC.md from PR surface

.planning/ is local-only and must never be pushed (AGENTS.md); SPEC.md was
deleted from master. Both rode in via a shared ancestor and don't belong on
this spec PR. Additive removal — no history rewrite.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: sandwich <dskvr@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@dskvr