What Constellation does
Constellation connects the public sources you control to a cited knowledge graph. It observes your website, reads a publication you serve, or accepts one you upload, and keeps each acquisition as a complete Knowledge Publication Protocol (KPP) 1.0 publication with the exact source bytes.
Your applications ask questions through the v1 API and receive bounded, cited evidence: complete records with their citations, any qualifications those records require, a coverage report and explicit omissions. Retrieval uses exact entity and page resolution, PostgreSQL full-text search and bounded typed traversal. There is no vector database to provision or keep in sync.
Constellation also reports the operational integrations you connect, such as Vercel log delivery, with an explicit state for each one.
Four packages
@kuykendall/constellation-protocolKPP 1.0 wire types, the pinned schema, canonical hashing, identity helpers and
validateSnapshot: the collector’s exact acceptance checks, so you can reproduce a rejection before you publish.@kuykendall/constellation-publisherStatic and dynamic publishers whose output is byte-compatible with the portfolio
kpp-static/1.0.0layout;/http, a Node and Vercel handler with ETags and runtime deployment proof;/observe, semantic HTML extraction with exact UTF-8 byte-range citations, RFC 9309 robots rules, sitemaps, a bounded crawler and a build-output reader; and/conformance, the adapter conformance kit.@kuykendall/constellationThe typed v1 client, including server-side Vercel connections;
answer(), which turns evidence into a chat answer with citation validation and required-context checks; theopenAICompatibleModeladapter; and webhook signature verification.@kuykendall/constellation-cliThe
constellationcommand: init, build, validate, publish, collect, connect, sync, status, doctor and vercel. Every command accepts--json. The key is read fromCONSTELLATION_API_KEYand never printed.
Version identities are independent: release 0.2.8 pins each package’s own version (listed under Install), the HTTP API is v1 with the constellation-version header 2026-11-01, and publications are KPP 1.0.
Access and membership
Constellation is part of the software portfolio included with KI memberships. It is not sold as a separate Store product, and this page lists no separate price.
-
Projects
Kuykendall Industries provisions each Constellation project directly at this stage. Provisioning creates the project and its first admin API key, which is shown once. There is no self-service sign-up yet.
Request a project -
KI members
Current paid Kuykendall One, Ultra, and Unlimited memberships include Warden and the Constellation SDK at no additional membership charge. Sign in to your KI Store account and open Membership to download the packages for your organization.
SDK downloads included with current paid membership
-
KI employees
Employee access is provided by the company and needs no Store account or membership. Sign in to the KI Employee Portal, then download the packages from this page.
Sign in to the Employee Portal
Install the SDK
Release 0.2.8 is a prerelease distributed as 4 tarballs. Publication to the npm registry is not available yet, so there is no registry install command. Download the tarballs, check their SHA-256 values, then install them from the folder that holds them.
The links below use your KI Employee Portal session. Members download these same packages from their KI Store membership account. Connected service coverage is reported separately under Status.
@kuykendall/constellation-protocolKPP 1.0 types, the pinned schema, canonical hashing and the collector-identical validateSnapshot.
- Version
- 0.1.0
- File
kuykendall-constellation-protocol-0.1.0.tgz- Size
- 14.9 KiB · 15,236 bytes
- SHA-256
7113906b9e6ba1f36bbfcf04b9c16c2a2d6298840c07ee9a51664654864af31c
@kuykendall/constellation-publisherStatic and dynamic publishers, the Node/Vercel publication handler, the /observe site reader and the /conformance adapter kit.
- Version
- 0.1.4
- File
kuykendall-constellation-publisher-0.1.4.tgz- Size
- 52.8 KiB · 54,051 bytes
- SHA-256
9414db9dcec2fa90422d05f45bba12131c2e8c1f1f0fee5d34a9dcc49fb2fe75
@kuykendall/constellationTyped v1 API client, Warden telemetry and browser instrumentation, monitoring and firewall controls, scoped incident, persistent observer and investigation reads, authenticated repair reports, answer() and webhook signature verification.
- Version
- 0.2.8
- File
kuykendall-constellation-0.2.8.tgz- Size
- 37.4 KiB · 38,266 bytes
- SHA-256
13d35b9de2f34ca46083c3f47f4a2203244f46ead305f8a68891d27b4d5881c0
@kuykendall/constellation-cliThe constellation command: init, build, validate, publish, collect, connect, sync, status, doctor and vercel.
- Version
- 0.1.12
- File
kuykendall-constellation-cli-0.1.12.tgz- Size
- 17.9 KiB · 18,367 bytes
- SHA-256
85c48a59a8b29d5561368fe929bc254b2851b543d714e208b8aaaf0f23b02ec8
Verify the files
Save this text as SHA256SUMS in the download folder and check every file before you install it. On Windows, compare Get-FileHash -Algorithm SHA256 output with the values above.
7113906b9e6ba1f36bbfcf04b9c16c2a2d6298840c07ee9a51664654864af31c kuykendall-constellation-protocol-0.1.0.tgz
9414db9dcec2fa90422d05f45bba12131c2e8c1f1f0fee5d34a9dcc49fb2fe75 kuykendall-constellation-publisher-0.1.4.tgz
13d35b9de2f34ca46083c3f47f4a2203244f46ead305f8a68891d27b4d5881c0 kuykendall-constellation-0.2.8.tgz
85c48a59a8b29d5561368fe929bc254b2851b543d714e208b8aaaf0f23b02ec8 kuykendall-constellation-cli-0.1.12.tgz
sha256sum -c SHA256SUMS # Linux
shasum -a 256 -c SHA256SUMS # macOS
Install the packages
Install all 4 in one command so the packages resolve each other locally. Their open-source dependencies (ajv, ajv-formats and parse5) come from the public npm registry. The complete four-package installation requires Node.js 20.19.0 or newer. The client and protocol packages on their own support Node.js 20.11.0 or newer; the publisher and CLI require 20.19.0 or newer.
npm install ./kuykendall-constellation-protocol-0.1.0.tgz ./kuykendall-constellation-publisher-0.1.4.tgz ./kuykendall-constellation-0.2.8.tgz ./kuykendall-constellation-cli-0.1.12.tgz
npx constellation --version
Quickstarts
Commands that contact the API read a project key from CONSTELLATION_API_KEY. Export it in your shell or your CI secret store; never commit it. init, build and validate work offline.
Connect a website
Constellation observes only hosts your project has verified. Read the project’s verification token with an admin key (it is the verification.token field), then publish it either as the content of https://<host>/.well-known/constellation-verification.txt or as a DNS TXT record named _constellation-verification.<host>.
curl -sS https://ki-congress-web.onrender.com/api/constellation/v1/project \
-H "Authorization: Bearer $CONSTELLATION_API_KEY" \
-H "constellation-version: 2026-11-01"
If the host is not on the project yet, add it; then ask Constellation to check the token.
curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/domains \
-H "Authorization: Bearer $CONSTELLATION_API_KEY" \
-H "constellation-version: 2026-11-01" \
-H "Idempotency-Key: add-www-example-com" \
-H "content-type: application/json" \
-d '{"host":"www.example.com"}'
curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/domains/www.example.com/verify \
-H "Authorization: Bearer $CONSTELLATION_API_KEY" \
-H "constellation-version: 2026-11-01"
Then connect the site and acquire it. connect prefers a KPP feed the site already publishes at /.well-known/knowledge-feed.json and otherwise registers an observation source; sync starts an acquisition and waits for the job. init writes constellation.config.json, which remembers the connected source for sync and status.
npx constellation init --url https://www.example.com
npx constellation connect https://www.example.com && npx constellation sync
npx constellation status
Publish from a build
Use this when your HTML is generated at build time. build --dir reads the rendered output, follows cleanUrls and trailingSlash from vercel.json, skips error and noindex pages, records the exact commit and repository from your CI environment or Git, and writes a publication to .knowledge. validate runs the collector’s acceptance checks locally. connect --mode push registers a push source once; publish uploads only the blobs Constellation does not already hold and waits until the publication is adopted.
npx constellation init --mode build --origin https://www.example.com
npx constellation build --dir dist
npx constellation validate
npx constellation connect --mode push
npx constellation publish
Publish records from your own code
When your records already live in code or a database, publish them directly. publishSnapshot validates the complete publication with the collector’s checks before it writes anything. A qualification that must travel with a claim is its own node, listed in the claim’s requiredContext.
// scripts/publish-knowledge.mjs — run after your build
import { publishSnapshot } from '@kuykendall/constellation-publisher';
const origin = 'https://www.example.com';
const identity = {
sourceId: 'urn:kpp:example-com:catalog',
publisherId: `${origin}/#organization`,
scopeId: 'example-com',
partition: 'catalog',
visibility: 'public',
policyRevision: 'public/1',
};
const record = { price: 'Custom cakes start at $45.', notice: 'Orders need three days of notice.' };
const resourceId = `${origin}/records/custom-cakes`;
publishSnapshot({
identity, origin, outputDirectory: '.knowledge',
extractorVersion: 'example-catalog/1', mappingVersion: 'example-kpp/1',
resources: [{ resourceId, canonicalUrl: `${origin}/cakes`, title: 'Custom cakes',
bytes: JSON.stringify(record) + '\n', mediaType: 'application/json; charset=utf-8',
representation: 'structured_public_record' }],
nodes: [
{ assertionId: `${origin}/kpp/nodes/notice`, entityId: `${origin}/#cake-notice`,
entityType: 'https://schema.org/Text', label: 'Ordering notice',
attributes: { text: record.notice }, evidenceResources: [resourceId] },
{ assertionId: `${origin}/kpp/nodes/price`, entityId: `${origin}/#cake-price`,
entityType: 'https://schema.org/Offer', label: 'Custom cake price',
attributes: { text: record.price, requiredContext: [`${origin}/#cake-notice`] },
evidenceResources: [resourceId] },
],
edges: [],
});
Serve the publication from your origin with the handler, using the same routes as the Kuykendall Industries portfolio sites. It answers conditional requests with ETags and refuses anything that is not part of the publication.
// api/knowledge.js — serves the publication in .knowledge
import { createKnowledgeHandler } from '@kuykendall/constellation-publisher/http';
export default createKnowledgeHandler();
{
"functions": { "api/knowledge.js": { "includeFiles": ".knowledge/**" } },
"rewrites": [
{ "source": "/.well-known/knowledge-feed.json", "destination": "/api/knowledge?resource=discovery" },
{ "source": "/api/knowledge/v1/manifest", "destination": "/api/knowledge?resource=manifest" },
{ "source": "/api/knowledge/v1/health", "destination": "/api/knowledge?resource=health" },
{ "source": "/knowledge/v1/snapshots/:revision/:artifact", "destination": "/api/knowledge?resource=snapshots/:revision/:artifact" },
{ "source": "/knowledge/v1/content/:digest", "destination": "/api/knowledge?resource=content/:digest" }
]
}
Check the served feed with the same rules, then register it. Without --mode, connect finds the feed by itself.
npx constellation validate --feed https://www.example.com/.well-known/knowledge-feed.json
npx constellation connect https://www.example.com --mode publisher
Retrieval and chat
retrieve() returns an evidence packet: numbered evidence items with exact citations, the required-context items each one depends on, a coverage report per source and explicit omissions. A record whose qualification cannot be produced is withheld rather than sent without it.
answer() retrieves evidence, asks your model to answer only from it, checks every citation, number and required qualification against the exact packet, asks for one repair when a check fails, and records the accepted answer with its source dependencies so a later source change invalidates it.
// Server-side code only: keep project keys out of browser bundles.
import { Constellation, answer, openAICompatibleModel } from '@kuykendall/constellation';
const constellation = new Constellation(); // reads CONSTELLATION_API_KEY
const packet = await constellation.retrieve({ query: 'What do custom cakes cost?', limit: 8 });
// packet.evidence, packet.requiredContext, packet.coverage and packet.omissions
const result = await answer({
client: constellation,
question: 'What do custom cakes cost?',
model: openAICompatibleModel({
baseUrl: process.env.MODEL_BASE_URL, // any OpenAI-compatible endpoint
apiKey: process.env.MODEL_API_KEY,
model: process.env.MODEL_NAME,
}),
});
if (!result.check.valid || result.stale) {
console.error('Answer requires review', result.check);
} else {
console.log(result.answer, result.citations.map((item) => item.url));
}
If the optional repair still fails citation checks, the result remains a draft with check.valid: false and output: null; the SDK does not attempt to record it. Streamed text is draft output. Check validity and source freshness before displaying an accepted answer.
Bring your own model
A model is any function that takes chat messages and returns the answer text; call onDelta to stream. answer() calls only the model you pass in, so your model account, keys and costs stay yours. A supplied signal stops pending SDK waits and prevents later model, repair or save calls. Results and receipts accepted before cancellation remain available. A provider must honor the signal to stop its own work; remote effects are not rolled back.
const model = async (messages, { signal, onDelta }) => {
const reply = await myModelClient.chat({ messages, signal }); // your provider SDK
return reply.text;
};
const stop = new AbortController(); // Call stop.abort() from your cancellation handler.
const result = await answer({ client: constellation, question, model, signal: stop.signal });
The same request over HTTP
curl -sS https://ki-congress-web.onrender.com/api/constellation/v1/retrieve \
-H "Authorization: Bearer $CONSTELLATION_API_KEY" \
-H "constellation-version: 2026-11-01" \
-H "content-type: application/json" \
-d '{"query":"What do custom cakes cost?","limit":8}'
The request accepts query (up to 500 characters), optional sources and requiredSources (source IDs), limit (1–50), maxChars (1,000–100,000), and since and until timestamps.
Keys in browsers
Keep read, write and admin keys on your server. A public key can read only sources you made public and never sees restricted sources, jobs or administration; ship one to a browser only when that exposure is what you intend.
Events and webhooks
Event deliveries carry constellation-signature (a timestamp and an HMAC-SHA256 of the raw body) and constellation-event-id. The verifier authenticates the raw bytes, then requires the header to match the signed payload’s own id. It returns that authenticated identity; any current secret is accepted during a rotation.
import { verifyDelivery } from '@kuykendall/constellation/webhooks';
export async function POST(request) {
const event = await verifyDelivery({
secret: process.env.CONSTELLATION_WEBHOOK_SECRET,
rawBody: await request.text(),
signature: request.headers.get('constellation-signature'),
eventId: request.headers.get('constellation-event-id'),
}); // throws SIGNATURE_MISSING, SIGNATURE_INVALID, SIGNATURE_EXPIRED,
// EVENT_ID_INVALID or EVENT_ID_MISMATCH
console.log(event.id);
return new Response(null, { status: 204 });
}
Before an application effect, check the expected project and current authority. Deduplicate the returned event.id durably within the receiving subscription and project, committing that record atomically with the effect or using the destination’s idempotency mechanism. A retry signed with a newer timestamp keeps the same event ID; signature verification alone does not store replay state.
Authentication and keys
Send a project key as Authorization: Bearer <key>. Keys look like ck_live_ (production) or ck_test_ followed by a six-character prefix and the secret. Constellation stores only a SHA-256 digest; the secret is shown once, when the key is created. Authority comes from the key’s project: IDs in a path or body only select records inside that project.
| Capability | Allows |
|---|---|
public | Listing, reading and retrieving from sources that are public. Never restricted sources, jobs or administration. |
read | Every source in the project, with coverage, history and jobs. |
write | Everything read allows, plus sync, uploads, and cancelling or retrying jobs. |
admin | Everything write allows, plus domains, keys, and registering, changing, revoking or erasing sources. |
Create narrower keys with an admin key and store the returned secret in your secret manager. Revocation is immediate: a revoked key fails its next request exactly like an unknown key.
curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/keys \
-H "Authorization: Bearer $CONSTELLATION_API_KEY" \
-H "constellation-version: 2026-11-01" \
-H "Idempotency-Key: create-site-chat-key-1" \
-H "content-type: application/json" \
-d '{"name":"Site chat (server)","capabilities":["public"]}'
curl -sS -X POST https://ki-congress-web.onrender.com/api/constellation/v1/project/keys/KEY_ID/revoke \
-H "Authorization: Bearer $CONSTELLATION_API_KEY" \
-H "constellation-version: 2026-11-01" \
-H "Idempotency-Key: revoke-site-chat-key-1"
Request rules
- Version. Send
constellation-version: 2026-11-01. An unsupported value fails withVERSION_UNSUPPORTED. Every response carriesconstellation-api-versionandx-request-id. - Idempotency. Commands that register, change, revoke or erase records, start a sync, commit an upload, or manage jobs, domains and keys require an
Idempotency-Keyof 8–200 characters. Retrying with the same key and body replays the original receipt; the same key with a different body fails withIDEMPOTENCY_CONFLICT. The SDK client generates keys for you. - Revisions. Changing a source requires
If-Matchwith the revision you read; a stale revision fails withREVISION_CONFLICT. - Rate limits. Over the limit, requests receive 429
RATE_LIMITEDwithRetry-After. The client retries reads and keyed commands with backoff.
Errors use one envelope:
{
"error": {
"code": "DOMAIN_NOT_VERIFIED",
"message": "Verify www.example.com for this project before observing it.",
"retryable": false,
"requestId": "7b0e2b8c-5f0a-4c4e-9a43-2a8f6f0d3e11",
"details": { "host": "www.example.com" }
}
}
API reference
Base URL: https://ki-congress-web.onrender.com/api/constellation/v1. Use this address for API calls: constellation.kuykendall.industries is the browser workspace and refuses bearer credentials with HTTP 421. Set CONSTELLATION_API_URL to point the SDK elsewhere. Project provisioning (POST /projects) is performed by Kuykendall Industries and is not available to project keys.
Project, domains and keys
| Method | Path | Purpose |
|---|---|---|
| GET | /openapi.json | The machine-readable contract; no key required. |
| GET | /project | The key’s project, domains, capabilities and limits. |
| POST | /project/domains | Add a host to verify. |
| POST | /project/domains/{host}/verify | Check the well-known file or DNS TXT token. |
| GET | /project/keys | List keys by prefix; secrets are never returned. |
| POST | /project/keys | Create a key; the secret is returned once. |
| POST | /project/keys/{id}/revoke | Revoke a key immediately. |
Sources and uploads
| Method | Path | Purpose |
|---|---|---|
| GET | /sources | List sources with health and coverage. |
| POST | /sources | Register an observe, publisher or push source. |
| GET | /sources/{id} | One source. |
| PATCH | /sources/{id} | Rename, change observation rules, pause or resume (with If-Match). |
| POST | /sources/{id}/sync | Start an acquisition job now. |
| GET | /sources/{id}/coverage | Every route’s outcome from the last complete observation. |
| GET | /sources/{id}/history | Adopted publications over time. |
| POST | /sources/{id}/revoke | Disconnect and withhold evidence. |
| POST | /sources/{id}/erase | Irreversibly erase retained data; requires a reason. |
| POST | /sources/{id}/uploads | Begin a push upload with the manifest (up to 1 MiB). |
| PUT | /sources/{id}/uploads/{uploadId}/blobs/{sha256} | Upload one declared blob (up to 16 MiB). |
| POST | /sources/{id}/uploads/{uploadId}/commit | Validate and adopt the complete publication. |
Jobs
| Method | Path | Purpose |
|---|---|---|
| GET | /jobs | Recent acquisition and adoption jobs. |
| GET | /jobs/{id} | One job, its attempts and its error code. |
| POST | /jobs/{id}/cancel | Cancel a queued or running job. |
| POST | /jobs/{id}/retry | Retry a failed, cancelled or dead-lettered job. |
Graph, retrieval and outputs
| Method | Path | Purpose |
|---|---|---|
| GET | /graph/entities | Search entities by text, type or source. |
| GET | /graph/entities/{id} | One entity with its evidence. |
| GET | /graph/entities/{id}/neighborhood | Bounded typed traversal around an entity. |
| GET | /graph/changes | Recent graph changes, paged by cursor. |
| POST | /retrieve | Cited evidence for a question. |
| POST | /outputs | Record an answer with its exact dependencies. |
| GET | /outputs/{id} | An output and whether it needs revalidation. |
Operations, events and usage
| Method | Path | Purpose |
|---|---|---|
| GET | /integrations | Connected integrations and their states. |
| GET | /integrations/{id} | One integration. |
| GET | /incidents | Grouped operational incidents. |
| GET | /incidents/{id} | One incident with its evidence. |
| GET | /events | Project events after a cursor. |
| GET | /webhooks | Webhook subscriptions. |
| POST | /webhooks | Subscribe a URL to event types. |
| POST | /webhooks/{id}/disable | Stop deliveries to a subscription. |
| GET | /usage | Usage against the project’s limits. |
Source lifecycle
Three ways in
observe- Constellation reads your public website within explicit bounds: robots rules (RFC 9309), sitemaps, include and exclude rules, and page limits. The host must be a verified project domain.
publisher- Constellation reads the KPP publication you serve, starting from its discovery document. The feed must be public, its
canonicalOriginmust match its URL, and its host must be verified. push- You upload complete publications with
constellation publishor the uploads API. A push source acquires when an upload is committed.
How a source changes
- Every acquisition is validated as a complete publication before it replaces the previous one. A partial or cancelled observation is never adopted; it resumes on the next sync.
- A page is removed only on a definitive signal: 404 or 410, a robots or scope exclusion,
noindex, a redirect or a canonical duplicate. - A temporary failure, such as a timeout, a network error, a 429 or a 5xx response, keeps the last retained version, marked as carried forward.
- Scheduled observation syncs run at most every 15 minutes.
Pause, revoke or erase
- Pause
- Set
statetopausedwithPATCH /sources/{id}; set it back toactiveto resume. - Revoke
- Disconnects the source: acquisition stops and its evidence is withheld from retrieval. Retained history stays for audit until you erase it.
- Erase
- Irreversibly removes the retained bytes, the derived graph, passages and dependent outputs. It requires a reason, and only the project that owns the source can erase it.
Vercel logging
Constellation receives signed Vercel log deliveries, groups them into incidents and reports each integration’s state. Kuykendall Industries runs this intake for its own Vercel projects today.
Customer self-connection: implemented, pending release
A project’s admin key connects your own Vercel team from your server, with integrations.connectVercel({ token, teamId, projectIds }) or the vercel command below, which reads a team-scoped token from VERCEL_TOKEN. The token is sent once; Constellation seals it and never returns or prints it. Constellation then creates a log drain signed with a secret only it holds, reads the drain back and reports any difference. rotateSecret replaces the signing secret make-before-break, and disconnect removes the drain and reports whether its removal was confirmed.
npx constellation vercel connect --team <team id> --project <project id>
npx constellation vercel verify --url <URL of a request that logged a warning or error>
npx constellation vercel status
npx constellation vercel rotate
npx constellation vercel disconnect --yes
integrations.verify(id, { requestId }), which vercel verify calls with the response’s x-vercel-id, proves that a known warning or error reached the intended project and deployment through a signed delivery. The service release that accepts customer connections has not shipped yet; until it does, production refuses them. GET /integrations and GET /incidents report what is connected.
| State | Meaning |
|---|---|
connected | Vercel access is authorized; no project or environment is selected yet. |
configured | Projects and environments are selected; no signed delivery has arrived yet. |
receiving | Signed log deliveries are arriving. |
runtime_verified | A known request, identified by its x-vercel-id, was confirmed in the intended project’s and deployment’s logs, not only received. |
stale | No delivery has arrived since the integration’s staleAfter time. |
unavailable | The current state cannot be read; it is not treated as healthy. |
failed | Configuration or delivery failed and needs attention. |
constellation doctor reports configured, receiving and runtime_verified as working and every other state as a problem to fix.
Warden, By Kuykendall Industries
AI firewall and online system monitoring live inside Constellation. Warden is included at no additional membership charge with Kuykendall One, Ultra, and Unlimited, through the existing Constellation SDK and account boundary.
Connect Vercel, Supabase, and application telemetry to follow external probes, scaling pressure, backend failures, and browser errors. Each incident retains its evidence, investigation, repair ticket, execution receipts, and production checks.
For a member project, open MABOS-Code, select the project, and choose Warden. Its settings connect the repair agent, set an explicit customer-funded model allowance, and define any permitted database recovery tables and row boundaries. Automatic deployment uses the selected Vercel project, current provider authorization, the separate Warden Release App, and the repository's protected config/warden/probes.json catalogue. The settings show which prerequisites are ready.
Warden is included in downloadable SDK 0.2.8. Service availability and observed runtime coverage are shown under Status.
The Warden entry point extends @kuykendall/constellation. It uses an authenticated Congress access token, an authorized workspace, and a server-issued run. Existing customer project keys are not Congress access tokens. Keep server credentials on your server; browser instrumentation sends through your application’s authenticated same-origin proxy.
import { Warden, createWardenMonitor } from '@kuykendall/constellation/warden';
const warden = new Warden({
accessToken: process.env.CONGRESS_ACCESS_TOKEN,
scopeId: process.env.CONGRESS_SCOPE_ID,
agentRunId: process.env.CONGRESS_RUN_ID,
integrationId: process.env.WARDEN_INTEGRATION_ID,
});
const monitor = createWardenMonitor({
projectId: process.env.WARDEN_PROJECT_ID,
send: (events, key) => warden.capture(events, key),
});
export async function reportApplicationFailure(error) {
monitor.captureException(error);
await monitor.flush();
}
const incidents = await warden.incidents();
export async function readRepairReport(notificationId, signal) {
const { report } = await warden.notificationReport(notificationId, signal);
return report;
}
Call reportApplicationFailure(error) from your application’s existing error handler. Use a real configured integration and its mapped project. configureObservation establishes the permitted intake mapping; it does not report that an event was observed. capture returns the durable intake receipt, while incidents(), notifications(), status(), and task(id) read the recorded work.
notificationReport(notificationId, signal) reads the investigation, repair ticket, release, production checks, and recovery record for an existing notice. It keeps current verification separate from historical evidence. Reading or refreshing a report does not acknowledge the notice or create another notification.
- Detection and investigation
- Provider firewall rules enforce request protection. Warden correlates the resulting signals and investigates asynchronously. Incident text is evidence; it cannot authorize a repository change or deployment.
- Repair routing
- A ticket can use the project’s authorized MABOS-Coding agent, an isolated KI-hosted coding agent, or a connected Cursor agent. Constellation retains the target repository, execution authority, and recorded outcome.
- Verification and recovery
- Code, test, deploy, then verify the actual production deployment. Code rollback and database recovery have separate evidence. A database change needs a migration-aware recovery plan that preserves subsequent writes.
- Three notifications at most
- Issue found. Ticket dispatched. Repair verified in production. Retries and intermediate agent work stay in the incident timeline. A provider’s “completed” status alone cannot produce a success notification.
Membership inclusion does not establish monitoring coverage by itself. Constellation reports the integrations actually connected, the last verified intake, the agent route, and the status of each repair. Existing agreed compute, model, and external-provider allowances continue to apply.
Custom adapters
An adapter turns a source system, such as a CMS, a repository, a database, a hosting provider or a runtime, into Constellation knowledge. An adapter is anything that produces a complete KPP 1.0 publication that passes validateSnapshot: a manifest, the nodes, edges and content_index artifacts, and the exact bytes of every content record. buildStaticPublication and buildDynamicPublication run that check before anything is written or uploaded.
What every publication needs
- Stable identity: one
sourceId,publisherId,scopeId,partition,visibilityandpolicyRevision, never derived from a display name or reused from another source. - Exact evidence: every node and edge cites a content record by
resourceId,resourceRevisionandsha256, preferably withutf8_byte_rangelocators. - Complete records: the source’s full bytes, never an excerpt published as the source.
- Required context: a qualification such as pricing, availability, legal or policy terms is its own node with evidence, listed in the claim’s
attributes.requiredContext(andrequiredContextIdsfor older consumers). - Honest basis and lineage:
authored_publication,database_publicationorobserved_page, with lineage for copied or compiled material. - Completeness: a partial or cancelled acquisition is never published, and only a definitive signal removes a record.
Validate before you deliver
import { validateSnapshot } from '@kuykendall/constellation-protocol';
// manifestBytes: the exact manifest; fetched: a Map from every artifact and
// content URL to its exact bytes; identity: the source identity you declared.
const snapshot = validateSnapshot(manifestBytes, fetched, identity);
// Throws a KppError carrying the collector's own code, such as KPP_EVIDENCE_UNRESOLVED.
From the command line, npx constellation validate --dir .knowledge checks a local publication and npx constellation validate --feed <discovery URL> checks a served one.
Conformance
checkAdapterConformance(adapter, scenario) from @kuykendall/constellation-publisher/conformance runs the adapter contract against your own fixtures. An adapter has a name, a version, its source identity and a run(input, context) that returns whether it is complete, the validated publication and an outcome for every discovered item. The scenario supplies a baseline and, optionally, an edit, a temporary failure, a deletion, a qualified claim and a cancellation point.
The report checks that the output passes validateSnapshot and is deterministic; that every discovered item has an explicit outcome; that evidence is exact; that an edit changes only the affected records; that a temporary failure keeps a record while a definitive deletion removes it; that qualifications survive as resolvable required context; and that cancellation leaves no publication while resumption completes it. The built-in website observer, createSiteAdapter from /observe, passes every check. Kuykendall Industries lists an adapter as supported only after its report passes.
Troubleshooting with constellation doctor
Start with doctor. It checks Node, the config file, the local publication, the key (shown only by its prefix), API reachability, domains, sources and integrations, and prints a fix for each problem. Add --json for machine-readable output.
npx constellation doctor
| Code | What it means and what to do |
|---|---|
DOMAIN_NOT_VERIFIED | The host is not a verified domain of the project. Publish the token at the well-known path or the DNS TXT record, then verify the domain. |
KPP_PUBLICATION_UNCONFIRMED | The feed was archived but has no production confirmation. Register publisher sources with origin confirmation, which is what constellation connect does by default. |
KPP_SOURCE_UNAVAILABLE | The publisher could not be read. Check that the site is up and the feed URL is public. |
OBSERVATION_INCOMPLETE | The last observation did not finish. It resumes on the next sync and never replaces the previous complete publication. |
CRAWL_DESTINATION_BLOCKED | The site resolves to a private address. Run a local collector with constellation collect, which observes a site you operate and uploads it to a push source. |
IDEMPOTENCY_CONFLICT | The Idempotency-Key was used with a different request. Use a new key for a new request; reuse a key only to retry the identical request. |
KEY_CAPABILITY_REQUIRED | The key lacks the capability the operation needs. Use a key with the capability named in details.required. |
UNAUTHENTICATED | The key is missing, unknown, expired or revoked. Create a new key with an admin key. |
Quotas and retention
These are the defaults. A project can have different limits; GET /project returns the limits that apply to it.
| Limit | Default |
|---|---|
| Sources per project | 25 |
| Pages per observation | 200 |
| Retained bytes per source | 64 MiB |
| Retrievals | 120 per minute |
| API requests per key | 600 per minute |
| Sync interval | At least 15 minutes |
| Retention | 365 days |
| Push uploads | Manifest up to 1 MiB, each blob up to 16 MiB; an open upload expires after 24 hours |
Compatibility and migrations
- Protocol. Publications use KPP 1.0. The pinned schema’s SHA-256 is
6d2643b240003c0fc69a7fad961df05b99e115500b19fab91dc227d34746e532. - API. The path carries the major version (
v1) and theconstellation-versionheader selects the contract (2026-11-01). Package, API and protocol versions change independently. - Portfolio publishers.
publishSnapshotfrom@kuykendall/constellation-publishertakes the same arguments and writes the samekpp-static/1.0.0layout as the portfolio publisher, byte for byte, includingcurrent.json. Identical input produces the identicalcontentRevision, so collectors see no change. The handler also accepts the existing?resource=rewrites.
// Before: import { publishSnapshot } from './lib/knowledge/publisher.js';
import { publishSnapshot } from '@kuykendall/constellation-publisher';
After switching, rebuild and compare the new contentRevision with the one you serve. For the same input, they match.
Status
Capability and release status
As of . Implemented means the code exists in the SDK or the service. Deployed and Runtime observed require the released service in production; a build or a test run does not count.
| Capability | Implemented | Deployed | Runtime observed |
|---|---|---|---|
KPP 1.0 types, pinned schema and collector-identical validation @kuykendall/constellation-protocol | Implemented | Pending release | Pending release |
Static and dynamic publishers, byte-compatible with the kpp-static/1.0.0 layout @kuykendall/constellation-publisher | Implemented | Pending release | Pending release |
Node and Vercel publication handler with deployment proof @kuykendall/constellation-publisher/http | Implemented | Pending release | Pending release |
Semantic HTML extraction with exact byte-range citations, robots, sitemaps and a bounded crawler @kuykendall/constellation-publisher/observe | Implemented | Pending release | Pending release |
Build-output reader with commit provenance @kuykendall/constellation-publisher/observe | Implemented | Pending release | Pending release |
Adapter conformance kit: validation, outcomes, evidence, required context, determinism, scoped change, carry-forward, deletion and resumable cancellation @kuykendall/constellation-publisher/conformance | Implemented | Pending release | Pending release |
Typed v1 API client @kuykendall/constellation | Implemented | Pending release | Pending release |
answer() with citation validation and required-context checks @kuykendall/constellation | Implemented | Pending release | Pending release |
Webhook signature verification @kuykendall/constellation/webhooks | Implemented | Pending release | Pending release |
constellation init, build, validate, publish, collect, connect, sync, status, doctor and vercel @kuykendall/constellation-cli | Implemented | Pending release | Pending release |
Versioned API at /api/constellation/v1 with idempotent mutations Constellation service | Implemented | Pending release | Pending release |
Projects, domain verification and revocable API keys Constellation service | Implemented | Pending release | Pending release |
Observe, publisher and push sources with jobs, coverage and uploads Constellation service | Implemented | Pending release | Pending release |
Cited retrieval with required context and explicit omissions Constellation service | Implemented | Pending release | Pending release |
Customer self-connection of Vercel log delivery: sealed team token, signed drain with readback, runtime verification, secret rotation and disconnect Constellation service | Implemented | Pending release | Pending release |
Warden telemetry, browser errors, Supabase monitoring, firewall and drain controls, scoped incident and repair reads @kuykendall/constellation/warden | Implemented | Pending release | Pending release |
Warden included with paid One, Ultra and Unlimited memberships, with independent connection and runtime coverage state Constellation and KI Store | Implemented | Pending release | Pending release |
Live service status
Open the status report or the service health endpoint directly. This check reports reachability and the deployed release; it is not a product acceptance test.

