aaronrene / knowtation public
source-calendar-defaults.mjs
65 lines 2.3 KB
Raw
sha256:65ccb454656ea5acdea0a10e559b78bcde1eb6ff753ecc2911bc99d1c3d7cadd feat(calendar): enforce agent context tiers in retrieval AP… Human minor ⚠ breaking 1 day ago
1 /**
2 * Default toggle values for new SourceCalendar rows (Calendar Events v0).
3 *
4 * Product rule: synced calendars appear on the timeline by default, but agents
5 * receive no calendar context until the user opts in per calendar.
6 *
7 * @see docs/CALENDAR-EVENTS-V0-SPEC.md — Security checklist §Phase 0
8 */
9
10 /** @typedef {0 | 1 | 2 | 3 | 4} AgentContextTier */
11
12 /** @type {readonly AgentContextTier[]} */
13 export const AGENT_CONTEXT_TIERS = Object.freeze([0, 1, 2, 3, 4]);
14
15 /**
16 * Canonical defaults applied when a user connects a new external calendar.
17 * @type {Readonly<{
18 * enabled_for_sync: boolean,
19 * enabled_for_display: boolean,
20 * enabled_for_agents: boolean,
21 * agent_context_tier_max: AgentContextTier,
22 * }>}
23 */
24 export const SOURCE_CALENDAR_DEFAULTS = Object.freeze({
25 enabled_for_sync: true,
26 enabled_for_display: true,
27 enabled_for_agents: false,
28 agent_context_tier_max: 0,
29 });
30
31 /**
32 * Build a SourceCalendar toggle snapshot with v0 defaults, optionally overridden.
33 *
34 * @param {Partial<typeof SOURCE_CALENDAR_DEFAULTS>} [overrides]
35 * @returns {typeof SOURCE_CALENDAR_DEFAULTS}
36 */
37 export function buildSourceCalendarDefaults(overrides = {}) {
38 const tier = overrides.agent_context_tier_max ?? SOURCE_CALENDAR_DEFAULTS.agent_context_tier_max;
39 if (!AGENT_CONTEXT_TIERS.includes(/** @type {AgentContextTier} */ (tier))) {
40 throw new RangeError('agent_context_tier_max must be 0–4');
41 }
42 return {
43 enabled_for_sync: overrides.enabled_for_sync ?? SOURCE_CALENDAR_DEFAULTS.enabled_for_sync,
44 enabled_for_display: overrides.enabled_for_display ?? SOURCE_CALENDAR_DEFAULTS.enabled_for_display,
45 enabled_for_agents: overrides.enabled_for_agents ?? SOURCE_CALENDAR_DEFAULTS.enabled_for_agents,
46 agent_context_tier_max: /** @type {AgentContextTier} */ (tier),
47 };
48 }
49
50 /**
51 * Whether agent retrieval may include fields from a calendar at the requested tier.
52 *
53 * @param {{ enabled_for_agents: boolean, agent_context_tier_max: AgentContextTier }} calendar
54 * @param {AgentContextTier} requestedTier
55 * @returns {boolean}
56 */
57 export function isAgentTierAllowed(calendar, requestedTier) {
58 if (!calendar.enabled_for_agents) {
59 return requestedTier === 0;
60 }
61 if (!AGENT_CONTEXT_TIERS.includes(requestedTier)) {
62 return false;
63 }
64 return requestedTier <= calendar.agent_context_tier_max;
65 }
File History 1 commit
sha256:65ccb454656ea5acdea0a10e559b78bcde1eb6ff753ecc2911bc99d1c3d7cadd feat(calendar): enforce agent context tiers in retrieval AP… Human minor ⚠ 1 day ago