YSDK-1 — YOS APPLICATION INTEGRATION SPECIFICATION

Version 1.0.0-draft.2 · Date 2026-08-30 · Authority ysdk.org Supersedes draft.1 in full

BCP 14 language: MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY carry their normative meanings when capitalised.

Normative artifacts shipped with this document. The prose is the contract; these are the contract in executable form. Where they disagree, this document is normative and the file is the defect.

  • ysdk.app.schema.json — JSON Schema 2020-12 for the manifest
  • ysdk-core.ts — the client library: UCAN wire types, guards, upgrade gate, seed broker
  • ysdk-design-system.css — the hexagon room system, tokens, responsive morph, a11y floors
  • ysdk-conformance.spec.ts — the executable conformance suite that produces the evidence block
  • ysdk-sw.js — reference service worker with the normative update strategy
  • yfile.ysdk.app.json — a complete worked example at L3
  • YSDK-1-PLATFORM-MATRIX.xlsx — Baseline evidence, capability grammar, annexes

PART ONE — PLAIN ENGLISH

1.1 What YOS is

An operating system whose applications are not hosted by one company and whose app store is not owned by whoever runs it. It lives at bind.com as a canvas of hexagonal rooms. Each hexagon is a complete application with its own domain, brand, knowledge, agent and API. Entering one takes you inside, where that app's own agent is present.

Four properties make it an operating system rather than a bookmark folder.

Identity nobody issues on your behalf. Identities come from ydid.org, a post-quantum self-custody engine. They are verifiable by anyone, controlled by their holder, revocable by their holder. YOS itself holds one — the store is a customer of the identity system, not its issuer. This inverts the normal arrangement and it is the point.

Any app can use any other app. Not by partnership. By contract: an app publishes what it can do and another app, or an agent acting for a person, discovers and calls it. A file manager becomes the file layer inside a video editor without the two teams ever meeting.

Permission is something you hold, not something you are. When app A uses app B, A never receives a key or a password. A holds a capability: signed, scoped, expiring, revocable, and passable-on in narrowed form. This is the difference between lending someone your house keys and giving them a note that says "may enter the kitchen, Tuesday only, and may not copy this note."

Every person chooses their relationship to the software. Use it in a browser. Install it and own the copy. Or, if the machine is capable and the operator opts in, run it for other people as a seed.

1.2 What "harvest" means

An app here is not only a thing a person opens; it is a set of functions other software can consume. Harvesting is one app taking another's functionality and using it as its own. It works because every app describes itself in a machine-readable way and speaks one protocol, so a consumer needs no bespoke code per integration — it reads a manifest and speaks MCP.

1.3 What this is not

Not a platform that takes a cut. Not a walled garden. A conforming app runs entirely outside YOS, at its own domain, for people who have never heard of bind.com. Conformance makes an app joinable, not captive. An app that cannot run standalone has not been integrated — it has been absorbed, and that is a failure of this specification, not a success. §9 makes that a test rather than a promise.

1.4 The one-day version

Get a DID from ydid.org, publish a signed ysdk.app.json at your domain, and you are Level 0: identified, listed, discoverable. Everything after is incremental. You do not have to boil the ocean to join it.

PART TWO — THE GOVERNING DECISION

YSDK invents exactly one artifact. Everything else is a profile over existing standards.

An ecosystem that invents its own identity format, capability format and RPC protocol must persuade every application to learn three proprietary things and must maintain three proprietary things forever, including their security review. A profile inherits the tooling, the test suites, the review — and every application that already speaks them.

The four, all fetched and inspected 2026-08-30:

Identity — W3C DID v1.1, Candidate Recommendation 2026-03-05, superseding DID Core v1.0 (REC 2022-07-19). W3C publishes a did-test-suite, so conformance is run. The multicodec registry carries codepoints for exactly the parameter sets in estate use — mlkem-1024-pub 0x120d, mldsa-87-pub 0x1212, private-key range from 0x1313, and the full SLH-DSA set 0x1220–0x122b. All marked draft.

Authority — UCAN v1.0.0. Its abstract: "a trustless, secure, local-first, user-originated, distributed authorization scheme... public-key verifiable, delegable, expressive, openly extensible capabilities... public verifiability with late-bound certificate chains and principals represented by decentralized identifiers." Sub-specifications exist for Delegation, Invocation, Promise and Revocation. Authors sit at Protocol Labs, Bluesky, Common Tools, number zero and Decentralised Experience.

That paragraph is this ecosystem's requirement, already specified, with revocation already solved. YSDK does not define a capability format. It uses UCAN, at the wire level, exactly.

Functional exposure — Model Context Protocol, revision 2026-07-28. "An open-source standard for connecting AI applications to external systems", "like a USB-C port for AI applications." Host → one Client per Server; STDIO for local, Streamable HTTP for remote. Reference SDK @modelcontextprotocol/sdk 1.30.0 (2026-07-27, MIT), whose dependency set — zod, ajv, hono, jose, pkce-challenge, eventsource — tells you the transport and auth shape without reading a line of it. YSDK does not define an RPC protocol. It uses MCP.

Installability — W3C Web Application Manifest, Working Draft 2026-08-13.

What YSDK adds: ysdk.app.json — one file binding an app's DID to its web manifest, MCP endpoint, UCAN grammar, deployment modes, seed requirements, brand, agent and upgrade policy.

PART THREE — WIRE FORMATS (normative)

3.1 The UCAN envelope

Every UCAN artifact uses this container:

[ signature_bytes,
  { h: VarsigHeader,
    "ucan/<subspec-tag>@<version>": TokenPayload } ]

.0 is a signature by the payload's iss over .1. .1.h is the Varsig v1 header, which encodes the signature algorithm inside the envelope.

Varsig is not incidental — it is the crypto-agility mechanism. ML-DSA-87 is expressible today, and when the classical half of a hybrid sunsets, the header changes while every previously issued artifact stays verifiable because it says what it is. An implementation that replaces Varsig with a bare algorithm string has broken migration for the whole ecosystem. ysdk-core.ts §7 builds it from the manifest's multicodec value and throws ALGORITHM_UNIDENTIFIED if absent.

3.2 Delegation — tag ucan/dlg@1.0.0

Fields, per the UCAN Delegation specification: iss (DID, required), aud (DID, required), sub (DID or null, required), cmd (String, required), pol (Policy, required), nonce (Bytes, required), meta (map, optional), nbf (integer seconds, optional), exp (integer or null, required).

YSDK narrows UCAN in exactly one place. UCAN permits exp: null. YSDK forbids it. A non-expiring capability in this ecosystem is a defect: revocation propagation is best-effort across a peer-to-peer network, expiry is not. Ceiling is one year — YSDK_MAX_DELEGATION_SECONDS.

Commands are hierarchical path segments. /file covers /file/read; /file/read does not cover /file or /file/write. Segment boundaries matter: /file does not cover /filesystem/read. commandCovers() implements this and the conformance suite drills the escalation cases, because a prefix-match bug here is a privilege escalation.

Policy is UCAN's syntactically-driven constraint language, e.g.

[ ["==", ".status", "draft"],
  ["all", ".reviewer", ["like", ".email", "*@example.com"]],
  ["any", ".tags", ["or", ["==", ".", "news"], ["==", ".", "press"]]] ]

3.3 Invocation — tag ucan/inv@1.0.0

iss, sub, aud (optional; MUST differ from sub and MUST be omitted when the executor is the subject), cmd, args, prf (delegation CIDs proving the chain), meta, nonce, exp, iat, cause.

3.4 Verification order (normative)

Verifiers MUST check in this order, and the order is a requirement, not a style:

  1. Invocation exp against now.
  2. Each delegation's exp and nbf.
  3. Chain linkage — each aud equals the next issuer.
  4. commandCovers() at every hop.
  5. Signature at every hop.
  6. Revocation last.

Revocation may hit the network. An expired or malformed token MUST NOT cost a round-trip, or the revocation endpoint becomes a denial-of-service amplifier reachable by anyone with a junk token.

PART FOUR — CONFORMANCE LEVELS

A ladder, not a threshold. Levels are verified by a run, never declared.

  • L0 IDENTIFIED — resolvable DID; signed manifest at /.well-known/ysdk.app.json. ~1 day.
  • L1 INSTALLABLE — Web App Manifest, service worker with the §6 update strategy, honest offline, 1320/760/390 with the narrow leg under touch and pointer: coarse, keyboard-only operable, focus visible through clip-path.
  • L2 INTEGRATABLE — MCP surface; every tool documented, versioned, rate-limited, sideEffects declared.
  • L3 DELEGABLE — UCAN issue and verify. Revocation MUST be OBSERVED terminating access, live. A passing unit test is not sufficient evidence for this level.
  • L4 SEEDABLE — seed mode with the §7 obligations.
  • L5 AGENTIC — own agent over own knowledge partition; app fully functional with the agent dark.
  • L6 ACCOUNTABLE — tamper-evident contribution records. Measurement only.

ysdk-conformance.spec.ts is tagged @L0…@L6; its run populates conformance.evidence.

PART FIVE — THE UI/UX CONTRACT

This part is normative. Every claim below is justified against web-features 3.36.0 Baseline data, published 2026-08-27.

5.1 Container queries, not media queries — REQUIRED

A room renders full-bleed at bind.com, inside a panel in a consuming app, and standalone at its own domain — all at the same viewport width. Media queries cannot express that; container queries can. Baseline high since 2025-08-14, so no fallback is required.

Implementations MUST size rooms by container query. Media queries MAY be used only for prefers-reduced-motion, pointer, and forced-colors.

5.2 oklch, not hsl — REQUIRED for palettes

Baseline high since 2025-11-09 for oklab/oklch and color-mix. oklch is perceptually uniform, so rotating hue by a fixed angle produces a perceptually even step. In HSL the same rotation produces wildly uneven lightness and a golden-ratio palette visibly falls apart. The design system derives a room's entire palette from one number — --ysdk-brand-h — using the golden angle 360/φ² = 137.5077640500378deg.

A room's palette MUST be manifest data, never a stylesheet literal. Changing a room's colour is a manifest edit and a deploy of nothing.

5.3 Hexagon geometry

Flat-top regular hexagon, circumradius r: width 2r vertex-to-vertex, height √3·r flat-to-flat. Tessellates in offset columns: x-step 1.5r, y-step √3·r, alternate columns offset by √3·r/2. Pointy-top swaps the roles and offsets rows. Both are expressed as six derived custom properties, so orientation is a token.

The clip is polygon(25% 0%, 75% 0%, 100% 50%, 75% 100%, 25% 100%, 0% 50%) — the 25%/75% x-positions are exactly r/2 from each vertex, which is exact for a regular hexagon rather than an approximation.

5.4 The responsive morph — REQUIRED

A tessellation of twenty hexagons is beautiful at 1320 and unusable at 390. The identity is preserved; the tessellation is what changes. Three container-driven states:

  • ≥900px — full interlocking tessellation.
  • <900px — reduced radius, interlock relaxed.
  • <620px — tessellation abandoned. Rooms become a single flow column with a gentler clip. This is a first-class layout, not a degraded one — it is what most visitors will see.
  • <380px — the clip is dropped entirely and brand identity is carried by the rim, because below this width an acute hexagon corner eats the text.

An implementation that ships hexagons without a declared narrow topology fails L1.

5.5 Focus must survive clip-path — REQUIRED

clip-path clips an outline away. A hexagon relying on a normal focus outline gives keyboard users no visible focus at all. The system draws the ring as an inset ::after rim inside the clip. @L1 focus is VISIBLE despite clip-path tests exactly this.

5.6 Floors, not fixed sizes — REQUIRED

Tap targets use min-block-size. A fixed 44px pins a control and stops it growing with its content; a floor lets it grow. This exact defect has already shipped in this estate. Floors: 44px under pointer: coarse, 36px under pointer: fine, 24px for checkboxes.

5.7 Reduced motion is a real path — REQUIRED

Room entry still communicates "you have entered a room" under prefers-reduced-motion: reduce, via an instant crossfade and a persistent rim flash. Silently removing the feedback is a different bug from respecting the preference.

5.8 Features that MUST NOT be load-bearing

Per Baseline, not Baseline as of 2026-08-30: anchor positioning, scroll-driven animations, WebGPU, WebNN, File System Access, launch/file/protocol handlers, background sync, badging, notifications, permissions policy. These MAY be used behind @supports or feature detection with a working fallback. They MUST NOT be required for any conformance level.

Two consequences worth stating. WebGPU and WebNN are not Baseline, so the agent layer MUST NOT assume GPU inference in the browser — §8 already requires it to be optional, and this is the platform reason. File System Access is not Baseline, so a file manager MUST NOT require showOpenFilePicker; OPFS is Baseline high since 2025-09-27 and is the durable local store.

5.9 Usable Baseline-high primitives

Import maps (2025-09-27) — the SDK ships as ES modules with no bundler required. Declarative Shadow DOM (2026-08-20). :has() (2026-06-19). Subgrid (2026-03-15). OPFS (2025-09-27). Web Locks and BroadcastChannel (2024-09-14) — cross-tab coordination for an installed PWA. Compression Streams (2025-11-09). WebRTC (2022-07-15) — seed transport, with WebTransport (Baseline low, 2026-03-24) as an enhancement.

WebCrypto is Baseline high but has no post-quantum algorithms. That is precisely why @noble/post-quantum is a dependency rather than a convenience.

PART SIX — LIVE UPGRADE AND ITS GATE

The promise is that apps stay current as their dependencies improve. The honest implementation has a gate, because automatically pulling unaudited code across a trust boundary is how one compromised app compromises every consumer at once.

  1. Publisher releases, signed by its DID key, with an integrity hash.
  2. Consumer declares an accepted range and policy in its manifest.
  3. The release is announced, never injected.
  4. Consumer verifies signature and hash against the publisher's DID.
  5. Acceptance is a recorded event. Auto MAY apply to an in-range non-structural patch. Anything touching an interface, capability grammar, cryptographic parameter or permission MUST be explicit.
  6. Pinned, with rollback to the prior pin possible without data loss.
  7. Every acceptance and rollback logged with who, what, when.

evaluateUpgrade() decides and never applies. "Live and seamless" describes the user's experience — it never means unreviewed.

PART SEVEN — THE THREE MODES

USE — hosted, nothing installed. MUST be supported; an app requiring installation to be evaluated will not be adopted.

INSTALL — owned by the device, offline after first load, with an honest statement of what does and does not work offline and legible failure states rather than blank panes. Browser storage is origin-bound, so an installed app at one origin cannot read another origin's store — a platform property, not a choice, and the reason §8.1 exists.

SEED — the device runs the app for other people. Every item is an obligation:

  • Explicit per-app operator opt-in, in plain language.
  • Capacity declared AND enforced — SeedBroker.admit() throws at the ceiling. A seed that over-admits fails everyone including its operator.
  • Peer access capability-gated (L3). A seed does not serve anonymous unbounded traffic.
  • Mid-operation disconnection handled: the portal knows what completed, what did not, what to retry.
  • Stoppable at any moment without destroying data or stranding peers silently.
  • An abuse policy exists before seeding ships. The operator is running strangers' traffic on their own hardware and their own network connection.

PART EIGHT — NON-NEGOTIABLES

8.1 Private keys never cross an origin. Capabilities cross; keys do not. Not in a URL, message payload, unencrypted backup, log, error report or telemetry event. assertNoKeyMaterial() is called on every outbound payload and ships with a test that feeds it a real key and asserts the throw.

8.2 Revocation is permanent. Append-only, replicated, exempt from every GC horizon. Verification MUST NOT require trusting the issuer — an issuer who is compromised, offline or hostile simply does not confirm. RevocationStore.purge() exists solely to be drilled and always throws REVOCATION_PERMANENT.

8.3 Deletion leaves a tombstone. No hard deletes across a sync boundary; the peer restores it on next replication. Purging payload is correct; the payload-free marker remains.

8.4 Contribution is measured, not monetised. L6 emits tamper-evident records. This specification does not define, authorise or describe the issuance, allocation, sale or distribution of anything of value. ledger.distributionDefined is false and validation rejects true.

8.5 The agent is an enhancement. Every surface functional with the agent dark, and turning it off MUST NOT reflow the layout — both are tested. Avatar capacity is measured, never assumed; WebGPU is not Baseline.

8.6 Accessibility floors are product requirements. §5.5–5.7.

8.7 No overclaiming. Not audited, certified, compliant or unbreakable until a third party says so in writing. attestations.independentSecurityAudit: null means not audited and MUST be present rather than omitted; unaudited apps MUST enumerate notReviewed.

8.8 Standalone or nothing. @standalone blocks every ecosystem host and requires the app to boot and perform its primary action anyway.

8.9 Argon2id at or above floor, in WASM. Where a passphrase derives a key: m ≥ 19456 KiB, t ≥ 2, p ≥ 1 (or an OWASP-listed equal-strength trade-off), parameters recorded in the file header so upgrade can be lazy, and a WASM implementation. Pure-JS Argon2 is roughly 5× slower than native and that penalty falls only on the defender — it is a security regression wearing the costume of a maintenance upgrade.

PART NINE — ADOPTION

  1. Inventory — what the app does as callable functions; seam classified CORE / HOST / ENTANGLED with every entangled edge named by file, line and symbol.
  2. Sever — own repository, private at creation, with .gitattributes and .gitignore present from the first commit. Hygiene files are infrastructure, not content; their absence has already CRLF'd a manifest and made a clone unverifiable in this estate.
  3. Identify — DID, signed manifest. L0. You are a member.
  4. Install — §5 in full. L1.
  5. Expose — MCP surface. L2.
  6. Delegate — UCAN, then prove revocation refuses, observed. L3.
  7. Elect — seed, agent, ledger, as the app's nature warrants.
  8. Enter the room — brand, palette, persona, hexagon. Then prove the app still runs standalone. The room is a guest of the app, not its host.

PART TEN — THE ECOSYSTEM, VERIFIED 2026-08-30

bind.com — YOS portal. Registered 1996-08-23, DigitalOcean nameservers, nginx/1.18.0 + Next.js at 146.190.132.45. No MX, no SPF, no DMARC, no CAA — the zone is apex and www only. ydid.org — identity root. Registered 2026-08-29, now on Cloudflare and resolving. yfile.org — file manager. Now on Cloudflare and resolving. yzkp.org · ywall.org — registered 2026-08-29, already delegated to Cloudflare. ysdk.org · ynoc.org — registered 2026-08-30, still on launch1/launch2.spaceship.net parking, resolving to registrar parking addresses. tokynomics.com — registered 2026-03-09, Cloudflare. tokyna.com — YTranscript, Cloudflare-proxied, the flagship integration.

ysdk.org and ynoc.org do not serve anything. An adopting app MUST NOT build against them as though they have endpoints.

APPENDIX A — WHAT THIS DOES NOT SETTLE

Stated so no adopting app mistakes silence for permission. The identity recovery model is undecided and is the keyholder's ruling. The ynoc.org cluster protocol is unspecified; the EVO-X2 is the genesis node and a network that has never had a second node is unproven as a network. ywall.org awaits the tokynomics vault architecture. yzkp.org awaits extraction from AEGIS. Per-app knowledge partitioning is specified in principle and unproven in practice. Multicodec codepoints for ML-DSA and ML-KEM are draft. @noble/post-quantum is pre-1.0 at the root of trust. No third party has audited any component of this ecosystem.

An app can reach L3 today without any of the above being resolved. That is the point of the ladder.