[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_286":287,"_288":289},"routes/_app.x.$handle.$name",{"_11":12,"_13":14,"_15":16,"_17":18,"_40":-7,"_145":-5,"_19":146,"_147":148,"_149":150,"_151":152,"_153":154,"_21":155,"_156":-5,"_157":-5,"_158":24,"_159":160,"_161":24,"_162":-5,"_163":-5,"_164":165},"routes/_app.x.$handle.$name.branch.$branch.history_.$",{"_11":12,"_13":14,"_15":16,"_17":18,"_19":20,"_21":22,"_23":24,"_25":26,"_27":28,"_29":24,"_30":-5},"handle","plusjade","name","source-sdk","branchName","main","path","sdk/contract.ts","project",{"_34":98,"_13":14,"_38":99,"_96":-5,"_100":24,"_101":102,"_103":102,"_104":105,"_106":-5,"_30":71,"_107":-5,"_108":24,"_109":-5,"_110":-5,"_111":26,"_42":43,"_112":-5,"_113":-5,"_114":-5,"_115":-5,"_116":117,"_118":117,"_119":120,"_121":120,"_122":120,"_123":117,"_124":117,"_55":125,"_126":127,"_128":129,"_130":24},"file",{"_65":66,"_13":67,"_68":69,"_70":24,"_97":-5},"isDirectory",false,"page",0,"history",[31,32,33],"hasNext","userId",{"_34":82,"_36":37,"_38":83,"_40":84,"_42":43,"_44":85,"_46":86,"_47":-5,"_48":-5,"_49":-5,"_50":-5,"_51":52,"_53":87,"_55":88,"_21":89,"_58":-5,"_59":90,"_60":-5,"_61":-5,"_62":91},{"_34":74,"_36":37,"_38":75,"_40":76,"_42":43,"_44":77,"_46":-5,"_47":-5,"_48":-5,"_49":-5,"_50":-5,"_51":52,"_53":54,"_55":78,"_21":79,"_58":-5,"_59":-5,"_60":-5,"_61":-5,"_62":80},{"_34":35,"_36":37,"_38":39,"_40":41,"_42":43,"_44":45,"_46":-5,"_47":-5,"_48":-5,"_49":-5,"_50":-5,"_51":52,"_53":54,"_55":56,"_21":57,"_58":-5,"_59":-5,"_60":-5,"_61":-5,"_62":63},"id","7c20608b-f906-406e-b6a0-048f2f4525eb","branchId","18439a77-9162-403a-ad4d-e69e4496f0d9","createdAt",["D",1788851537264],"version",2,"orgId","5a10edca-919b-4a78-babb-71908f69af93","parentId","5b1b1cf5-a80d-4537-9888-9de8a672c116","incomingCommitId","aiChatMessageId","aiChatThreadId","aiChatThreadUserId","aiChatThreadTitle","source","mcp","clientLabel","ChatGPT","user",{"_34":71,"_42":43,"_11":12,"_72":73},{"_65":66,"_13":67,"_68":69,"_70":24},"pull","merge","revert","multiple","commits",[64],{"_34":35,"_36":37,"_38":39,"_40":41,"_42":43,"_44":45,"_46":-5,"_47":-5,"_48":-5,"_49":-5,"_50":-5,"_51":52,"_53":54,"_55":56,"_21":57,"_58":-5,"_59":-5,"_60":-5},"fileId","01a07fdc-4571-76ba-9009-e9aa49b6faf9","contract.ts","fileType","script","deleted","b0a8da26-58e7-4d19-8b5c-eedf487df9a9","avatar","https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ2l0aHViL2ltZ18yVHpab25kTlBTM3M3WmpCa3NMSTd5akVwWksuanBlZyJ9","d0133c57-bcab-4893-b926-b80db66cffe4",["D",1788852023161],8,"bb2a9894-e559-48f7-8b7d-86f8b113704a",{"_34":71,"_42":43,"_11":12,"_72":73},{"_65":66,"_13":67,"_68":69,"_70":24},[81],{"_34":74,"_36":37,"_38":75,"_40":76,"_42":43,"_44":77,"_46":-5,"_47":-5,"_48":-5,"_49":-5,"_50":-5,"_51":52,"_53":54,"_55":78,"_21":79,"_58":-5,"_59":-5,"_60":-5},"fec7b7a8-8753-496d-a1fb-a11b5fa0cf6e",["D",1789077285831],12,"4caad7cb-551d-4f88-8620-2dc69134660d","1b3309e5-96c9-4256-9f10-402d1bb5c10a","Claude",{"_34":71,"_42":43,"_11":12,"_72":73},{"_65":66,"_13":67,"_68":69,"_70":24},{"_36":93,"_13":94,"_40":95,"_96":-5},[92],{"_34":82,"_36":37,"_38":83,"_40":84,"_42":43,"_44":85,"_46":86,"_47":-5,"_48":-5,"_49":-5,"_50":-5,"_51":52,"_53":87,"_55":88,"_21":89,"_58":-5,"_59":90,"_60":-5},"b8c2c5c5-60bc-4d6a-9ba3-e0e4d47d7ade","lifecycle-window",13,"deletedAt","deletedAtVersion","eb040b9b-c2e1-4e49-ab5b-059a85d1d61b",["D",1788851529508],"legacyEnvVars","privacy","public","httpPrivacy","description","Shared temporal source protocol and authoring SDK","imageUrl","pinnedFileId","pinPreview","pinMigrated","screenshotVersion","likeCount","tursoName","tursoHostname","tursoMeasuredAt","pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm",{"_11":12,"_144":73},"org",{"_11":12,"_140":-5,"_72":73,"_30":71,"_141":142,"_143":24},"branch",{"_40":131,"_13":16,"_34":37,"_132":98,"_133":-5,"_134":-5,"_135":-5,"_136":-5,"_137":-5,"_138":14,"_139":12},"isOwned",16,"projectId","forkedBranchId","forkedBranchVersion","forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","displayName","tier","free","canRestrictVals","profileImageUrl","adoptOrgId",{"_34":98,"_13":14,"_38":282,"_96":-5,"_100":24,"_101":102,"_103":102,"_104":105,"_106":-5,"_30":71,"_107":-5,"_108":24,"_109":-5,"_110":-5,"_111":26,"_42":43,"_112":-5,"_113":-5,"_114":-5,"_115":-5,"_116":117,"_118":117,"_119":120,"_121":120,"_122":120,"_123":117,"_124":117,"_55":283,"_126":284,"_128":285,"_130":24},"tree",[187,189,195,197,198],"files",[187,188,189,190,191,192,193,194,195,196,197,198],"counts",{"_177":26,"_178":41,"_179":26,"_180":181,"_182":183},"contents",[],{"_34":166,"_13":67,"_65":66,"_44":167,"_36":37,"_168":84,"_169":170,"_38":171,"_40":41,"_68":69,"_172":173,"_70":24,"_174":-5,"_17":175},"upstreamProject","upstreamBranch","emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},"d3ca80ab-fd3f-48bd-971a-02398cda1e37","01a07fdc-4570-7068-b849-a2f0d645edd4","branchVersion","latest",true,["D",1789077285831],"content","// Temporal item contract, result helpers and guards shared by every source.\n// Runtime imports must stay inside sdk/; tools/sdk-check.ts enforces the boundary.\n// Source authors start at ../README.md and import ../mod.ts.\n\nexport const PROTOCOL_VERSION = 1;\n\n// The longest window `items()` will accept. Its real job is catching a\n// mixed-unit bug — one bound in seconds, the other in milliseconds — which\n// neither bound's own magnitude check can see, because a millisecond value is\n// still a plausible far-future second value.\nexport const MAX_ITEM_SPAN_SECONDS = 30 * 24 * 60 * 60;\n\n// The one payload shape every source produces, whatever it is a source of.\n// There is no away/home, no score, no domain — a source decides what to *say*\n// and the client renders these fields blind.\n//\n// `caption: null` is a protocol value, not an absent field: it tells the\n// client to format `startsAt` itself as a local time. A source that wants no\n// caption at all still sends null — and a source whose events are only\n// day-precise must NOT send null, or the client will render a fabricated\n// clock time (see ../README.md, \"Day-granular events\").\n//\n// An item is a WINDOW, not an instant: `[startsAt, expiresAt)`. Both bounds\n// are required and `expiresAt` must be strictly greater, so every consumer can\n// derive `phase()` from the clock alone with no further reads. A genuinely\n// instantaneous event publishes a one-second window rather than omitting the\n// bound; a nullable expiry would classify as already-expired under `now >\n// null` and vanish from `WHERE expires_at > :now`, both silently.\n//\n// `expiresAt` is an ESTIMATE and is never displayed. Sources without live\n// ingest publish a typical duration; a longer-than-typical event reads as\n// expired while still running, which is bounded and acceptable. Rendering it\n// as a fact (\"ends at 4:15 PM\") is not.\n//\n// Both are Unix EPOCH SECONDS, not milliseconds. This is the single most\n// common implementation mistake: sending ms decodes on the client as a date\n// ~57,000 years out, and no type-level check catches it because both are\n// numbers. `items()` below rejects values too large to be a plausible\n// second-precision time, and rejects an implausible span — together those\n// catch the mixed-unit case, but not two consistently-wrong bounds.\nexport type Item = {\n id: string;\n mainText: string;\n subText: string;\n caption: string | null;\n emphasized: boolean;\n startsAt: number;\n expiresAt: number;\n /**\n * @deprecated Transitional duplicate of `startsAt` for consumers that\n * predate the window. Sources emit it during the migration window only;\n * drop it once no old client remains.\n */\n timestamp?: number;\n};\n\n// Where an item sits relative to the clock. The vocabulary is deliberately\n// domain-free: the protocol says `current`, and the SOURCE decides whether\n// that reads as \"LIVE\" or \"PEAK\". These values are state, not display text,\n// and must never reach a user.\nexport type Phase = \"upcoming\" | \"current\" | \"expired\";\n\n// The single derivation every consumer uses. Route phase decisions through\n// this rather than comparing bounds inline, so one definition of \"current\"\n// exists across the source, the parent and any future consumer.\nexport function phase(item: Pick, now: number): Phase {\n if (now < item.startsAt) return \"upcoming\";\n return now < item.expiresAt ? \"current\" : \"expired\";\n}\n\n// Builds a window from a start plus a duration the SOURCE owns. The SDK has\n// no domain model, so it will never supply the duration itself — pass a named\n// constant with a rationale, not a bare number.\n//\n// Throws rather than rejecting: a non-positive or non-finite duration is a bug\n// in the source, not a caller's bad input.\nexport function windowFrom(startsAt: number, durationSeconds: number): Pick {\n if (!Number.isFinite(startsAt)) throw new Error(\"windowFrom: startsAt must be finite\");\n if (!Number.isFinite(durationSeconds) || durationSeconds < 1) {\n throw new Error(\"windowFrom: durationSeconds must be at least 1 second\");\n }\n return { startsAt, expiresAt: startsAt + durationSeconds };\n}\n\nexport function record(value: unknown): value is Record {\n return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction instant(value: unknown): value is number {\n return typeof value === \"number\" && Number.isFinite(value) && Math.abs(value) <= 8640000000000;\n}\n\n// The gate every source's output passes through before it leaves the val.\n// serveSource applies this automatically, so an implementer cannot ship a\n// malformed item by forgetting to check: a failing read returns 502\n// invalid_source_output from this source rather than failing composition at\n// the parent, where nothing would name which source produced the bad item.\n//\n// `id` must be unique within one response and stable across polls of the same\n// underlying thing; the parent namespaces it per source, so it only has to be\n// unique here.\n//\n// The window rules are strict `>` and a bounded span. Strict, because an\n// accidental `expiresAt === startsAt` would reintroduce the zero-duration case\n// the required bound exists to eliminate; bounded, because a span outside\n// MAX_ITEM_SPAN_SECONDS almost always means one bound was written in\n// milliseconds.\nexport function items(value: unknown): value is Item[] {\n return Array.isArray(value) && value.every(v => record(v)\n && typeof v.id === \"string\" && v.id.length > 0\n && typeof v.mainText === \"string\" && typeof v.subText === \"string\"\n && (v.caption === null || typeof v.caption === \"string\")\n && typeof v.emphasized === \"boolean\"\n && instant(v.startsAt) && instant(v.expiresAt)\n && (v.expiresAt as number) > (v.startsAt as number)\n && (v.expiresAt as number) - (v.startsAt as number) <= MAX_ITEM_SPAN_SECONDS\n && (v.timestamp === undefined || instant(v.timestamp)))\n && new Set(value.map(v => v.id)).size === value.length;\n}\n\n// How a source hands a rejection back to the SDK instead of throwing. One\n// type for both settings parsing and write operations, so there is a single\n// failure idiom to learn.\n//\n// `error` becomes the protocol's error code verbatim, so it should be a\n// stable snake_case token the parent can branch on (\"unknown_selection\"), not\n// a sentence. `status` defaults to 400 — the codes worth overriding are 404\n// for a thing that does not exist and 422 for a well-formed request this\n// source will not perform.\n//\n// Returning a rejection is not the same as throwing: a throw is a bug and\n// surfaces as a 500, while a rejection is this source correctly refusing.\nexport type Result =\n | { ok: true; value: T }\n | { ok: false; error: string; status?: number };\n\nexport function accept(value: T): Result {\n return { ok: true, value };\n}\n\nexport function reject(error: string, status = 400): Result {\n return { ok: false, error, status };\n}\n","label",[176,67],"sdk","pulls","branches","forks","envVars",{"_184":26,"_186":26},"connections",{"_184":26,"_185":26},"count","unfilledCount","emptyCount",{"_34":277,"_13":276,"_65":271,"_44":-5,"_36":37,"_168":278,"_169":170,"_38":279,"_40":26,"_68":229,"_172":-5,"_70":24,"_174":-5,"_205":280,"_17":281},{"_34":268,"_13":269,"_65":270,"_44":271,"_36":37,"_168":131,"_169":170,"_38":272,"_40":41,"_68":69,"_172":273,"_70":24,"_174":-5,"_205":274,"_17":275},{"_34":264,"_13":176,"_65":167,"_44":-5,"_36":37,"_168":41,"_169":170,"_38":265,"_40":26,"_68":229,"_172":-5,"_70":24,"_174":-5,"_205":266,"_17":267},{"_34":257,"_13":209,"_65":258,"_44":167,"_36":37,"_168":259,"_169":170,"_38":260,"_40":203,"_68":21,"_172":261,"_70":24,"_174":-5,"_205":262,"_17":263},{"_34":166,"_13":67,"_65":66,"_44":167,"_36":37,"_168":84,"_169":170,"_38":254,"_40":41,"_68":69,"_172":173,"_70":24,"_174":-5,"_205":255,"_17":256},{"_34":246,"_13":247,"_65":248,"_44":167,"_36":37,"_168":249,"_169":170,"_38":250,"_40":203,"_68":69,"_172":251,"_70":24,"_174":-5,"_205":252,"_17":253},{"_34":239,"_13":240,"_65":241,"_44":167,"_36":37,"_168":84,"_169":170,"_38":242,"_40":41,"_68":69,"_172":243,"_70":24,"_174":-5,"_205":244,"_17":245},{"_34":232,"_13":233,"_65":234,"_44":167,"_36":37,"_168":41,"_169":170,"_38":235,"_40":26,"_68":21,"_172":236,"_70":24,"_174":-5,"_205":237,"_17":238},{"_34":227,"_13":226,"_65":220,"_44":-5,"_36":37,"_168":41,"_169":170,"_38":228,"_40":26,"_68":229,"_172":-5,"_70":24,"_174":-5,"_205":230,"_17":231},{"_34":217,"_13":218,"_65":219,"_44":220,"_36":37,"_168":84,"_169":170,"_38":221,"_40":222,"_68":69,"_172":223,"_70":24,"_174":-5,"_205":224,"_17":225},{"_34":208,"_13":209,"_65":210,"_44":-5,"_36":37,"_168":211,"_169":170,"_38":212,"_40":213,"_68":21,"_172":214,"_70":24,"_174":-5,"_205":215,"_17":216},{"_34":199,"_13":200,"_65":201,"_44":-5,"_36":37,"_168":84,"_169":170,"_38":202,"_40":203,"_68":69,"_172":204,"_70":24,"_174":-5,"_205":206,"_17":207},"d406172b-0fcb-491e-bc1b-70344328a036","mod.ts","9b489f52-ab54-11f1-89a4-1607ee4eb77e",["D",1789077285831],1,"// Public source-author API. Implementation lives in sdk/.\nexport {\n accept,\n items,\n MAX_ITEM_SPAN_SECONDS,\n phase,\n PROTOCOL_VERSION,\n record,\n reject,\n windowFrom,\n type Item,\n type Phase,\n type Result,\n} from \"./sdk/contract.ts\";\nexport { defineSource, type SourceDefinition, type ReadContext, type WriteHandler } from \"./sdk/defineSource.ts\";\nexport { serveSource } from \"./sdk/serve.ts\";\n","children",[],[200],"c0bf8bd5-b706-4705-8ce2-de017a5adaf6","README.md","07d62c66-ab55-11f1-9a00-1607ee4eb77e",15,["D",1789077310054],5,"# Source SDK\n\nOne definition and one HTTP mount. Import the public API from:\n\n```ts\nimport { accept, reject, defineSource, serveSource, type Item } from \"https://esm.town/v/plusjade/source-sdk@12-main/mod.ts\";\n```\n\nThis is shared code executed inside your source val, not another HTTP service.\nStorage, credentials, ingest, schedules and domain policy stay in your source.\nThe SDK runtime has no dependencies or load-time side effects.\n\n## Create a source\n\nCopy [examples/rpc.ts](examples/rpc.ts) into a new val as an **HTTP** file.\nSet that val's `SOURCE_TOKEN` environment variable, choose a unique source key,\nand replace the example item with your data. No install, build, import map or\nSDK directory is needed. This complete starter uses empty settings, supported\nby the parent's browser form:\n\n```ts\n// Starter mount: create this as an HTTP file in your own source val.\nimport { accept, reject, defineSource, serveSource, windowFrom } from \"https://esm.town/v/plusjade/source-sdk@12-main/mod.ts\";\n\n// Your domain's typical duration, named and justified. The SDK will never\n// supply one — it has no idea what your events are.\nconst EXAMPLE_TYPICAL_EVENT_SECONDS = 2 * 60 * 60;\n\nconst source = defineSource({\n key: \"example\",\n settingsSchema: { type: \"object\", properties: {}, additionalProperties: false },\n parseSettings: (raw) =>\n Object.keys(raw).length === 0 ? accept(null) : reject(\"invalid_settings\"),\n read: async () => [{\n id: \"example-event\",\n mainText: \"Example event\",\n subText: \"Replace this with your source's data\",\n caption: null,\n emphasized: false,\n ...windowFrom(1798761600, EXAMPLE_TYPICAL_EVENT_SECONDS),\n }],\n});\n\nexport default function handler(req: Request): Promise | Response {\n const token = Deno.env.get(\"SOURCE_TOKEN\");\n if (!token) return Response.json({ error: \"RPC token not configured\" }, { status: 503 });\n if (req.headers.get(\"authorization\") !== `Bearer ${token}`) {\n return Response.json({ error: \"unauthorized\" }, { status: 401 });\n }\n return serveSource(source, req);\n}\n```\n\nThe example is stored here as a script so the SDK val exposes no HTTP endpoint.\nA larger source can put the definition in `mySource.ts` and keep authentication\nand `serveSource(mySource, req)` in `rpc.ts`; import from the same URL in both.\nSee [Moon](https://www.val.town/x/plusjade/source-moon) for that small split and\n[Women's FIBA](https://www.val.town/x/plusjade/source-wfiba) for storage-backed settings and ingestion.\n\nTo connect it to Clark View, register the HTTP endpoint obtained from Val Town,\nthe matching source key, protocol version 1, and a credential reference in the\nparent's source registry; configure the same bearer value independently in the\nparent and source. Assign that registered source to a device through the parent.\nDo not register this SDK val as a source.\n\nFor selectable settings, follow [the parent's supported form contract](sdk/settings-form.md).\nThe SDK publishes your schema; your `parseSettings` enforces it.\n\n## Public API\n\n| Export | Purpose |\n| --- | --- |\n| `defineSource`, `SourceDefinition` | Describe a source; infer/check parsed settings against its read handler. |\n| `serveSource(definition, request)` | Serve protocol v1 with request and item validation. |\n| `accept(value)`, `reject(code, status?)`, `Result` | Return validated input or an expected rejection. |\n| `Item`, `ReadContext`, `WriteHandler` | Types for items, caller context and optional writes. |\n| `record(value)`, `items(value)` | Guards for object payloads and item arrays; output guarding is automatic. |\n| `phase(item, now)`, `Phase` | Derive `upcoming \\| current \\| expired` from the clock. |\n| `windowFrom(startsAt, durationSeconds)` | Build `{startsAt, expiresAt}` from a duration you own. |\n| `PROTOCOL_VERSION`, `MAX_ITEM_SPAN_SECONDS` | The wire protocol version, currently 1; the widest span `items()` accepts. |\n\nImport only `mod.ts`; `sdk/` is implementation, not a second author API.\n\n## An item is a window, not an instant\n\nEvery item carries `startsAt` and `expiresAt`, both Unix **seconds**, both\nrequired, with `expiresAt` strictly greater. Together they let any consumer\nderive lifecycle from the clock alone — no re-read, no ingest, no polling:\n\n```ts\nphase(item, Math.floor(Date.now() / 1000)); // \"upcoming\" | \"current\" | \"expired\"\n```\n\nThree rules that are easy to get wrong:\n\n1. **`expiresAt` is an estimate, and never displayed.** Publish your domain's\n typical duration; a longer-than-typical event reading as expired while it\n is still running is the accepted cost of needing no live ingest. It exists\n for phase and refresh scheduling. Never render it as \"ends at 4:15 PM\".\n2. **An instantaneous event publishes a one-second window**, not a missing or\n null bound. `now > null` is `now > 0` in JS, and `expires_at > :now` is\n never true for NULL in SQL — a nullable expiry classifies a moment as\n permanently expired, silently, in both languages. One second is a fiction\n too, but it degrades predictably instead of corrupting. If such an event\n should later read as current for an hour, publish that hour.\n3. **`phase()` values are state, not words.** The protocol says `current`;\n *you* decide whether that renders as \"LIVE\" or \"PEAK\". Never put a phase\n value in `mainText`, `subText` or `caption`.\n\n### Day-granular events\n\nSome events are only precise to a day (\"pay this bill\"). Any clock time you\ninvent for one is fabricated, and rule 1 above applies to it too:\n\n- **Span the real unit.** The window is the whole local day —\n `[day start, next day start)` — not a made-up instant plus a duration.\n- **Send a non-null `caption`** (`\"DUE\"`, `\"TODAY\"`). `caption: null` is a\n protocol instruction meaning *\"client, format the start time yourself\"*, and\n the client will render a clock time. The day label it derives is honest at\n day granularity; the clock time is not.\n\n## SDK changes and source upgrades\n\nThe import above pins the entire val to **main snapshot 12**, including relative\ndependencies. This is an implementation revision, not a protocol version.\nSnapshot 12 is the first with the `startsAt`/`expiresAt` window; snapshot 3 is\nthe last single-`timestamp` runtime. Later documentation and example edits do\nnot require sources to change their runtime pin.\n\nKeep a source's SDK imports on the same snapshot. To upgrade, test an SDK branch,\nmerge once, obtain its new immutable module URL, replace the old URL in a source\nbranch, run that source's checks, then merge. Unversioned `source-sdk/mod.ts`\ntracks main; avoid it in deployed sources while the SDK is evolving.\nThere is no separate release registry or compatibility adapter.\n\n## Maintainer map and checks\n\n- `mod.ts`: explicit public exports.\n- `sdk/contract.ts`: item guard and results.\n- `sdk/defineSource.ts`: source author types.\n- `sdk/serve.ts`: protocol implementation.\n- `tools/sdk-check.ts`: shared boundary and protocol conformance checks.\n- `examples/rpc.ts`: complete creator starting point.\n\nRun `tools/sdk-check.ts` in this val after runtime edits. It imports the public\nentrypoint, uses a storage-free fixture, and checks the implementation imports\nstay within `sdk/`. Source-specific storage and HTTP checks stay in each source.\nThe runtime must not import a source, Val Town storage, environment helpers or\nthird-party packages. Authentication belongs in the mount.\n\n## What the SDK does, so you don't\n\n- Routes `/v1/descriptor`, `/v1/validate-settings`, `/v1/read`, `/v1/write`, `/v1/publish`.\n- Validation-only requests call `parseSettings` without calling `read` or returning\n the parsed internal value. Keep `parseSettings` free of mutations.\n- `settingsSchema` may be an object or an async function returning one.\n- Parses and shape-checks the request body; rejects a wrong `protocolVersion`\n or a `sourceKey` that isn't yours.\n- Validates `context.utcOffsetSeconds` before your code sees it.\n- **Validates your output.** Items that break the contract — a duplicate `id`,\n an inverted or implausibly long window — never leave the val; the request fails 502\n `invalid_source_output` instead of failing composition at the parent, where\n nothing would say which source produced the bad item.\n- Derives `capabilities` from the definition, so what a source advertises\n cannot drift from what it implements.\n- Writes every response envelope, so no route can invent a new one.\n\n## What is yours\n\n- **Validating settings.** `settingsSchema` is published for the parent's UI;\n the SDK does not enforce it. The parent checks its supported form subset and\n posted values, then asks `parseSettings` to decide before saving. Reads also\n call `parseSettings` independently.\n- **Being total.** Reject unknown keys. A setting you silently ignore is a\n setting a caller thinks is working.\n- **Failing by returning, not throwing.** `reject(\"code\")` is this source\n correctly refusing, and the code reaches the parent verbatim — make it a\n stable snake_case token it can branch on, not a sentence. A throw is a bug\n and surfaces as a 500.\n- **Deciding what `null` means.** `utcOffsetSeconds: null` means the parent had\n no offset to forward. It does **not** mean UTC. Fall back to a zone you pick;\n treating it as 0 quietly moves every day boundary to Greenwich.\n\n## What is nobody's job here\n\nThese belong to the parent, and a source that does them will conflict with it:\n\n- Composition across sources, and namespacing ids (the parent prefixes yours).\n- Presentation: envelopes, eyebrows, section headers, empty-state copy.\n- Device or user identity — a source never learns who is asking.\nAuthentication belongs to each source's HTTP mount.\n\n## Three things that go wrong\n\n1. **Milliseconds in `startsAt` or `expiresAt`.** They are Unix *seconds*.\n Sending ms decodes on the client as a date ~57,000 years out, and nothing\n catches it: both are numbers, and a real ms value is not large enough to\n trip the magnitude check. The span rule catches only the *mixed* case, one\n bound in each unit — two consistently-wrong bounds pass. Pin it in a test.\n2. **An `id` that isn't stable.** It must be the same across polls of the same\n underlying thing, and unique within one response. An id containing \"now\"\n makes every poll look like new content.\n3. **Re-reading storage in `read`.** `parseSettings` may do I/O and hands its\n return value to `read` verbatim — load the snapshot there once, and pass it\n along. As a bonus the request is then resolved against one consistent\n snapshot rather than two.\n\n",[],[209],"8acd6c95-2616-4fda-b058-8f2e7eae3c5c","sdk-check.ts","01a07fdc-4571-76ba-9009-fc3e091cae54","01a07fdc-4571-76ba-9009-fa3c6e2258ea",["D",1789077285831],3,"// Shared SDK boundary and protocol conformance checks via the public entrypoint.\n// Uses in-memory fixtures; no source storage or production data is touched.\n\nimport { readFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport {\n accept,\n type Item,\n items,\n MAX_ITEM_SPAN_SECONDS,\n phase,\n reject,\n defineSource,\n type SourceDefinition,\n serveSource,\n windowFrom,\n} from \"../mod.ts\";\n\nfunction check(value: unknown, message: string): asserts value {\n if (!value) throw new Error(message);\n}\n\n// ---------------------------------------------------------------- boundary --\n\nconst SDK_FILES = [\"/sdk/contract.ts\", \"/sdk/defineSource.ts\", \"/sdk/serve.ts\"];\n\n// Words that mean this val in particular. The SDK may not know any of them.\n// (Checked against code only — sdk/README.md uses them in its examples, which\n// is exactly where domain vocabulary belongs.)\nconst DOMAIN_WORDS = [\"sport\", \"team\", \"game\", \"sleeper\", \"fiba\", \"catalog\", \"widget\", \"channel\"];\n\nfor (const path of SDK_FILES) {\n const code = await readFile(path, import.meta.url);\n\n // Every import must be relative and stay inside sdk/. This also rules out\n // remote imports, so the published SDK has zero dependencies — including on\n // Val Town's own std, which is what lets a source run somewhere else.\n for (const [, specifier] of code.matchAll(/(?:^|\\n)\\s*(?:import|export)[^;]*?from\\s+[\"']([^\"']+)[\"']/g)) {\n check(\n specifier.startsWith(\"./\") && !specifier.includes(\"..\"),\n `${path} imports outside sdk/: ${specifier}`,\n );\n }\n\n // Strip comments before the vocabulary scan: prose may say \"a catalog, say\"\n // while explaining what `options` is for. Identifiers may not.\n const source = code.replace(/\\/\\/[^\\n]*/g, \"\").replace(/\\/\\*[\\s\\S]*?\\*\\//g, \"\").toLowerCase();\n for (const word of DOMAIN_WORDS) {\n check(!source.includes(word), `${path} names this val's domain in code: \"${word}\"`);\n }\n}\n\n// ------------------------------------------------------------- conformance --\n\nconst fixture = defineSource<{ count: number }>({\n key: \"fixture\",\n // `temporal` deliberately omitted, to prove the descriptor defaults it.\n settingsSchema: {\n type: \"object\",\n properties: { count: { type: \"integer\" } },\n required: [\"count\"],\n additionalProperties: false,\n },\n parseSettings: (raw) =>\n typeof raw.count === \"number\" && Number.isInteger(raw.count) && raw.count >= 0\n ? accept({ count: raw.count })\n : reject(\"invalid_settings\"),\n read: ({ count }, context) =>\n Promise.resolve(Array.from({ length: count }, (_, i): Item => ({\n id: `fixture-${i}`,\n mainText: `Item ${i}`,\n // Echoed so the assertions below can prove the context reached the\n // source rather than being swallowed by the protocol layer.\n subText: String(context.utcOffsetSeconds),\n caption: null,\n emphasized: false,\n ...windowFrom(1788739200 + i, 3600),\n }))),\n writes: {\n echo: (payload) =>\n typeof payload.value === \"string\"\n ? accept({ echoed: payload.value })\n : reject(\"invalid_value\"),\n },\n});\n\n// A source that breaks the item contract, to prove the SDK catches it rather\n// than passing it to the parent: two items with the same id.\nconst brokenSource = defineSource({\n key: \"broken\",\n settingsSchema: {},\n parseSettings: () => accept(null),\n read: () =>\n Promise.resolve([0, 0].map((): Item => ({\n id: \"duplicate\",\n mainText: \"\",\n subText: \"\",\n caption: null,\n emphasized: false,\n startsAt: 1788739200,\n expiresAt: 1788742800,\n }))),\n});\n\n// A source that inverts its window, to prove the guard rejects it at the\n// source rather than letting an item that can never be `current` compose.\nconst invertedSource = defineSource({\n key: \"inverted\",\n settingsSchema: {},\n parseSettings: () => accept(null),\n read: () =>\n Promise.resolve([{\n id: \"inverted\",\n mainText: \"\",\n subText: \"\",\n caption: null,\n emphasized: false,\n startsAt: 1788739200,\n expiresAt: 1788739200,\n }] as Item[]),\n});\n\nconst BASE = { protocolVersion: 1, sourceKey: \"fixture\" };\n// deno-lint-ignore no-explicit-any -- the harness drives two differently-typed\n// definitions through one helper; serveSource's own generic is what's under test.\ntype Definition = SourceDefinition;\n\nfunction call(definition: Definition, path: string, body?: unknown, rawBody?: string) {\n const init: RequestInit = body !== undefined || rawBody !== undefined\n ? { method: \"POST\", body: rawBody ?? JSON.stringify(body) }\n : {};\n return serveSource(definition, new Request(\"https://fixture.invalid\" + path, init));\n}\nasync function status(definition: Definition, path: string, body?: unknown, rawBody?: string) {\n const response = await call(definition, path, body, rawBody);\n return { code: response.status, json: await response.json() };\n}\n\n// Descriptor: derived capabilities, defaulted temporal, absent options.\nconst descriptor = await (await call(fixture, \"/v1/descriptor\")).json();\ncheck(descriptor.sourceKey === \"fixture\" && descriptor.protocolVersion === 1, \"descriptor identity\");\ncheck(descriptor.temporal === true, \"temporal did not default to true\");\ncheck(!(\"options\" in descriptor), \"options published by a source that declares none\");\ncheck(\n JSON.stringify(descriptor.capabilities) === JSON.stringify({ read: true, validateSettings: true, write: [\"echo\"], publish: false }),\n \"capabilities not derived from the definition\",\n);\ncheck((await status(fixture, \"/v1/descriptor?sourceKey=other\")).code === 404, \"wrong key reached the descriptor\");\n\n// Validation does not read, write, or leak parseSettings' internal output.\nlet readCalls = 0;\nconst validationFixture = defineSource({\n key:\"validation\",\n settingsSchema: async () => ({type:\"object\",properties:{},additionalProperties:false}),\n parseSettings: (raw) => Object.keys(raw).length === 0 ? accept({privateContext:\"secret\"}) : reject(\"invalid_settings\"),\n read: async () => { readCalls++; return []; },\n});\nconst valid = await status(validationFixture,\"/v1/validate-settings\",{\n protocolVersion:1,sourceKey:\"validation\",settings:{},\n});\ncheck(valid.code === 200 && valid.json.ok === true && !(\"privateContext\" in valid.json) &&\n Object.keys(valid.json).length === 3 && readCalls === 0, \"validation-only boundary\");\ncheck((await status(validationFixture,\"/v1/validate-settings\",{\n protocolVersion:1,sourceKey:\"validation\",settings:{unknown:true},\n})).code === 400,\"validation rejected unknown settings\");\ncheck((await status(validationFixture,\"/v1/descriptor\")).json.settingsSchema.type === \"object\",\"dynamic schema\");\n\n// Read: the happy path, and that context and settings both arrive intact.\nconst read = await status(fixture, \"/v1/read\", {\n ...BASE,\n settings: { count: 3 },\n context: { utcOffsetSeconds: -25200 },\n});\ncheck(read.code === 200 && read.json.items.length === 3, \"read did not return the source's items\");\ncheck(read.json.items[0].subText === \"-25200\", \"context.utcOffsetSeconds did not reach the source\");\ncheck(read.json.sourceKey === \"fixture\", \"read envelope identity\");\n\nconst nullOffset = await status(fixture, \"/v1/read\", {\n ...BASE,\n settings: { count: 1 },\n context: { utcOffsetSeconds: null },\n});\n// null must arrive AS null. Coercing it to 0 here would silently move every\n// day boundary to UTC for callers the parent couldn't resolve.\ncheck(nullOffset.json.items[0].subText === \"null\", \"null offset was coerced before the source saw it\");\n\n// Read: the ways it is refused.\nconst badSettings = await status(fixture, \"/v1/read\", {\n ...BASE,\n settings: { count: \"x\" },\n context: { utcOffsetSeconds: 0 },\n});\ncheck(badSettings.code === 400 && badSettings.json.error === \"invalid_settings\", \"parseSettings rejection not surfaced\");\n// The offset guard runs BEFORE parseSettings, so an absent utcOffsetSeconds is\n// invalid_timezone and not the source's business. The parent always sends the\n// key (null when it has no value), so this only bites a hand-written request.\ncheck(\n (await status(fixture, \"/v1/read\", { ...BASE, settings: { count: 1 }, context: {} })).json.error === \"invalid_timezone\",\n \"absent offset silently accepted\",\n);\ncheck((await status(fixture, \"/v1/read\", { ...BASE, settings: { count: 1 } })).code === 400, \"missing context accepted\");\ncheck(\n (await status(fixture, \"/v1/read\", { ...BASE, settings: { count: 1 }, context: { utcOffsetSeconds: 86401 } }))\n .json.error === \"invalid_timezone\",\n \"out-of-range offset accepted\",\n);\ncheck((await status(fixture, \"/v1/read\", { ...BASE, protocolVersion: 2 })).json.error === \"unsupported_protocol\", \"protocol version\");\ncheck((await status(fixture, \"/v1/read\", undefined, \"{not json\")).json.error === \"invalid_json\", \"malformed json\");\ncheck((await status(fixture, \"/v1/read\", [])).json.error === \"invalid_body\", \"array body accepted\");\ncheck((await status(fixture, \"/v1/read\", { ...BASE, sourceKey: \"other\" })).code === 404, \"foreign sourceKey\");\n\n// The output guard: a source that breaks the contract fails here, not at the\n// parent.\nconst broken = await status(\n brokenSource,\n \"/v1/read\",\n { protocolVersion: 1, sourceKey: \"broken\", settings: {}, context: { utcOffsetSeconds: 0 } },\n);\ncheck(broken.code === 502 && broken.json.error === \"invalid_source_output\", \"duplicate ids escaped the source\");\n\nconst inverted = await status(\n invertedSource,\n \"/v1/read\",\n { protocolVersion: 1, sourceKey: \"inverted\", settings: {}, context: { utcOffsetSeconds: 0 } },\n);\ncheck(inverted.code === 502, \"a zero-length window escaped the source\");\n\n// ------------------------------------------------------------- the window --\n\nconst START = 1788739200;\nconst base = { id: \"w\", mainText: \"\", subText: \"\", caption: null, emphasized: false };\n\ncheck(items([{ ...base, startsAt: START, expiresAt: START + 1 }]), \"a one-second window was rejected\");\ncheck(!items([{ ...base, startsAt: START, expiresAt: START }]), \"expiresAt === startsAt accepted\");\ncheck(!items([{ ...base, startsAt: START, expiresAt: START - 1 }]), \"an inverted window accepted\");\ncheck(!items([{ ...base, startsAt: START }]), \"a missing expiresAt accepted\");\ncheck(!items([{ ...base, startsAt: START, expiresAt: null }]), \"a null expiresAt accepted\");\n// The mixed-unit case the span rule exists for: seconds start, ms expiry.\ncheck(!items([{ ...base, startsAt: START, expiresAt: START * 1000 }]), \"a millisecond expiresAt accepted\");\ncheck(\n !items([{ ...base, startsAt: START, expiresAt: START + MAX_ITEM_SPAN_SECONDS + 1 }]),\n \"an implausible span accepted\",\n);\ncheck(\n items([{ ...base, startsAt: START, expiresAt: START + 3600, timestamp: START }]),\n \"the transitional legacy field was rejected\",\n);\n\n// An instantaneous event is `current` for exactly its one second and at no\n// other sampled instant — the degenerate-but-predictable behavior the\n// one-second sentinel is chosen for.\nconst moment = { startsAt: START, expiresAt: START + 1 };\ncheck(phase(moment, START - 1) === \"upcoming\", \"instant before start\");\ncheck(phase(moment, START) === \"current\", \"an instant is not current at its own start\");\ncheck(phase(moment, START + 1) === \"expired\", \"an instant stayed current past its window\");\ncheck(phase(moment, START + 86400) === \"expired\", \"instant long after\");\n\nconst window = { startsAt: START, expiresAt: START + 3600 };\ncheck(phase(window, START - 1) === \"upcoming\", \"phase before start\");\ncheck(phase(window, START) === \"current\", \"phase at start\");\ncheck(phase(window, START + 3599) === \"current\", \"phase inside window\");\ncheck(phase(window, START + 3600) === \"expired\", \"phase at expiry\");\n\ncheck(JSON.stringify(windowFrom(START, 60)) === JSON.stringify({ startsAt: START, expiresAt: START + 60 }), \"windowFrom\");\nlet threw = false;\ntry { windowFrom(START, 0); } catch { threw = true; }\ncheck(threw, \"windowFrom accepted a zero duration\");\n\n// Writes.\nconst echo = await status(fixture, \"/v1/write\", { ...BASE, operation: \"echo\", payload: { value: \"hi\" } });\ncheck(echo.code === 200 && echo.json.ok === true && echo.json.result.echoed === \"hi\", \"write did not run\");\ncheck(\n (await status(fixture, \"/v1/write\", { ...BASE, operation: \"echo\", payload: { value: 1 } })).json.error === \"invalid_value\",\n \"write rejection not surfaced\",\n);\ncheck((await status(fixture, \"/v1/write\", { ...BASE, operation: \"nope\", payload: {} })).code === 422, \"unknown operation\");\n// Object.prototype must not be reachable as an operation.\ncheck((await status(fixture, \"/v1/write\", { ...BASE, operation: \"toString\", payload: {} })).code === 422, \"prototype method invoked as an operation\");\ncheck((await status(fixture, \"/v1/write\", { ...BASE, operation: \"echo\", payload: \"x\" })).json.error === \"invalid_payload\", \"non-object payload accepted\");\ncheck(\n (await status(brokenSource, \"/v1/write\", { protocolVersion: 1, sourceKey: \"broken\", operation: \"echo\", payload: {} })).code === 422,\n \"a source with no writes accepted one\",\n);\n\n// Reserved and unknown routes.\ncheck((await status(fixture, \"/v1/publish\", BASE)).code === 501, \"publish stub\");\ncheck((await status(fixture, \"/v1/nope\", BASE)).json.error === \"not_found\", \"unknown route\");\n\nconsole.log(`PASS: sdk/ imports nothing outside itself and names no domain concept; serveSource conforms for a fixture source with no storage.`);\n",[],[226,218],"tools","839c9b46-fd78-49cd-94d9-5e41ff804734",["D",1788851537264],"directory",[196],[226],"ce5b4d7f-0773-43be-9819-6d6a902870c7","settings-form.md","01a07fdc-4571-76ba-9009-f7fa4b177f79",["D",1788851537264],"# Source settings form contract\n\nThe parent renders source settings from authenticated `GET /v1/descriptor?sourceKey=...`.\nIt checks protocol/source identity, `temporal:true`, and\n`capabilities.validateSettings:true`. The live schema is authoritative for the\nform; stored registry schema snapshots are not used for editing.\n\n## Supported JSON Schema subset\n\nThe root is `{type:\"object\",properties:{...},additionalProperties:false}`.\nAn optional `required` array names declared properties. Each property has a\n`title`, optional `description`, and one of these shapes:\n\n- Boolean: `{type:\"boolean\",title:\"Show alerts\",default:false}`.\n- Multiple choices: `{type:\"array\",title:\"Locations\",default:[],uniqueItems:true,\n items:{type:\"string\",oneOf:[{const:\"west\",title:\"West\",\"x-group\":\"Regions\"}]}}`.\n\n`x-group` is the only UI extension. Choice values are stable strings;\ntitles and optional groups are display text. Declaration order determines form\norder. Defaults apply when displaying a field with no saved value. Empty\n`properties` means no settings. Field names start with a letter and contain\nonly letters, digits, and underscores; prototype-related names are rejected.\n\nUnsupported property types or constraints fail closed, with no save form.\nThis is deliberately not a general JSON Schema renderer. No nested objects,\nfree text, numbers, conditional fields, pagination, or source-supplied HTML/JS.\nAll labels are escaped by React. Legacy descriptor `options` is not consumed:\nthe choice-to-property binding is inside `settingsSchema`.\n\nA source may provide a static schema or an async `settingsSchema()` function.\nSports builds choices from its catalog in one descriptor request. Moon publishes\nthe empty object schema. No source data tables need changing.\n\n## Saving\n\nThe form includes a fingerprint of the rendered fields. The parent reloads the\ndescriptor on POST and rejects a changed fingerprint with 409; it does not\nsilently interpret an old form against new controls or choices.\n\nThe parent decodes only declared fields. Unchecked booleans become false and\nunselected arrays become []; defaults do not override an intentional clearing.\nUnknown fields, duplicate values, and unavailable choices are rejected.\nPreviously saved choices that disappear remain visible as checked unavailable\nvalues, requiring explicit removal.\n\nBefore persisting, the parent sends\n`POST /v1/validate-settings` with\n`{protocolVersion:1,sourceKey,settings}`.\nThe SDK invokes the same `parseSettings` used by reads and returns only\n`{protocolVersion:1,sourceKey,ok:true}`. It does not call `read`, perform writes,\nor expose parsed internal context. Implementers must keep `parseSettings`\nfree of mutation. Validation remains source-authoritative on every feed read,\nsince data/choices may change after a settings save.\n\nSource validation errors retain their stable error code. Unavailability returns\n502, invalid settings 422, and stale forms 409. None changes the assignment.\nSuccessful saves persist the original wire settings, then use the existing\ndevice notification path.\n\n## Scope and remaining coupling\n\nDevice settings routes and rendering have no source-kind dispatch, field-name\nknowledge, or sports catalog import. Another source supporting this profile\nneeds only a registered pointer and its descriptor/validation/read implementation.\n\nPrototype starter-feed defaults and operator ingestion/catalog/coverage adapters\nstill refer to Sports/Moon instance IDs. Removing those is separate from settings\nforms. Immutable releases, descriptor caching, schema migrations, and agent ACLs\nremain deferred.\n",[],[176,233],"e4acb9f0-8695-4bf5-addf-73805d433173","serve.ts","01a07fdc-4571-76ba-9009-f28dbdde6525",["D",1789077285831],"// Protocol v1 routing, envelopes and validation for a source definition.\n// Authentication belongs to the source's HTTP mount; this module performs no I/O.\n\nimport { items, PROTOCOL_VERSION, record } from \"./contract.ts\";\nimport type { SourceDefinition } from \"./defineSource.ts\";\n\n// Every response the protocol emits carries protocolVersion, and every\n// failure carries `ok:false` plus a code. Kept as two helpers so no route can\n// invent a third envelope shape.\nfunction fail(error: string, status = 400): Response {\n return Response.json({ protocolVersion: PROTOCOL_VERSION, ok: false, error }, { status });\n}\n\nexport async function serveSource(\n definition: SourceDefinition,\n req: Request,\n): Promise {\n const url = new URL(req.url);\n\n let body: Record = {};\n if (req.method === \"POST\") {\n try {\n const raw = await req.json();\n if (!record(raw)) return fail(\"invalid_body\");\n body = raw;\n } catch {\n return fail(\"invalid_json\");\n }\n if (body.protocolVersion !== PROTOCOL_VERSION) return fail(\"unsupported_protocol\");\n }\n\n // Identity is checked before routing, so a request addressed to the wrong\n // source is a 404 on every path — including /v1/publish. A val that mounts\n // several definitions dispatches on this key.\n const key = req.method === \"GET\" ? url.searchParams.get(\"sourceKey\") ?? definition.key : body.sourceKey;\n if (key !== definition.key) return fail(\"unknown_source\", 404);\n\n if (req.method === \"GET\" && url.pathname === \"/v1/descriptor\") {\n return Response.json({\n protocolVersion: PROTOCOL_VERSION,\n sourceKey: definition.key,\n temporal: definition.temporal ?? true,\n settingsSchema: typeof definition.settingsSchema === \"function\"\n ? await definition.settingsSchema() : definition.settingsSchema,\n ...(definition.options ? { options: await definition.options() } : {}),\n // Derived, never declared: capabilities are read off the definition, so\n // a source cannot advertise a write it doesn't implement or hide one it\n // does.\n capabilities: {\n read: true,\n validateSettings: true,\n write: Object.keys(definition.writes ?? {}),\n publish: false,\n },\n });\n }\n\n if (req.method === \"POST\" && url.pathname === \"/v1/validate-settings\") {\n if (!record(body.settings)) return fail(\"invalid_settings\");\n const parsed = await definition.parseSettings(body.settings);\n if (!parsed.ok) return fail(parsed.error, parsed.status ?? 400);\n // Parsed values can contain private implementation context. Never export them.\n return Response.json({ protocolVersion: PROTOCOL_VERSION, sourceKey: definition.key, ok: true },\n { headers: { \"cache-control\": \"no-store\" } });\n }\n\n if (req.method === \"POST\" && url.pathname === \"/v1/read\") {\n if (!record(body.settings) || !record(body.context)) return fail(\"settings_and_context_required\");\n // The offset is protocol-level, so it is checked here rather than by each\n // source. This is the wide guard — a source's own fallback narrows it\n // further (see ReadContext).\n const tz = body.context.utcOffsetSeconds;\n if (tz !== null && (typeof tz !== \"number\" || !Number.isInteger(tz) || Math.abs(tz) > 86400)) {\n return fail(\"invalid_timezone\");\n }\n const parsed = await definition.parseSettings(body.settings);\n if (!parsed.ok) return fail(parsed.error, parsed.status ?? 400);\n\n const produced = await definition.read(parsed.value, { utcOffsetSeconds: tz as number | null });\n // Guarding the source's own output, not a remote's: a duplicate id or an\n // inverted window is rejected here rather than at the parent, where\n // the whole composition would fail without naming which source produced\n // it. 502 and not 500 — the source answered, the answer was unusable.\n if (!items(produced)) return fail(\"invalid_source_output\", 502);\n return Response.json(\n { protocolVersion: PROTOCOL_VERSION, sourceKey: definition.key, items: produced },\n { headers: { \"cache-control\": \"no-store\" } },\n );\n }\n\n if (req.method === \"POST\" && url.pathname === \"/v1/write\") {\n if (!record(body.payload)) return fail(\"invalid_payload\");\n // Object.hasOwn, not a plain lookup: `writes` is an object literal, so\n // `operation: \"toString\"` would otherwise resolve to Object.prototype's\n // method and get called with the payload.\n const writes = definition.writes ?? {};\n const operation = typeof body.operation === \"string\" ? body.operation : \"\";\n if (!Object.hasOwn(writes, operation)) return fail(\"unsupported_operation\", 422);\n const handler = writes[operation];\n const outcome = await handler(body.payload);\n if (!outcome.ok) return fail(outcome.error, outcome.status ?? 400);\n return Response.json({\n protocolVersion: PROTOCOL_VERSION,\n sourceKey: definition.key,\n ok: true,\n result: outcome.value,\n });\n }\n\n // Reserved rather than absent: the parent already knows the route, and a\n // 501 tells it \"not yet\" where a 404 would say \"never\".\n if (url.pathname === \"/v1/publish\") return fail(\"not_implemented\", 501);\n return fail(\"not_found\", 404);\n}\n",[],[176,240],"39a39075-4d46-4bfb-bae6-30fbdc713ce2","defineSource.ts","01a07fdc-4571-76ba-9009-ec81b7693068",9,["D",1788852027732],"// A source definition connects parsed settings to reads and optional writes.\n// serveSource exposes it over protocol v1; authors import these types via mod.ts.\n\nimport type { Item, Result } from \"./contract.ts\";\n\n// Everything the parent forwards about the caller, which is deliberately\n// almost nothing: no device identity, no user id, no presentation. A source\n// gets a timezone offset and the settings that caller chose, and that is the\n// whole input surface.\n//\n// `utcOffsetSeconds: null` means the parent had no offset to forward. It does\n// NOT mean UTC, and treating it as UTC is a bug: it silently shifts every\n// day boundary to Greenwich for callers the parent couldn't resolve. Fall\n// back to a default the source picks.\nexport type ReadContext = { utcOffsetSeconds: number | null };\n\n// A write handler. The SDK has already checked that `payload` is a JSON\n// object; validating its contents is the operation's own job, because only it\n// knows the shape. Return `reject(\"...\")` for bad input rather than throwing.\nexport type WriteHandler = (\n payload: Record,\n) => Promise> | Result;\n\nexport type SourceDefinition = {\n // The protocol `sourceKey`. The parent addresses this source by it and the\n // SDK rejects any request naming a different one.\n key: string;\n\n // Whether items carry meaningful times. Advertised in the descriptor;\n // defaults to true, which is the only shape v1's Item can express.\n temporal?: boolean;\n\n // JSON Schema for `settings`, published in the descriptor so the parent can\n // build a settings UI without knowing what this source is. It is\n // DOCUMENTATION, not enforcement — the SDK does not validate against it.\n // parseSettings is what actually decides.\n settingsSchema: Record | (() => Promise> | Record);\n\n // The choices a caller can pick from, published alongside the schema — a\n // catalog, a list of channels, whatever this source's settings reference.\n // Called on every descriptor request, so it may hit storage. Omit it for a\n // source whose settings are free-form.\n options?: () => Promise | unknown;\n\n // Raw `settings` in, whatever `read` needs out. This is the ONLY place a\n // source validates caller input, and it must be total: reject anything not\n // recognized, including unknown keys.\n //\n // It may do I/O, and that is a feature — it is where to load a snapshot\n // that both validation and the read itself need (a catalog, say), so the\n // request pays for it once. Whatever it returns is handed to `read`\n // verbatim, so the returned type is free to be richer than the wire\n // settings.\n parseSettings: (\n raw: Record,\n ) => Promise> | Result;\n\n // The source itself. Parsed settings in, items out. Anything it returns is\n // validated against the item contract before it leaves the val, so this can\n // return its natural output and let the SDK be the gate.\n read: (settings: Settings, context: ReadContext) => Promise;\n\n // Named side effects the parent can invoke, if this source has any. The\n // keys become the protocol's `operation` values and the descriptor's\n // advertised write capabilities — declared once, so what a source says it\n // can do cannot drift from what it does.\n writes?: Record;\n};\n\n// Identity function. It exists purely so `Settings` is inferred from\n// parseSettings and checked against read's parameter at the definition site,\n// where the mismatch is legible, instead of at the serveSource call.\nexport function defineSource(\n definition: SourceDefinition,\n): SourceDefinition {\n return definition;\n}\n",[],[176,247],["D",1789077285831],[],[176,67],"3081f974-7ce2-41a2-bf07-84a6525ebedb","01a07fdc-4570-7068-b849-a4647819a677",6,["D",1788851717288],"# SDK implementation\n\nStart with the [public API and source-creator guide](../README.md).\nImport `mod.ts`; these three modules are internal implementation.\nThey have no external dependencies. Run `tools/sdk-check.ts` after changes.\n",[],[176,209],"7bed7229-c5ed-4109-972f-478ea07da481",["D",1788851537264],[190,191,192,193,194],[176],"4df74f47-21fb-4739-934d-00a5b76ee67b","rpc.ts","04f32d8c-ab55-11f1-a4a0-1607ee4eb77e","0af64ad4-4d7d-480c-ad2f-797b3c340d14",["D",1789077313013],"// Starter mount: create this as an HTTP file in your own source val.\nimport { accept, reject, defineSource, serveSource, windowFrom } from \"https://esm.town/v/plusjade/source-sdk@12-main/mod.ts\";\n\n// How long one of this source's events stays current. The duration is the\n// SOURCE's to decide — the SDK has no domain model and will never supply one.\n// Name it and say why, so the next reader can judge the estimate.\nconst EXAMPLE_TYPICAL_EVENT_SECONDS = 2 * 60 * 60;\n\nconst source = defineSource({\n key: \"example\",\n settingsSchema: { type: \"object\", properties: {}, additionalProperties: false },\n parseSettings: (raw) =>\n Object.keys(raw).length === 0 ? accept(null) : reject(\"invalid_settings\"),\n read: async () => [{\n id: \"example-event\",\n mainText: \"Example event\",\n subText: \"Replace this with your source's data\",\n caption: null,\n emphasized: false,\n ...windowFrom(1798761600, EXAMPLE_TYPICAL_EVENT_SECONDS),\n }],\n});\n\nexport default function handler(req: Request): Promise | Response {\n const token = Deno.env.get(\"SOURCE_TOKEN\");\n if (!token) return Response.json({ error: \"RPC token not configured\" }, { status: 503 });\n if (req.headers.get(\"authorization\") !== `Bearer ${token}`) {\n return Response.json({ error: \"unauthorized\" }, { status: 401 });\n }\n return serveSource(source, req);\n}\n",[],[276,269],"examples","59189930-111b-4352-9c5d-b132d21904b3",4,["D",1788851706857],[188],[276],["D",1788851529508],{"_11":12,"_144":73},{"_11":12,"_140":-5,"_72":73,"_30":71,"_141":142,"_143":24},{"_40":131,"_13":16,"_34":37,"_132":98,"_133":-5,"_134":-5,"_135":-5,"_136":-5,"_137":-5,"_138":14,"_139":12},"ctx",{"_55":-5,"_163":319,"_320":321,"_322":323,"_324":24,"_325":24,"_326":24,"_327":170,"_328":-5,"_329":-7,"_330":-7,"_331":26,"_332":24,"_333":24,"_334":-5,"_335":24,"_336":24,"_337":24,"_338":-5},"ENV",{"_290":291,"_292":293,"_294":16,"_295":296,"_297":298,"_299":300,"_301":302,"_303":304,"_305":306,"_307":308,"_309":310,"_311":312,"_313":314,"_315":316,"_317":318},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

History · contract.ts