[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_253":254,"_255":256},"routes/_app.x.$handle.$name",{"_102":101,"_32":45,"_110":90,"_27":111,"_13":14,"_112":-5,"_11":113,"_114":115,"_116":117,"_118":119,"_120":121,"_20":-5,"_122":-5,"_123":124,"_125":49,"_126":127,"_128":25,"_129":-5,"_130":-5,"_131":132},"routes/_app.x.$handle.$name.branch.$branch.version.$version.diff",{"_11":12,"_13":14,"_15":16,"_17":-5,"_18":-5},"project",{"_43":44,"_32":45,"_38":46,"_47":-5,"_48":49,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":58,"_59":49,"_60":-5,"_61":-5,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":-5,"_73":74,"_75":74,"_76":77,"_78":77,"_79":77,"_80":74,"_81":74,"_82":83,"_84":85,"_86":87,"_88":49},"version",7,"changes",[19],"aiChatInfo","userId",{"_20":21,"_22":23,"_24":25,"_26":25,"_27":28,"_29":28},"file",{"_30":31,"_32":33,"_34":35,"_36":37,"_38":39,"_40":14,"_41":42,"_24":25},"previous",{"_30":31,"_32":33,"_34":35,"_36":37},"deleted",true,"deletedHere","path","sdk/defineSource.ts","latestPath","fileId","01a07fdc-87bd-7507-81cb-59c2672c629d","name","defineSource.ts","fileType","script","content","// The author-facing surface: everything an implementer writes, and nothing\n// they don't. A source is one object. serveSource turns it into the protocol.\n//\n// Part of the SDK — see sdk/contract.ts's header for the import rule.\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","createdAt",["D",1788851733884],"branchVersion","branchId","cab6db64-ac03-417d-bdee-4d167f06b8f9","id","e3ae15b8-4f32-4fb0-8b61-fc05375aa5cf","source-moon",["D",1788806619199],"deletedAt","legacyEnvVars",false,"privacy","public","httpPrivacy","description","Full-moon temporal source; no per-device settings","imageUrl","b0a8da26-58e7-4d19-8b5c-eedf487df9a9","pinnedFileId","2f093378-aaec-11f1-932c-1607ee4eb77e","pinPreview","pinMigrated","screenshotVersion","likeCount",0,"orgId","5a10edca-919b-4a78-babb-71908f69af93","tursoName","e3ae15b84f324fb08b61fc05375aa5cf","tursoHostname","e3ae15b84f324fb08b61fc05375aa5cf-val-town.aws-us-east-2.turso.io","tursoMeasuredAt",["D",1789501878689],"pinned","userPerm","r","valPerm","blobPerm","rw","emailPerm","sqlitePerm","projectPerm","telemetryPerm","user",{"_102":101,"_109":105},"org",{"_102":101,"_103":-5,"_104":105,"_18":56,"_106":107,"_108":49},"branch",{"_13":89,"_32":90,"_43":42,"_91":44,"_92":93,"_94":95,"_96":51,"_97":44,"_98":65,"_99":45,"_100":101},"isOwned",17,"shared-sdk","projectId","forkedBranchId","1a99f650-ba92-42d1-bb22-1cd93410c30e","forkedBranchVersion",9,"forkedProjectPrivacy","forkedProjectId","forkedProjectOrgId","projectName","userHandle","plusjade","handle","displayName","avatar","https://img.clerk.com/eyJ0eXBlIjoicHJveHkiLCJzcmMiOiJodHRwczovL2ltYWdlcy5jbGVyay5kZXYvb2F1dGhfZ2l0aHViL2ltZ18yVHpab25kTlBTM3M3WmpCa3NMSTd5akVwWksuanBlZyJ9","tier","free","canRestrictVals","profileImageUrl","branchName","","adoptOrgId",{"_43":44,"_32":45,"_38":248,"_47":-5,"_48":49,"_50":51,"_52":51,"_53":54,"_55":-5,"_18":56,"_57":58,"_59":49,"_60":-5,"_61":-5,"_62":63,"_64":65,"_66":67,"_68":69,"_70":249,"_72":-5,"_73":74,"_75":74,"_76":77,"_78":77,"_79":77,"_80":74,"_81":74,"_82":250,"_84":251,"_86":252,"_88":49},"tree",[200,204,205,206,207,208],"files",[200,201,202,203,204,205,206,207,208],"counts",{"_190":63,"_191":168,"_192":63,"_193":194,"_195":196},"contents",[140,141,142,143,144,145],"upstreamProject","upstreamBranch",{"_43":93,"_38":133,"_134":135,"_32":136,"_91":44,"_13":137,"_92":-5,"_94":-5,"_138":139,"_47":-5,"_88":49,"_50":51,"_100":101,"_64":65,"_99":45},"emptyEnvVars","flags",[],"hasHttpFiles","grants","orgs","customDomains",{},["D",1788806619199],"updatedAt",["D",1789077369770],"main",12,"lockfileKey","1789077370001-esm.town_v_plusjade_source-moon@12-main",{"_43":184,"_32":185,"_30":186,"_149":-5,"_41":42,"_40":153,"_151":25,"_38":187,"_13":63,"_34":188,"_36":-5,"_24":49,"_155":-5,"_27":189},{"_43":178,"_32":179,"_30":180,"_149":-5,"_41":42,"_40":153,"_151":49,"_38":181,"_13":63,"_34":20,"_36":182,"_24":49,"_155":-5,"_27":183},{"_43":172,"_32":173,"_30":174,"_149":-5,"_41":42,"_40":153,"_151":25,"_38":175,"_13":63,"_34":35,"_36":176,"_24":49,"_155":-5,"_27":177},{"_43":165,"_32":166,"_30":167,"_149":-5,"_41":42,"_40":168,"_151":25,"_38":169,"_13":153,"_34":35,"_36":170,"_24":49,"_155":-5,"_27":171},{"_43":157,"_32":158,"_30":159,"_149":-5,"_41":42,"_40":160,"_151":25,"_38":161,"_13":153,"_34":162,"_36":163,"_24":49,"_155":-5,"_27":164},{"_43":146,"_32":147,"_30":148,"_149":-5,"_41":42,"_40":150,"_151":49,"_38":152,"_13":153,"_34":35,"_36":154,"_24":49,"_155":-5,"_27":156},"9df880c6-8034-43d1-946c-9e7dcd487933","sdk-import-check.ts","b36b7f5a-ab54-11f1-9a71-1607ee4eb77e","parentId",3,"latest",["D",1788851601536],1,"// Read-only probe of the public SDK import and its resolved dependencies.\nimport { accept, defineSource, serveSource } from \"https://esm.town/v/plusjade/source-sdk@3-main/mod.ts\";\nconst source = defineSource({key:\"fixture\",settingsSchema:{type:\"object\",properties:{},additionalProperties:false},parseSettings:()=>accept(null),read:async()=>[]});\nconst response = await serveSource(source,new Request(\"https://fixture.invalid/v1/descriptor\"));\nif(response.status!==200) throw new Error(\"SDK import failed\");\nconst module = await fetch(\"https://esm.town/v/plusjade/source-sdk@3-main/mod.ts\", {headers:{\"user-agent\":\"Deno/2.0\"}});\nconsole.log(JSON.stringify({status:response.status,url:module.url,code:await module.text()}));\n","label",[147],"c3d0af43-9db6-4b37-9f78-bf1e8e7f023b","rpc.ts","01a07fdc-87bd-7507-81cb-75f78f359eb0",4,["D",1788851626537],"http","// Deployment authentication around the shared source protocol.\nimport { serveSource } from \"https://esm.town/v/plusjade/source-sdk@3-main/mod.ts\";\nimport moon from \"./moonSource.ts\";\nexport default function handler(req: Request): Promise | Response {\n const token = Deno.env.get(\"SOURCE_MOON_V1_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(moon, req);\n}\n",[158],"5577e82c-90ef-4b2b-91d6-ea7cfe2b4fac","moonSource.ts","01a07fdc-87bd-7507-81cb-7126268291ba",5,["D",1788851630609],"// Moon storage and source definition. Device settings are always empty.\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nimport { accept, reject, record, type Item, defineSource } from \"https://esm.town/v/plusjade/source-sdk@3-main/mod.ts\";\n\n// Preserve the existing UTC-date selection policy and Pacific fallback.\nexport function fromDate(offset: number | null, now = new Date()): string {\n return offset !== null && offset >= -43200 && offset <= 50400\n ? new Date(now.getTime() + offset * 1000).toISOString().slice(0, 10)\n : now.toLocaleDateString(\"en-CA\", { timeZone: \"America/Los_Angeles\" });\n}\n\nexport async function moonItems(dateKey: string): Promise {\n const result = await sqlite.execute({\n sql: \"SELECT date_key, payload FROM full_moons WHERE date_key >= ? ORDER BY date_key LIMIT 1\",\n args: [dateKey],\n });\n const row = result.rows[0];\n if (!row) return [];\n const payload = JSON.parse(String(row.payload));\n return [{\n id: `moon-${row.date_key}`,\n mainText: \"Full Moon\",\n subText: payload.name,\n // A peak instant is not a moonrise or an invitation to look outside.\n caption: \"PEAK\",\n emphasized: false,\n timestamp: Math.floor(Date.parse(payload.peakTime) / 1000),\n }];\n}\n\nexport default defineSource({\n key: \"moon\",\n settingsSchema: { type: \"object\", properties: {}, additionalProperties: false },\n parseSettings: (raw) => Object.keys(raw).length === 0 ? accept(null) : reject(\"invalid_settings\"),\n read: (_, { utcOffsetSeconds }) => moonItems(fromDate(utcOffsetSeconds)),\n writes: {\n // Retains the parent's existing ingest envelope; storage is Moon-only.\n \"cache.put\": async (raw) => {\n const p = raw.payload;\n if (raw.source !== \"moon\" || typeof raw.dateKey !== \"string\"\n || !/^\\d{4}-\\d{2}-\\d{2}$/.test(raw.dateKey)\n || !record(p) || typeof p.name !== \"string\" || !p.name.trim()\n || typeof p.peakTime !== \"string\" || !Number.isFinite(Date.parse(p.peakTime))\n || new Date(p.peakTime).toISOString().slice(0, 10) !== raw.dateKey\n || (p.isBlueMoon !== undefined && typeof p.isBlueMoon !== \"boolean\")) {\n return reject(\"invalid_cache_payload\");\n }\n await sqlite.execute({\n sql: `INSERT INTO full_moons(date_key,payload,fetched_at) VALUES(?,?,?)\n ON CONFLICT(date_key) DO UPDATE SET payload=excluded.payload,fetched_at=excluded.fetched_at`,\n args: [raw.dateKey, JSON.stringify(p), new Date().toISOString()],\n });\n return accept({ source: \"moon\", dateKey: raw.dateKey });\n },\n },\n});\n",[166],"57d5e689-277e-4320-83c4-0af786fe6c89","check.ts","01a07fdc-87bd-7507-81cb-6f31de58df05",["D",1788851554238],"// Moon contract and storage checks; the disposable write is always removed.\nimport handler from \"./rpc.ts\";\nimport { fromDate, moonItems } from \"./moonSource.ts\";\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nfunction check(ok: unknown, message: string) { if (!ok) throw new Error(message); }\nconst base = {protocolVersion:1,sourceKey:\"moon\"};\nasync function call(path: string, body?: unknown, auth=true) {\n return await handler(new Request(\"https://moon.invalid\"+path,{\n method:body===undefined?\"GET\":\"POST\",\n headers:auth?{authorization:`Bearer ${Deno.env.get(\"SOURCE_MOON_V1_TOKEN\")}`}:{},\n ...(body===undefined?{}:{body:JSON.stringify(body)})\n }));\n}\ncheck((await call(\"/v1/descriptor\",undefined,false)).status===401,\"auth\");\nconst desc=await (await call(\"/v1/descriptor\")).json();\ncheck(desc.temporal && desc.sourceKey===\"moon\" && !(\"options\" in desc),\"descriptor\");\ncheck(JSON.stringify(desc.capabilities.write)==='[\"cache.put\"]',\"writes\");\nfor (const tz of [null,0,-43200,50400]) {\n const r=await call(\"/v1/read\",{...base,settings:{},context:{utcOffsetSeconds:tz}});\n const p=await r.json();check(r.ok&&p.items.length===1&&p.items[0].caption===\"PEAK\",\"read\");\n}\ncheck((await call(\"/v1/read\",{...base,settings:{x:1},context:{utcOffsetSeconds:0}})).status===400,\"settings\");\ncheck((await call(\"/v1/read\",{...base,sourceKey:\"sports\",settings:{},context:{utcOffsetSeconds:0}})).status===404,\"wrong source\");\ncheck((await call(\"/v1/write\",{...base,operation:\"toString\",payload:{}})).status===422,\"unsupported write\");\ncheck((await call(\"/v1/publish\",base)).status===501,\"publish\");\ncheck(fromDate(null,new Date(\"2026-01-04T07:30:00Z\"))===\"2026-01-03\",\"winter fallback\");\ncheck(fromDate(null,new Date(\"2026-07-04T06:30:00Z\"))===\"2026-07-03\",\"summer fallback\");\ncheck(fromDate(50400,new Date(\"2026-01-03T12:00:00Z\"))===\"2026-01-04\",\"positive boundary\");\ncheck((await moonItems(\"2026-05-31\"))[0].subText===\"Blue Moon\",\"blue moon\");\ncheck((await moonItems(\"2027-01-01\")).length===0,\"exhaustion\");\nconst dateKey=\"1900-01-01\";\ntry {\n const payload={source:\"moon\",dateKey,payload:{name:\"Fixture\",peakTime:dateKey+\"T12:00:00Z\",isBlueMoon:false}};\n const written=await call(\"/v1/write\",{...base,operation:\"cache.put\",payload});\n check(written.ok,\"write\");\n const item=(await moonItems(dateKey))[0];\n check(item.id===\"moon-\"+dateKey&&item.timestamp===Date.parse(payload.payload.peakTime)/1000,\"write readback seconds\");\n check((await call(\"/v1/write\",{...base,operation:\"cache.put\",payload:{...payload,source:\"fiba\"}})).status===400,\"foreign write\");\n check((await call(\"/v1/write\",{...base,operation:\"cache.put\",payload:{...payload,dateKey:\"1900-02-30\"}})).status===400,\"bad date\");\n} finally {\n await sqlite.execute({sql:\"DELETE FROM full_moons WHERE date_key=?\",args:[dateKey]});\n}\nconsole.log(\"PASS: Moon auth, descriptor, reads, empty settings, UTC boundaries, exhaustion, writes and cleanup\");\n",[173],"ab0d4f00-5294-4b46-929d-95df333ec1da","README.md","01a07fdc-87bd-7507-81cb-681b74684c27",["D",1788851554238],"# Moon source\n\nFive runtime modules: `rpc.ts`, `moonSource.ts`, and three vendored SDK modules copied unchanged from source-sports main version 11. `check.ts` is a manual Val Town verification script; it removes its disposable write in finally.\n\nThe only table is `full_moons(date_key TEXT PRIMARY KEY, payload TEXT NOT NULL CHECK(json_valid(payload)), fetched_at TEXT NOT NULL)`. It is provisioned at deployment, not during reads. Thirteen 2026 events were copied from the retired sibling. Coverage ends December 24, 2026; seed the next year through authenticated `cache.put`.\n\nSettings are exactly `{}`. Reads return one next event or an empty list. Selection deliberately preserves the former UTC date-key comparison against the client's calendar date, including the America/Los_Angeles fallback for null/out-of-range offsets; it does not change lunar day-boundary policy.\n\nThe parent owns source instance 3, assignments, composition, and presentation. HTTP auth uses SOURCE_MOON_V1_TOKEN. No legacy routes, schedulers, upstream fetches, or cross-val runtime imports.\n",[179],"b05fd0ce-38fd-402e-847a-689de3218fc9","sdk","01a07fdc-87bd-7507-81cb-6791e8f6883a",["D",1788851554238],"directory",[185],"pulls","branches","forks","envVars",{"_197":153,"_199":63},"connections",{"_197":63,"_198":63},"count","unfilledCount","emptyCount",{"_43":184,"_32":185,"_30":186,"_149":-5,"_41":42,"_40":153,"_151":25,"_38":245,"_13":63,"_34":188,"_36":-5,"_24":49,"_155":-5,"_210":246,"_27":247},{"_43":239,"_32":179,"_30":240,"_149":186,"_41":42,"_40":153,"_151":49,"_38":241,"_13":63,"_34":20,"_36":242,"_24":49,"_155":-5,"_210":243,"_27":244},{"_43":232,"_32":233,"_30":234,"_149":186,"_41":42,"_40":153,"_151":49,"_38":235,"_13":63,"_34":35,"_36":236,"_24":49,"_155":-5,"_210":237,"_27":238},{"_43":225,"_32":226,"_30":227,"_149":186,"_41":42,"_40":153,"_151":49,"_38":228,"_13":63,"_34":20,"_36":229,"_24":49,"_155":-5,"_210":230,"_27":231},{"_43":178,"_32":179,"_30":180,"_149":-5,"_41":42,"_40":153,"_151":49,"_38":222,"_13":63,"_34":20,"_36":182,"_24":49,"_155":-5,"_210":223,"_27":224},{"_43":172,"_32":173,"_30":174,"_149":-5,"_41":42,"_40":153,"_151":25,"_38":219,"_13":63,"_34":35,"_36":176,"_24":49,"_155":-5,"_210":220,"_27":221},{"_43":165,"_32":166,"_30":167,"_149":-5,"_41":42,"_40":168,"_151":25,"_38":216,"_13":153,"_34":35,"_36":170,"_24":49,"_155":-5,"_210":217,"_27":218},{"_43":157,"_32":158,"_30":159,"_149":-5,"_41":42,"_40":160,"_151":25,"_38":213,"_13":153,"_34":162,"_36":163,"_24":49,"_155":-5,"_210":214,"_27":215},{"_43":146,"_32":147,"_30":148,"_149":-5,"_41":42,"_40":150,"_151":49,"_38":209,"_13":153,"_34":35,"_36":154,"_24":49,"_155":-5,"_210":211,"_27":212},["D",1788851601536],"children",[],[147],["D",1788851626537],[],[158],["D",1788851630609],[],[166],["D",1788851554238],[],[173],["D",1788851554238],[],[179],"c281a211-e44f-4ffa-ab3b-cfc3a02fe2ab","settings-form.md","01a07fdc-87bd-7507-81cb-61973d9799db",["D",1788851554238],"# 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",[],[185,226],"f2f345a2-c44a-4144-a68c-e205b02ff7d5","serve.ts","01a07fdc-87bd-7507-81cb-5eea0be0985a",["D",1788851554238],"// Version 1 of the source protocol, as a function of a SourceDefinition.\n// Everything here is the same for every source, which is exactly why it is\n// here and not in the source: an implementer who writes this by hand writes\n// the envelopes, the status codes and the output guard slightly differently\n// each time, and the parent is the one that finds out.\n//\n// The routes:\n// GET /v1/descriptor what this source is, and what settings it takes\n// POST /v1/read settings + context in, items out\n// POST /v1/write a named side effect from `writes`\n// POST /v1/publish 501; reserved, no source implements it yet\n//\n// Auth is NOT here. It belongs to whatever mounts this (rpc.ts), because the\n// credential is a deployment concern and a source shouldn't have an opinion\n// about how it is fronted.\n//\n// Part of the SDK — see sdk/contract.ts's header for the import rule.\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 a\n // non-finite timestamp 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",[],[185,233],"6b67a6fd-3c9f-43ee-ba6e-692818fc2ca0","01a07fdc-87bd-7507-81cb-53246c608d7d",["D",1788851554238],"# Source SDK (protocol v1)\n\nA **source** answers one question: *given these settings and this caller's\ntimezone, what are the next few things worth showing?* It returns a flat list\nof items. It does not know who is asking, what else is on the screen, or how\nany of it is rendered.\n\nThis directory is everything that is true of every source. It has **no\ndependencies** — not on npm, not on Val Town's `std`, not on the val around it.\nThree files:\n\n| File | What's in it |\n| --- | --- |\n| `contract.ts` | `Item`, the validator that enforces it, and `accept`/`reject` |\n| `defineSource.ts` | `SourceDefinition` — the whole author-facing surface |\n| `serve.ts` | `serveSource()` — the protocol, as a function of a definition |\n\n## Write a source\n\nFor the parent’s supported browser forms, see [the settings form contract](settings-form.md).\nThe protocol permits broader schemas; the parent deliberately rejects forms outside\nits small supported subset. The example below illustrates the broader protocol,\nnot a browser-renderable form.\n\nOne object, one mount. That is the entire API.\n\n```ts\nimport { accept, reject } from \"./sdk/contract.ts\";\nimport { defineSource } from \"./sdk/defineSource.ts\";\n\nexport default defineSource<{ city: string }>({\n key: \"weather\",\n\n settingsSchema: {\n type: \"object\",\n properties: { city: { type: \"string\" } },\n required: [\"city\"],\n additionalProperties: false,\n },\n\n // Optional legacy metadata. The parent does not render this; browser choices\n // must be bound to properties in settingsSchema (see settings-form.md).\n options: () => listCities(),\n\n // The only place caller input is validated. Must be total — reject anything\n // you don't recognize, unknown keys included. May do I/O.\n parseSettings: (raw) =>\n typeof raw.city === \"string\" && known(raw.city)\n ? accept({ city: raw.city })\n : reject(\"unknown_city\"),\n\n // The source itself. Timestamps are Unix SECONDS.\n read: async ({ city }, { utcOffsetSeconds }) => [{\n id: `weather:${city}:tomorrow`,\n mainText: \"Rain expected\",\n subText: \"Portland\",\n caption: null,\n emphasized: false,\n timestamp: 1788739200,\n }],\n\n // Optional: named side effects. The keys become the protocol's `operation`\n // values and the descriptor's advertised capabilities.\n writes: {\n \"cache.put\": async (payload) =>\n typeof payload.dateKey === \"string\"\n ? accept(await store(payload))\n : reject(\"invalid_cache_payload\"),\n },\n});\n```\n\nThen mount it behind whatever auth the deployment wants:\n\n```ts\n// rpc.ts — an HTTP val\nexport default (req: Request) =>\n authorized(req) ? serveSource(mySource, req) : unauthorized();\n```\n\n`tools/sdk-check.ts` in this val defines a complete fixture source in ~30\nlines and asserts the protocol against it. It is the shortest working example;\ncopying it is a reasonable way to start.\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 a non-finite timestamp — 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.\n- Auth. That is the mount's business, not the source's.\n\n## Three things that go wrong\n\n1. **Milliseconds in `timestamp`.** It is Unix *seconds*. Sending ms decodes on\n the client as a date ~57,000 years out, and nothing catches it: both are\n numbers, and the contract validator can only reject values too large to be a\n plausible timestamp — a real ms value is not. 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## The one structural rule\n\n**Nothing under `sdk/` may import anything outside `sdk/`.**\n\nThat is what makes this directory liftable into its own published val without a\nrewrite, and it is the kind of rule that decays quietly, so it is enforced\nrather than asked for: `tools/sdk-check.ts` fails if an import escapes the\ndirectory, or if SDK *code* so much as names one of the host val's domain\nconcepts. Run it after touching anything in here.\n\nDomain vocabulary belongs on the other side of the seam — in this val, that is\n`sportsSource.ts` (the definition) and `lib/` (how it gets its data).\n",[],[185,179],["D",1788851554238],[201,202,203],[185],["D",1788806619199],["D",1789501878689],{"_102":101,"_109":105},{"_102":101,"_103":-5,"_104":105,"_18":56,"_106":107,"_108":49},{"_13":89,"_32":90,"_43":42,"_91":44,"_92":93,"_94":95,"_96":51,"_97":44,"_98":65,"_99":45,"_100":101},"ctx",{"_82":-5,"_130":286,"_287":288,"_289":290,"_291":49,"_292":49,"_293":49,"_294":25,"_295":-5,"_296":-7,"_297":-7,"_298":63,"_299":49,"_300":49,"_301":-5,"_302":49,"_303":49,"_304":49,"_305":-5},"ENV",{"_257":258,"_259":260,"_261":136,"_262":263,"_264":265,"_266":267,"_268":269,"_270":271,"_272":273,"_274":275,"_276":277,"_278":279,"_280":281,"_282":283,"_284":285},"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"]

Diff · v7