Aller au contenu principal

Contributing

Zeq is an open-core project. We welcome contributions to every part of the open stack. The non-open parts are labeled clearly in the repo, and PRs that touch them will be declined — it's not personal, those are the bits that keep the lights on.

What's open​

  • Protocol registry (app/artifacts/api-server/src/lib/protocols.ts)
  • All reference applications (app/artifacts/api-server/public/apps/*)
  • SDK source — TypeScript (app/packages/sdk/), MCP (app/packages/zeqsdk-mcp/), Python (app/sdk/python/)
  • Operator registry (app/packages/sdk/src/operators.ts)
  • Documentation (sdk-docs/source/)
  • Integration tests (app/artifacts/api-server/tests/)

What's closed​

  • API gateway runtime (app/artifacts/api-server/src/app.ts, src/routes/auth.ts, etc.) — binary-only release.
  • Key issuance & signing service.
  • Compute backend.
  • Internal ops tooling (app/deploy/, app/scripts/internal/).
  • Hosted HulyaPulse clock.

The repo is structured so the open pieces can be built and run without any closed piece. The closed pieces are replaceable locally — you can self-host the full stack, just with your own keys and your own clock.

Ways to contribute​

Add a protocol​

Edit app/artifacts/api-server/src/lib/protocols.ts and append a new entry:

{
  id: "zeq-your-protocol",
  category: "Applied Physics",
  description: "One-line description",
  formula: "Your_formula_here = ...",
  operators: ["KO42", "QM9", "NM23"],
  params: {
    m_kg:   { type: "number", required: true, description: "mass, kg" },
    v_mps:  { type: "number", required: true, description: "velocity, m/s" },
  },
  example: {
    params: { m_kg: 1, v_mps: 100 },
    expected: { /* ... */ },
  },
}

Run cd sdk-docs/source && npm run build — the generator will emit a docs page automatically.

Port the SDK to a new language​

Highest-impact contribution. See Build → SDKs → Python for what a port looks like. Target interface parity with @zeq-os/sdk:

ZeqClient              → thin wrapper over the hosted API
pulse()                → local pulse read
unixToZeqond / zeqondToUnix  → deterministic math, no network
getOperators / DOMAINS → operator registry (ported from sdk/src/operators.ts)
ZeqMail / ZeqMesh / ZeqDaemon clients  → vertical API wrappers

Languages we'd especially like to see: Go, Rust, Java, C#, Ruby, PHP.

Fix an app / build a new one​

Apps live in app/artifacts/api-server/public/apps/<app-name>/. Each is a static bundle (HTML + inline JS/CSS). Guidelines:

  • One app, one directory.
  • index.html at the root.
  • No frameworks with runtime builds — ship pre-built assets only.
  • Call the SDK via the CDN build (for non-Node apps) or a bundled copy.
  • Mark it as open-source: Apache-2.0 header in each source file.

Documentation​

This docs site is Docusaurus. Content is in sdk-docs/source/docs/. PRs welcome.

PR workflow​

  1. Fork github.com/hulyasmath/zeq-framework.
  2. Branch off main.
  3. Write the change + tests.
  4. Run pnpm run build && pnpm test at the repo root.
  5. Open the PR. We review on the HulyaPulse — 1.287 Hz is real, but review cadence is human.

Governance​

The framework has a technical custodian (Zeq H — founder) who has final say on merges to main. That's pragmatic: the framework's math has to be consistent, and one person has to own that consistency. Expect:

  • Fast iteration on apps and SDK code.
  • Slower, more careful review on anything touching operators or the protocol schema.
  • No PRs accepted that claim ≤0.1% error without a working KO42 proof.

Code of conduct​

Be kind. The framework is a serious mathematical project; criticism is welcome, cruelty is not.