chore: align repo scaffolding with the package standard

.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    services:
+      postgres:
+        image: postgres:16
+        env: { POSTGRES_PASSWORD: postgres, POSTGRES_DB: cron }
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+    env:
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/cron
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - uses: oven-sh/setup-bun@v2
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+      - run: bun run test:e2e
+      - name: node consumer smoke
+        run: |
+          set -euo pipefail
+          TARBALL="$PWD/$(npm pack --silent)"
+          mkdir -p "$RUNNER_TEMP/c" && cd "$RUNNER_TEMP/c"
+          npm init -y >/dev/null && npm pkg set type=module >/dev/null
+          npm install "$TARBALL"
+          node -e 'import("@corbits/cron").then((m) => { for (const n of ["createCronRoutes", "createCronTicker", "isValidCronExpression"]) if (typeof m[n] !== "function") throw new Error("missing export: " + n); })'

.github/workflows/cla.yml

@@ -0,0 +1,53 @@
+name: CLA Assistant
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_target:
+    types: [opened, synchronize]
+
+permissions:
+  actions: write
+  contents: write
+  pull-requests: write
+  statuses: write
+
+concurrency:
+  group: cla-${{ github.event.pull_request.number || github.event.issue.number || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  cla:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Maintainer fast path
+        if: >-
+          github.event_name == 'pull_request_target' &&
+          (contains(fromJSON('["TheGreatAxios","brianjfox"]'), github.event.pull_request.user.login) ||
+           endsWith(github.event.pull_request.user.login, '[bot]'))
+        run: echo "Maintainer or bot pull request; CLA not required."
+      - name: CLA Assistant
+        if: >-
+          ((github.event.comment.body == 'recreate-signatures' ||
+            github.event.comment.body == 'I have read the CLA Document and I hereby sign the CLA') ||
+           github.event_name == 'pull_request_target') &&
+          !(github.event_name == 'pull_request_target' &&
+            (contains(fromJSON('["TheGreatAxios","brianjfox"]'), github.event.pull_request.user.login) ||
+             endsWith(github.event.pull_request.user.login, '[bot]')))
+        # corbitsdev/cla-assistant-action v2.6.1-node24: upstream v2.6.1 on node24.
+        uses: corbitsdev/cla-assistant-action@ef6d3e51db8232fe93090810f13bde30497c1d74
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          path-to-document: "https://github.com/${{ github.repository }}/blob/main/CLA.md"
+          path-to-signatures: "signatures/version1/cla.json"
+          branch: "cla-signatures"
+          allowlist: TheGreatAxios,brianjfox,*[bot]
+          custom-notsigned-prcomment: >-
+            Thank you for your contribution. Before it can be merged, please read our
+            [Contributor License Agreement](https://github.com/${{ github.repository }}/blob/main/CLA.md)
+            and sign it by posting a new comment on this pull request containing
+            exactly the line below (nothing else):
+          custom-pr-sign-comment: "I have read the CLA Document and I hereby sign the CLA"
+          custom-allsigned-prcomment: "All contributors have signed the CLA."

.gitignore

@@ -1,7 +1,8 @@
-node_modules
-dist
-.tmp
+node_modules/
+dist/
 *.tsbuildinfo
+*.tgz
+coverage/
 .env
+.env.*
 .DS_Store
-*.log

AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+## Purpose
+
+`@corbits/cron` stores a tenant's cron schedules on the Interchange hub and
+wakes agents on them. It owns the `cron` Postgres schema, the grant-gated
+schedule routes and the ticker that turns a due row into run-trigger mail. It
+does not own mail transport, run lifecycle or grants; those come from the host.
+
+## Layout
+
+- `src/cron.ts` — the one five-field UTC cron parser, used for validation and matching.
+- `src/routes.ts` — `createCronRoutes`, CRUD over a tenant's schedules.
+- `src/ticker.ts` — `createCronTicker`, polls due rows and hands each to the transport.
+- `src/deliver.ts` — the system-trigger deliverer for schedule mail.
+- `src/deployment.ts` — resolves a schedule's agent to its live anchor run at fire time.
+- `src/schema.ts` — the `cron` schema's one table.
+- `src/migrations.ts` — `runCronMigrations`, applies `migrations/*.sql`.
+- `src/index.ts` — the only module consumers import from.
+- `e2e/` — real-Postgres suites, including the 0.1.0 upgrade test.
+
+## Rules
+
+- A schedule names an agent by definition name; the run is resolved at fire time, never stored.
+- The ticker mails `<run id>@<tenant domain>` for the definition's live anchor run.
+- Ticks claim due rows with `SELECT ... FOR UPDATE SKIP LOCKED`, so concurrent tickers never deliver one row twice.
+- A schedule that missed several ticks fires once for the latest due minute.
+- Unroutable run triggers (`run_grants_not_routable` / `run_mail_not_routable`) fail a stale `running` anchor whose allocation already settled, so the next tick waits instead of retrying a dead address.
+- Every migration statement is idempotent; there is no ledger.
+- The acting tenant comes from the host context, never from a path parameter.
+
+## Local development
+
+```sh
+bun install && bun run check
+```

CLA.md

@@ -0,0 +1,64 @@
+# Contributor License Agreement (CLA)
+
+Version 1.0
+
+This Contributor License Agreement ("Agreement") is entered into between the contributor ("Contributor") and ABK Labs, Inc. ("Maintainer").
+
+By submitting any Contribution to a project maintained by Maintainer, the Contributor agrees to the following terms.
+
+## 1. Definitions
+
+"Contribution" means any source code, object code, documentation, test cases, designs, specifications, bug fixes, enhancements, comments, pull requests, commits, issues containing code, or other materials intentionally submitted to a project maintained by Maintainer.
+
+## 2. Copyright Ownership
+
+The Contributor retains ownership of the Contributor's copyrights in the Contribution.
+
+No transfer of copyright ownership is required by this Agreement.
+
+## 3. License Grant to Maintainer
+
+The Contributor grants Maintainer a perpetual, worldwide, non-exclusive, irrevocable, royalty-free license to:
+
+- use, reproduce, modify, distribute, display, perform, and sublicense the Contribution;
+- combine the Contribution with other software and works;
+- distribute the Contribution under the project's current license;
+- distribute the Contribution under future versions of the project's license;
+- distribute the Contribution under alternative open-source, source-available, commercial, proprietary, or dual-license terms.
+
+## 4. License Grant to the Public
+
+The Contributor agrees that the Contribution may be distributed as part of the applicable project under the project's then-current license terms, including LGPL-2.1 or any successor license adopted by Maintainer.
+
+## 5. Contributor Representations
+
+The Contributor represents and warrants that:
+
+1. The Contributor created the Contribution or otherwise has sufficient rights to submit it.
+2. The Contributor has the legal authority to grant the rights described in this Agreement.
+3. To the best of the Contributor's knowledge, the Contribution does not knowingly infringe the intellectual property rights of any third party.
+4. Any third-party material included in the Contribution has been properly disclosed and is compatible with the rights granted under this Agreement.
+
+## 6. Corporate Contributions
+
+If a Contribution is submitted on behalf of an employer or other legal entity, the person accepting this Agreement represents that they are authorized to bind that entity to this Agreement.
+
+## 7. No Obligation
+
+Maintainer is not obligated to use, distribute, maintain, support, or accept any Contribution.
+
+## 8. Disclaimer
+
+Except as expressly stated in this Agreement, the Contribution is provided "AS IS" without warranties or conditions of any kind.
+
+## 9. Electronic Acceptance
+
+The Contributor agrees that electronic acceptance of this Agreement, including acceptance through a website, source-control platform, click-through process, pull-request workflow, or similar mechanism, shall have the same force and effect as a handwritten signature.
+
+## 10. Governing Law
+
+This Agreement shall be governed by the laws of the State of California, excluding its conflict-of-law provisions.
+
+---
+
+By submitting a Contribution, the Contributor acknowledges that they have read and agree to this Agreement.

CONTRIBUTING.md

@@ -2,33 +2,37 @@
 
 ## Development
 
-```bash
-git clone https://github.com/corbitsdev/corbits-cron.git
-cd corbits-cron
+```sh
 bun install
-bun run build
-bun run typecheck
-bun run test
-DATABASE_URL=postgres://localhost:5432/postgres bun run test:e2e
+bun run check
 ```
 
-The `e2e/` suites create and drop one database per suite, so `DATABASE_URL` needs a Postgres 13+ role with `CREATEDB`. They skip when `DATABASE_URL` is unset. `e2e/upgrade-from-0.1.0.test.ts` migrates and writes with the published 0.1.0 package, then upgrades in place.
+`bun run check` runs typecheck, lint, format check and unit tests. `bun run format` rewrites the tree.
 
-## Migrations
-
-`migrations/*.sql` ship in the tarball and all run on every boot; there is no ledger. Every statement must be idempotent (`IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`). `"public".` references are rewritten to the host's `schema`.
+Contributors sign the [CLA](CLA.md) on their first PR; the CLA bot explains how.
 
-## Internals
+`bun run test:e2e` needs a Postgres 13+ role with `CREATEDB` in `DATABASE_URL`, e.g. `DATABASE_URL=postgres://localhost:5432/postgres bun run test:e2e`. Each suite creates and drops its own database, and suites skip when `DATABASE_URL` is unset.
 
-A tenant saves a cron expression, the agent to wake, and the mail to send it (`subject` / `body`). `createCronTicker` polls for due rows and hands each to the host's transport, so a schedule-triggered workflow is a `mail`-triggered one addressed at itself: at fire time the ticker mails `<run id>@<tenant domain>` for the definition's live anchor run.
-
-Ticks claim due rows with `SELECT ... FOR UPDATE SKIP LOCKED`, so concurrent tickers never deliver one row twice.
+## Migrations
 
-Unroutable run triggers (`run_grants_not_routable` / `run_mail_not_routable`) fail a stale `running` anchor whose allocation already settled, so the next tick waits instead of retrying a dead address.
+`migrations/*.sql` ship in the tarball and all run on every boot; there is no ledger. Every statement must be idempotent (`IF NOT EXISTS`, `ADD COLUMN IF NOT EXISTS`). `"public".` references are rewritten to the host's `schema`.
 
 ## Commit messages
 
 Commit subjects and PR titles follow [Conventional Commits](https://www.conventionalcommits.org): `feat`, `fix`, `refactor`, `test`, `docs`, `build`, `ci`, `perf`, and `chore(release): x.y.z` for releases.
 Add `!` only for public API breaks: removed or renamed exports, changed signatures, newly required params. Peer and dependency range changes are `build(deps):` with no `!`.
 Keep subjects imperative, lowercase after the colon, 72 characters or less, and free of ticket IDs.
 Every PR links its issue with a `Closes <issue id>` line in the PR body.
+
+## Releasing
+
+Releases are manual. On a clean, up-to-date `main`:
+
+```sh
+npm version <patch|minor> -m "chore(release): %s"
+git push --follow-tags
+gh release create "v$(node -p 'require("./package.json").version')" --generate-notes
+npm publish
+```
+
+Bump minor only for breaking API changes; everything else is a patch. `prepack` builds `dist/` from the tagged commit.