portal-mojo 0.1.0

package/src/admin/phonehub/PhoneHubPage.tsx

@@ -0,0 +1,57 @@
+import { useRef, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { ArmedButton, Badge, DetailView, FlatRow, ModelTable, Tabs, fmt, modal, toast, type Column, type FilterDef } from '../../ui';
+import { useCan } from '../../client';
+import { buildPhoneConfigPayload, fetchPhoneGroupChoices, lookupPhoneNumber, savePhoneConfigImperative, testPhoneConfigImperative, type PhoneSecretField, type SecretEdit } from './api';
+import { exportPhoneConfigs, exportPhoneNumbers, exportSmsAudits } from './data';
+import {
+    PHONE_CONFIG_DELETE_PERMISSIONS, PHONE_CONFIG_MANAGE_PERMISSIONS, PHONE_CONFIG_VIEW_PERMISSIONS,
+    PHONE_GROUP_DIRECTORY_PERMISSIONS, PHONE_LOOKUP_UI_PERMISSIONS, PHONE_NUMBER_DELETE_PERMISSIONS,
+    PHONE_NUMBER_VIEW_PERMISSIONS, SMS_DELETE_PERMISSIONS, SMS_VIEW_PERMISSIONS,
+    PhoneConfigModel, PhoneNumberModel, SmsModel, type PhoneConfigRow, type PhoneNumberRow, type SmsRow,
+} from './models';
+
+const relationLabel=(value:{id:number;name?:string;display_name?:string}|number|null,empty='System default')=>value==null?empty:typeof value==='number'?`#${value}`:value.name??value.display_name??`#${value.id}`;
+const tone=(status:string)=>status==='delivered'||status==='valid'?'success':status==='failed'||status==='undelivered'||status==='invalid'?'danger':'warning';
+const phoneColumns:Column<PhoneNumberRow>[]=[
+    {key:'phone_number',label:'Phone number',sortable:true,hideable:false,render:r=><code>{r.phone_number}</code>},
+    {key:'carrier',label:'Carrier',sortable:true,render:r=>r.carrier||'—'},
+    {key:'line_type',label:'Line type',sortable:true,render:r=>r.line_type||'—'},
+    {key:'is_valid',label:'Validity',render:r=><Badge tone={r.is_valid?'success':'danger'}>{r.is_valid?'valid':'invalid'}</Badge>},
+    {key:'lookup_count',label:'Lookups',sortable:true,align:'end'},
+    {key:'last_lookup_at',label:'Last lookup',sortable:true,render:r=>r.last_lookup_at?fmt.datetime(r.last_lookup_at):'Never'},
+];
+const smsColumns:Column<SmsRow>[]=[
+    {key:'created',label:'Created',sortable:true,hideable:false,render:r=>fmt.datetime(r.created)},
+    {key:'direction',label:'Direction',sortable:true,render:r=><Badge tone="info">{r.direction}</Badge>},
+    {key:'from_number',label:'From',render:r=><code>{r.from_number}</code>},
+    {key:'to_number',label:'To',render:r=><code>{r.to_number}</code>},
+    {key:'status',label:'Status',sortable:true,render:r=><Badge tone={tone(r.status)}>{r.status}</Badge>},
+    {key:'provider',label:'Provider',sortable:true,render:r=>r.provider||'—'},
+];
+const smsFilters:FilterDef[]=[{key:'direction',label:'Direction',type:'select',options:['inbound','outbound'].map(value=>({value,label:value}))},{key:'status',label:'Status',type:'select',options:['queued','sending','sent','delivered','failed','undelivered','received'].map(value=>({value,label:value}))},{key:'provider',label:'Provider',type:'select',options:['twilio','aws','mojo'].map(value=>({value,label:value}))},{key:'created',label:'Created',type:'daterange'}];
+const configColumns:Column<PhoneConfigRow>[]=[
+    {key:'name',label:'Configuration',sortable:true,hideable:false},
+    {key:'group',label:'Scope',render:r=>relationLabel(r.group)},
+    {key:'provider',label:'Stored/tested provider',sortable:true,render:r=><Badge tone="info">{r.provider}</Badge>},
+    {key:'is_active',label:'Active',sortable:true,render:r=><Badge tone={r.is_active?'success':'muted'}>{r.is_active?'active':'inactive'}</Badge>},
+    {key:'test_mode',label:'Test mode',render:r=><Badge tone={r.test_mode?'warning':'muted'}>{r.test_mode?'yes':'no'}</Badge>},
+    {key:'modified',label:'Modified',sortable:true,render:r=>fmt.datetime(r.modified)},
+];
+
+function PhoneDetail({id,onClose}:{id:number;onClose:()=>void}){const query=PhoneNumberModel.useOne(id);const canDelete=useCan(PHONE_NUMBER_DELETE_PERMISSIONS).can;const destroy=PhoneNumberModel.useDelete();if(!query.data)return <div className="modal-pad">{query.isLoading?'Loading phone record…':'Phone record unavailable'}<button className="btn" onClick={onClose}>Close</button></div>;const row=query.data;const remove=async()=>{await destroy.mutateAsync({id});toast.success('Local phone cache row deleted');onClose();};return <DetailView title={row.phone_number} subtitle={`${row.carrier||'Unknown carrier'} · ${row.line_type||'Unknown line type'}`} icon="bi-telephone" onClose={onClose} sections={[{key:'lookup',label:'Lookup',icon:'bi-search',render:()=><div className="detail-section"><FlatRow label="Provider">{row.lookup_provider||'—'}</FlatRow><FlatRow label="Lookup count">{row.lookup_count}</FlatRow><FlatRow label="Last lookup">{row.last_lookup_at?fmt.datetime(row.last_lookup_at):'Never'}</FlatRow><FlatRow label="Expires">{row.lookup_expires_at?fmt.datetime(row.lookup_expires_at):'Unknown'}</FlatRow><p className="dim">Lookup payloads are deliberately excluded from the client cache.</p></div>},{key:'identity',label:'Carrier & owner',icon:'bi-person-lines-fill',render:()=><div className="detail-section"><FlatRow label="Valid">{row.is_valid?'Yes':'No'}</FlatRow><FlatRow label="Mobile">{row.is_mobile?'Yes':'No'}</FlatRow><FlatRow label="VoIP">{row.is_voip?'Yes':'No'}</FlatRow><FlatRow label="Registered owner">{row.registered_owner||'—'}</FlatRow><FlatRow label="Region">{[row.region,row.state].filter(Boolean).join(', ')||'—'}</FlatRow></div>},...(canDelete?[{key:'delete',label:'Delete',icon:'bi-trash',render:()=><div className="detail-section"><p>Deletes this global cached phone record only. It does not affect provider data.</p><ArmedButton label="Delete cached record" armedLabel="Click again to delete" onConfirm={remove}/></div>}]:[])]}/>;}
+
+function LookupDialog({close}:{close:(row:PhoneNumberRow|null)=>void}){const qc=useQueryClient();const [value,setValue]=useState('');const [busy,setBusy]=useState(false);const [error,setError]=useState('');const submit=async()=>{setBusy(true);setError('');try{const normalized=await import('./api').then(api=>api.normalizePhoneNumber(value));let previous:PhoneNumberRow|undefined;try{const existing=await import('../../client').then(api=>api.mojoList<PhoneNumberRow>(PhoneNumberModel.endpoint,{phone_number:normalized,graph:'default',start:0,size:1}));previous=existing.rows[0];}catch{/* lookup remains available for a new row */}const row=await lookupPhoneNumber(normalized,previous,()=>window.confirm('This cache row is still fresh. Force a paid global Twilio Lookup anyway?'));qc.setQueryData(PhoneNumberModel.keys.one(row.id),row);await qc.invalidateQueries({queryKey:PhoneNumberModel.keys.root});toast.success('Lookup completed with refresh evidence');close(row);}catch(reason){setError(reason instanceof Error?reason.message:'Lookup failed');}finally{setBusy(false);}};return <div className="modal-pad"><h2 className="modal-title">Lookup phone number</h2><p className="dim">The number is normalized first. New or expired rows refresh automatically; a known-fresh row requires confirmation before a paid global Twilio Lookup.</p>{error&&<div className="form-alert" role="alert">{error}</div>}<label className="field"><span className="field-label">Phone number</span><input className="input" value={value} onChange={e=>setValue(e.target.value)} placeholder="+1 415 555 0100"/></label><div className="modal-actions"><button className="btn" disabled={busy} onClick={()=>close(null)}>Cancel</button><button className="btn btn-primary" disabled={busy||!value.trim()} onClick={()=>void submit()}>{busy?'Looking up…':'Normalize and look up'}</button></div></div>;}
+
+export function PhoneNumbersPage(){const canLookup=useCan(PHONE_LOOKUP_UI_PERMISSIONS).can;return <ModelTable model={PhoneNumberModel} eyebrow="Communications · Phone Hub" title="Phone Numbers" columns={phoneColumns} defaultSort="phone_number" searchable searchPlaceholder="Search number, carrier, or owner" columnChooser persistState persistKey="admin:phonehub:numbers" exportFormats={['csv','json']} exporter={exportPhoneNumbers} addLabel="Lookup number" onAdd={canLookup?()=>void modal.open(close=><LookupDialog close={close}/>):undefined} onRowClick={row=>void modal.detail(close=><PhoneDetail id={row.id} onClose={()=>close(null)}/>)}/>;}
+
+function SmsDetail({id,onClose}:{id:number;onClose:()=>void}){const query=SmsModel.useOne(id);const canDelete=useCan(SMS_DELETE_PERMISSIONS).can;const destroy=SmsModel.useDelete();if(!query.data)return <div className="modal-pad">{query.isLoading?'Loading SMS audit…':'SMS audit unavailable'}<button className="btn" onClick={onClose}>Close</button></div>;const row=query.data;const remove=async()=>{await destroy.mutateAsync({id});toast.success('Local SMS audit row deleted');onClose();};return <DetailView title={`${row.from_number} → ${row.to_number}`} subtitle={`${row.direction} · ${row.status}`} icon="bi-chat-square-text" onClose={onClose} sections={[{key:'message',label:'Message',icon:'bi-chat-text',render:()=><div className="detail-section"><FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow><FlatRow label="Provider">{row.provider||'—'}</FlatRow><FlatRow label="Group">{relationLabel(row.group,'None')}</FlatRow><div className="known-card"><h3>Message body</h3><p className="pre-wrap">{row.body||'—'}</p></div>{row.error_message&&<div className="form-alert">{row.error_message}</div>}</div>},...(canDelete?[{key:'delete',label:'Delete',icon:'bi-trash',render:()=><div className="detail-section"><p>Deletes the local audit row only. It cannot recall or alter a provider message. SMS rows are deleted when their owning user or group is deleted; deleting a provider config does not delete them.</p><ArmedButton label="Delete SMS audit row" armedLabel="Click again to delete" onConfirm={remove}/></div>}]:[])]}/>;}
+export function SmsPage(){return <ModelTable model={SmsModel} eyebrow="Communications · Phone Hub" title="SMS Audit" columns={smsColumns} filters={smsFilters} defaultSort="-created" searchable searchPlaceholder="Search number or message body" autoRefresh={20} columnChooser persistState persistKey="admin:phonehub:sms" exportFormats={['csv','json']} exporter={exportSmsAudits} onRowClick={row=>void modal.detail(close=><SmsDetail id={row.id} onClose={()=>close(null)}/>)}/>;}
+
+const credentialLabels:Record<PhoneSecretField,string>={twilio_account_sid:'Twilio account SID',twilio_auth_token:'Twilio auth token',aws_access_key_id:'AWS access key id',aws_secret_access_key:'AWS secret access key',mojo_api_key:'Mojo service API key'};
+function ConfigEditor({row,close}:{row?:PhoneConfigRow;close:(value:PhoneConfigRow|null)=>void}){const qc=useQueryClient();const canGroups=useCan(PHONE_GROUP_DIRECTORY_PERMISSIONS).can;const groups=useQuery({queryKey:['phonehub','group-choices'],queryFn:fetchPhoneGroupChoices,enabled:canGroups,staleTime:60_000});const [name,setName]=useState(row?.name??'');const [provider,setProvider]=useState<PhoneConfigRow['provider']>(row?.provider??'twilio');const [group,setGroup]=useState(row?.group==null?'':String(typeof row.group==='number'?row.group:row.group.id));const [active,setActive]=useState(row?.is_active??true);const [testMode,setTestMode]=useState(row?.test_mode??false);const [lookup,setLookup]=useState(row?.lookup_enabled??true);const [cacheDays,setCacheDays]=useState(row?.lookup_cache_days??90);const [twilioFrom,setTwilioFrom]=useState(row?.twilio_from_number??'');const [awsRegion,setAwsRegion]=useState(row?.aws_region??'us-east-1');const [awsSender,setAwsSender]=useState(row?.aws_sender_id??'');const [mojoUrl,setMojoUrl]=useState(row?.mojo_remote_url??'');const refs=useRef<Partial<Record<PhoneSecretField,HTMLInputElement|null>>>({});const [clearFields,setClearFields]=useState<PhoneSecretField[]>([]);const [busy,setBusy]=useState(false);const [error,setError]=useState('');const toggleClear=(field:PhoneSecretField)=>{if(clearFields.includes(field)){setClearFields(clearFields.filter(v=>v!==field));return;}if(window.confirm(`Clear the stored ${credentialLabels[field]} on save?`))setClearFields([...clearFields,field]);};const submit=async()=>{setBusy(true);setError('');const credentials:Partial<Record<PhoneSecretField,SecretEdit>>={};for(const field of Object.keys(credentialLabels) as PhoneSecretField[]){const value=refs.current[field]?.value??'';credentials[field]=clearFields.includes(field)?{mode:'clear',confirmed:true}:value?{mode:'replace',value}:{mode:'untouched'};}try{buildPhoneConfigPayload({},credentials);const saved=await savePhoneConfigImperative(qc,row?.id??null,{name:name.trim(),provider,group:group?Number(group):null,is_active:active,test_mode:testMode,lookup_enabled:lookup,lookup_cache_days:cacheDays,twilio_from_number:twilioFrom||null,aws_region:awsRegion||null,aws_sender_id:awsSender||null,mojo_remote_url:mojoUrl||null},credentials);for(const field of Object.keys(credentialLabels) as PhoneSecretField[])if(refs.current[field])refs.current[field]!.value='';toast.success(row?'Provider configuration updated':'Provider configuration created');close(saved);}catch(reason){setError(reason instanceof Error?reason.message:'Configuration could not be saved');}finally{setBusy(false);}};return <div className="modal-pad phonehub-config-editor"><h2 className="modal-title">{row?'Edit':'Create'} provider configuration</h2><p className="dim">Credentials are write-only. Leave a field blank to keep it, type a replacement, or explicitly confirm Clear. Empty strings are never submitted.</p>{error&&<div className="form-alert" role="alert">{error}</div>}<div className="form-grid"><label className="field col-8"><span className="field-label">Name</span><input className="input" value={name} onChange={e=>setName(e.target.value)}/></label><label className="field col-4"><span className="field-label">Provider</span><select className="input" value={provider} onChange={e=>setProvider(e.target.value as PhoneConfigRow['provider'])}><option value="twilio">Twilio</option><option value="aws">AWS</option><option value="mojo">Mojo</option></select></label>{canGroups?<label className="field col-12"><span className="field-label">Group scope</span><select className="input" value={group} onChange={e=>setGroup(e.target.value)}><option value="">System default</option>{groups.data?.map(item=><option key={item.id} value={item.id}>{item.name}</option>)}</select><span className="field-help">Choices are a bounded global directory projection (maximum 100).</span></label>:<div className="field col-12"><span className="field-label">Group scope</span><div className="input" aria-readonly="true">{relationLabel(row?.group??null)}</div><span className="field-help">Group choices stay hidden without global group-directory permission.</span></div>}<label className="field col-6"><span className="field-label">Twilio from number</span><input className="input" value={twilioFrom} onChange={e=>setTwilioFrom(e.target.value)}/></label><label className="field col-6"><span className="field-label">AWS region</span><input className="input" value={awsRegion} onChange={e=>setAwsRegion(e.target.value)}/></label><label className="field col-6"><span className="field-label">AWS sender id</span><input className="input" value={awsSender} onChange={e=>setAwsSender(e.target.value)}/></label><label className="field col-6"><span className="field-label">Mojo remote URL</span><input className="input" value={mojoUrl} onChange={e=>setMojoUrl(e.target.value)}/></label>{(Object.keys(credentialLabels) as PhoneSecretField[]).map(field=><label className="field col-6" key={field}><span className="field-label">{credentialLabels[field]}</span><div className="phonehub-secret-row"><input ref={node=>{refs.current[field]=node;}} className="input" type="password" autoComplete="new-password" disabled={clearFields.includes(field)}/><button type="button" className={`btn${clearFields.includes(field)?' btn-danger':''}`} onClick={()=>toggleClear(field)}>{clearFields.includes(field)?'Keep instead':'Clear…'}</button></div></label>)}<label className="check col-4"><input type="checkbox" checked={active} onChange={e=>setActive(e.target.checked)}/><span>Active</span></label><label className="check col-4"><input type="checkbox" checked={testMode} onChange={e=>setTestMode(e.target.checked)}/><span>Test mode</span></label><label className="check col-4"><input type="checkbox" checked={lookup} onChange={e=>setLookup(e.target.checked)}/><span>Lookup enabled</span></label><label className="field col-4"><span className="field-label">Lookup cache days</span><input className="input" type="number" min="1" value={cacheDays} onChange={e=>setCacheDays(Number(e.target.value))}/></label></div><div className="modal-actions"><button className="btn" disabled={busy} onClick={()=>close(null)}>Cancel</button><button className="btn btn-primary" disabled={busy||!name.trim()} onClick={()=>void submit()}>{busy?'Saving…':'Save configuration'}</button></div></div>;}
+
+function ConfigDetail({id,onClose}:{id:number;onClose:()=>void}){const query=PhoneConfigModel.useOne(id);const canManage=useCan(PHONE_CONFIG_MANAGE_PERMISSIONS).can;const canDelete=useCan(PHONE_CONFIG_DELETE_PERMISSIONS).can;const destroy=PhoneConfigModel.useDelete();if(!query.data)return <div className="modal-pad">{query.isLoading?'Loading provider configuration…':'Configuration unavailable'}<button className="btn" onClick={onClose}>Close</button></div>;const row=query.data;const edit=()=>void modal.open(close=><ConfigEditor row={row} close={async saved=>{close(saved);if(saved)await query.refetch();}}/>,{size:'lg'});const test=async()=>{try{const result=await testPhoneConfigImperative(id);toast[result.status?'success':'error'](result.message);}catch(reason){toast.error(reason instanceof Error?reason.message:'Connection test failed');}};const remove=async()=>{await destroy.mutateAsync({id});toast.success('Provider configuration deleted');onClose();};return <DetailView title={row.name} subtitle={`${relationLabel(row.group)} · ${row.provider}`} icon="bi-phone" onClose={onClose} sections={[{key:'configuration',label:'Configuration',icon:'bi-sliders',render:()=><div className="detail-section"><div className="storage-action-row">{canManage&&<><button className="btn" onClick={edit}>Edit</button><button className="btn" onClick={()=>void test()}>Test stored connection</button></>}</div><FlatRow label="Provider">{row.provider}</FlatRow><FlatRow label="Active">{row.is_active?'Yes':'No'}</FlatRow><FlatRow label="Test mode">{row.test_mode?'Yes':'No'}</FlatRow><FlatRow label="Lookup cache">{row.lookup_cache_days} days</FlatRow><p className="form-alert">Test mode only short-circuits the connection test; it does not prevent SMS sends. Current sending uses a per-group configuration only for the Mojo provider. Stored Twilio and AWS credentials are testable, but sending still follows global Twilio settings; AWS sending is not wired.</p><p className="dim">An active group config wins, otherwise the first active system default is used. Deleting or deactivating it falls back to the system default. Deleting a group cascades its config; deleting this config does not delete SMS audit rows.</p></div>},...(canDelete?[{key:'delete',label:'Delete',icon:'bi-trash',render:()=><div className="detail-section"><ArmedButton label="Delete provider configuration" armedLabel="Click again to delete" onConfirm={remove}/></div>}]:[])]}/>;}
+export function ProviderConfigsPage(){const canManage=useCan(PHONE_CONFIG_MANAGE_PERMISSIONS).can;return <ModelTable model={PhoneConfigModel} eyebrow="Communications · Phone Hub" title="Provider Configurations" columns={configColumns} defaultSort="name" searchable searchPlaceholder="Search configuration names" columnChooser persistState persistKey="admin:phonehub:configs" exportFormats={['csv','json']} exporter={exportPhoneConfigs} addLabel="Create configuration" onAdd={canManage?()=>void modal.open(close=><ConfigEditor close={close}/>,{size:'lg'}):undefined} onRowClick={row=>void modal.detail(close=><ConfigDetail id={row.id} onClose={()=>close(null)}/>)}/>;}
+
+export function PhoneHubPage(){const canNumbers=useCan(PHONE_NUMBER_VIEW_PERMISSIONS).can;const canSms=useCan(SMS_VIEW_PERMISSIONS).can;const canConfig=useCan(PHONE_CONFIG_VIEW_PERMISSIONS).can;const items=[...(canNumbers?[{key:'numbers',label:'Phone Numbers',panel:<PhoneNumbersPage/>}]:[]),...(canSms?[{key:'sms',label:'SMS',panel:<SmsPage/>}]:[]),...(canConfig?[{key:'config',label:'Provider Config',panel:<ProviderConfigsPage/>}]:[])];return <div className="phonehub-page"><div className="phonehub-heading"><p className="eyebrow">Communications</p><h1>Phone Hub</h1><p className="dim">Global phone intelligence, SMS audit history, and provider configuration. This surface never adopts the active product group.</p></div><Tabs ariaLabel="Phone Hub admin areas" variant="underline-all" items={items}/></div>;}

package/src/admin/phonehub/api.ts

@@ -0,0 +1,47 @@
+import type { QueryClient } from '@tanstack/react-query';
+import { mojoCall, mojoList } from '../../client';
+import { PhoneConfigModel, sanitizePhoneConfigRow, sanitizePhoneNumberRow, type PhoneConfigRow, type PhoneNumberRow, type PhoneRelation } from './models';
+
+export const PHONE_GROUP_CHOICE_LIMIT=100;
+export const PHONE_SECRET_FIELDS=['twilio_account_sid','twilio_auth_token','aws_access_key_id','aws_secret_access_key','mojo_api_key'] as const;
+export type PhoneSecretField=(typeof PHONE_SECRET_FIELDS)[number];
+export type SecretEdit={mode:'untouched'}|{mode:'replace';value:string}|{mode:'clear';confirmed:true};
+
+export async function normalizePhoneNumber(phoneNumber:string,countryCode?:string):Promise<string>{
+    const body=await mojoCall('/api/phonehub/number/normalize',{method:'POST',body:{phone_number:phoneNumber,...(countryCode?{country_code:countryCode}:{})}});
+    const value=(body.data as {phone_number?:unknown}|undefined)?.phone_number;
+    if(typeof value!=='string'||!/^\+[1-9]\d{7,14}$/.test(value))throw new Error('The server did not return a valid E.164 phone number.');
+    return value;
+}
+export async function lookupPhoneNumber(phoneNumber:string,previous?:PhoneNumberRow,confirmFresh?:()=>boolean|Promise<boolean>):Promise<PhoneNumberRow>{
+    const normalized=await normalizePhoneNumber(phoneNumber);
+    const fresh=Boolean(previous?.lookup_expires_at&&previous.lookup_expires_at>Date.now()/1000);
+    if(fresh&&!(await confirmFresh?.()))throw new Error('Fresh lookup cancelled.');
+    const body=await mojoCall('/api/phonehub/number/lookup',{method:'POST',body:{phone_number:normalized,...(fresh?{force_refresh:true}:{})}});
+    const row=sanitizePhoneNumberRow(body.data as PhoneNumberRow);
+    const advanced=previous?row.lookup_count>previous.lookup_count||Boolean(row.last_lookup_at&&row.last_lookup_at!==(previous.last_lookup_at??null)):row.lookup_count>=1&&row.last_lookup_at!=null;
+    if(!advanced)throw new Error('The lookup provider returned no refresh evidence. The cached record was left unchanged.');
+    return row;
+}
+export function buildPhoneConfigPayload(scalars:Record<string,unknown>,credentials:Partial<Record<PhoneSecretField,SecretEdit>>):Record<string,unknown>{
+    const body={...scalars};
+    for(const field of PHONE_SECRET_FIELDS){const edit=credentials[field];if(!edit||edit.mode==='untouched')continue;if(edit.mode==='clear')body[field]=null;else{const value=edit.value.trim();if(!value)throw new Error(`${field} replacements cannot be empty.`);body[field]=value;}}
+    return body;
+}
+export async function savePhoneConfigImperative(qc:QueryClient,id:number|null,scalars:Record<string,unknown>,credentials:Partial<Record<PhoneSecretField,SecretEdit>>):Promise<PhoneConfigRow>{
+    const payload=buildPhoneConfigPayload(scalars,credentials);
+    const path=id==null?PhoneConfigModel.endpoint:`${PhoneConfigModel.endpoint}/${id}`;
+    const response=await mojoCall(path,{method:'POST',body:payload});
+    for(const field of PHONE_SECRET_FIELDS)delete payload[field];
+    const row=sanitizePhoneConfigRow(response.data as PhoneConfigRow);
+    qc.setQueryData(PhoneConfigModel.keys.one(row.id),row);await qc.invalidateQueries({queryKey:PhoneConfigModel.keys.root});return row;
+}
+export async function testPhoneConfigImperative(id:number):Promise<{status:boolean;message:string}>{
+    const response=await mojoCall(`${PhoneConfigModel.endpoint}/${id}`,{method:'POST',body:{test_connection:1}});
+    const data=(response.data??response) as Record<string,unknown>;
+    return {status:data.status!==false,message:typeof data.message==='string'?data.message:'Connection test completed.'};
+}
+export async function fetchPhoneGroupChoices():Promise<PhoneRelation[]>{
+    const result=await mojoList<Record<string,unknown>>('/api/group',{graph:'basic',sort:'name',start:0,size:PHONE_GROUP_CHOICE_LIMIT});
+    return result.rows.flatMap(row=>{const id=Number(row.id);return Number.isFinite(id)&&typeof row.name==='string'?[{id,name:row.name}]:[];});
+}

package/src/admin/phonehub/data.ts

@@ -0,0 +1,6 @@
+import { createSafeExporter } from '../../client';
+import { PhoneConfigModel, PhoneNumberModel, SmsModel, sanitizePhoneConfigRow, sanitizePhoneNumberRow, sanitizeSmsRow, type PhoneConfigRow, type PhoneNumberRow, type SmsRow } from './models';
+const sheet=(value:unknown)=>typeof value==='string'&&/^[\t\r\n\u0000-\u0020]*[=+\-@]/.test(value)?`'${value}`:value;
+export const exportPhoneNumbers=createSafeExporter<PhoneNumberRow>({endpoint:PhoneNumberModel.endpoint,filename:'phone-numbers',sanitizeRow:sanitizePhoneNumberRow,fields:[{key:'id'},{key:'phone_number',value:r=>sheet(r.phone_number)},{key:'country_code'},{key:'carrier',value:r=>sheet(r.carrier)},{key:'line_type'},{key:'is_mobile'},{key:'is_voip'},{key:'is_valid'},{key:'lookup_provider'},{key:'lookup_count'},{key:'last_lookup_at'},{key:'created'}]});
+export const exportSmsAudits=createSafeExporter<SmsRow>({endpoint:SmsModel.endpoint,filename:'sms-audit',sanitizeRow:sanitizeSmsRow,fields:[{key:'id'},{key:'created'},{key:'direction'},{key:'from_number',value:r=>sheet(r.from_number)},{key:'to_number',value:r=>sheet(r.to_number)},{key:'status'},{key:'provider'},{key:'sent_at'},{key:'delivered_at'}]});
+export const exportPhoneConfigs=createSafeExporter<PhoneConfigRow>({endpoint:PhoneConfigModel.endpoint,filename:'phone-provider-configs',sanitizeRow:sanitizePhoneConfigRow,fields:[{key:'id'},{key:'name',value:r=>sheet(r.name)},{key:'provider'},{key:'is_active'},{key:'test_mode'},{key:'lookup_enabled'},{key:'lookup_cache_days'},{key:'created'},{key:'modified'}]});

package/src/admin/phonehub/index.ts

@@ -0,0 +1,10 @@
+import type { AdminSection } from '../index';
+import { PhoneHubPage } from './PhoneHubPage';
+import { PHONE_HUB_ADMIN_PERMISSIONS } from './models';
+
+export * from './models';
+export * from './api';
+export * from './data';
+export * from './PhoneHubPage';
+
+export const PHONE_HUB_ADMIN_SECTION:AdminSection={id:'phonehub',basePath:'phonehub',title:'Phone Hub',icon:'bi-phone',navigationGroup:'communications',permissions:PHONE_HUB_ADMIN_PERMISSIONS,routes:[{path:'',label:'Phone Hub',component:PhoneHubPage,permissions:PHONE_HUB_ADMIN_PERMISSIONS}]};

package/src/admin/phonehub/models.ts

@@ -0,0 +1,68 @@
+import { defineModel, type Params } from '../../client';
+
+export const PHONE_NUMBER_VIEW_PERMISSIONS = ['sys.view_phone_numbers', 'sys.manage_phone_numbers', 'sys.comms', 'sys.manage_users'];
+export const PHONE_NUMBER_MANAGE_PERMISSIONS = ['sys.manage_phone_numbers', 'sys.comms', 'sys.manage_users'];
+export const PHONE_NUMBER_DELETE_PERMISSIONS = ['sys.manage_phone_numbers'];
+export const PHONE_LOOKUP_UI_PERMISSIONS = PHONE_NUMBER_MANAGE_PERMISSIONS;
+export const SMS_VIEW_PERMISSIONS = ['sys.view_sms', 'sys.manage_sms', 'sys.comms', 'sys.owner', 'sys.manage_notifications'];
+export const SMS_MANAGE_PERMISSIONS = ['sys.manage_sms', 'sys.comms', 'sys.manage_notifications'];
+export const SMS_DELETE_PERMISSIONS = ['sys.manage_sms', 'sys.manage_notifications'];
+export const PHONE_CONFIG_VIEW_PERMISSIONS = ['sys.manage_phone_config', 'sys.manage_groups', 'sys.comms'];
+export const PHONE_CONFIG_MANAGE_PERMISSIONS = PHONE_CONFIG_VIEW_PERMISSIONS;
+export const PHONE_CONFIG_DELETE_PERMISSIONS = ['sys.manage_phone_config', 'sys.manage_groups'];
+export const PHONE_HUB_ADMIN_PERMISSIONS = [...new Set([...PHONE_NUMBER_VIEW_PERMISSIONS, ...SMS_VIEW_PERMISSIONS, ...PHONE_CONFIG_VIEW_PERMISSIONS])];
+export const PHONE_GROUP_DIRECTORY_PERMISSIONS = ['sys.view_groups', 'sys.manage_groups', 'sys.manage_group', 'sys.groups'];
+
+export interface PhoneRelation { id: number; name?: string; display_name?: string; email?: string }
+export interface PhoneNumberRow {
+    id:number; created:number; modified:number; phone_number:string; country_code:string|null; region:string|null; state:string|null;
+    carrier:string|null; line_type:string|null; is_mobile:boolean; is_voip:boolean; is_valid:boolean;
+    registered_owner:string|null; owner_type:string|null; address_line1:string|null; address_city:string|null;
+    address_state:string|null; address_zip:string|null; address_country:string|null; lookup_provider:string|null;
+    lookup_expires_at:number|null; lookup_count:number; last_lookup_at:number|null;
+}
+export interface SmsRow {
+    id:number; created:number; modified?:number; direction:string; from_number:string; to_number:string; body:string;
+    status:string; provider:string|null; error_message:string|null; sent_at:number|null; delivered_at:number|null;
+    user:PhoneRelation|number|null; group:PhoneRelation|number|null;
+}
+export interface PhoneConfigRow {
+    id:number; created:number; modified:number; group:PhoneRelation|number|null; name:string; is_active:boolean;
+    provider:'twilio'|'aws'|'mojo'; twilio_from_number:string|null; aws_region:string|null; aws_sender_id:string|null;
+    mojo_remote_url:string|null; lookup_enabled:boolean; lookup_cache_days:number; test_mode:boolean;
+}
+
+const COMMON = new Set(['start','size','search']);
+function listParams(params:Params, graph:string, filters:readonly string[], sorts:readonly string[], defaultSort:string, dateRange=false):Params {
+    const out:Params={graph,start:params.start??0,size:params.size??25,sort:defaultSort};
+    for(const key of COMMON)if(params[key]!=null&&params[key]!=='')out[key]=params[key];
+    for(const key of filters)if(params[key]!=null&&params[key]!=='')out[key]=params[key];
+    const requested=typeof params.sort==='string'?params.sort:'';
+    if(sorts.includes(requested.replace(/^-/,'')))out.sort=requested;
+    if(dateRange&&(params.dr_start||params.dr_end)){out.dr_field='created';if(params.dr_start)out.dr_start=params.dr_start;if(params.dr_end)out.dr_end=params.dr_end;}
+    return out;
+}
+const relation=(value:unknown):PhoneRelation|number|null=>{
+    if(typeof value==='number')return value;
+    if(!value||typeof value!=='object')return null;
+    const row=value as Record<string,unknown>;const id=Number(row.id);if(!Number.isFinite(id))return null;
+    return {id,...(typeof row.name==='string'?{name:row.name}:{}),...(typeof row.display_name==='string'?{display_name:row.display_name}:{}),...(typeof row.email==='string'?{email:row.email}:{})};
+};
+const text=(value:unknown)=>typeof value==='string'?value:null;
+const num=(value:unknown)=>typeof value==='number'&&Number.isFinite(value)?value:null;
+export function sanitizePhoneNumberRow(input:PhoneNumberRow):PhoneNumberRow {
+    const row=input as unknown as Record<string,unknown>;
+    return {id:Number(row.id),created:Number(row.created??0),modified:Number(row.modified??0),phone_number:String(row.phone_number??''),country_code:text(row.country_code),region:text(row.region),state:text(row.state),carrier:text(row.carrier),line_type:text(row.line_type),is_mobile:Boolean(row.is_mobile),is_voip:Boolean(row.is_voip),is_valid:Boolean(row.is_valid),registered_owner:text(row.registered_owner),owner_type:text(row.owner_type),address_line1:text(row.address_line1),address_city:text(row.address_city),address_state:text(row.address_state),address_zip:text(row.address_zip),address_country:text(row.address_country),lookup_provider:text(row.lookup_provider),lookup_expires_at:num(row.lookup_expires_at),lookup_count:Number(row.lookup_count??0),last_lookup_at:num(row.last_lookup_at)};
+}
+export function sanitizeSmsRow(input:SmsRow):SmsRow {
+    const row=input as unknown as Record<string,unknown>;
+    return {id:Number(row.id),created:Number(row.created??0),modified:num(row.modified)??undefined,direction:String(row.direction??''),from_number:String(row.from_number??''),to_number:String(row.to_number??''),body:String(row.body??''),status:String(row.status??''),provider:text(row.provider),error_message:text(row.error_message),sent_at:num(row.sent_at),delivered_at:num(row.delivered_at),user:relation(row.user),group:relation(row.group)};
+}
+export function sanitizePhoneConfigRow(input:PhoneConfigRow):PhoneConfigRow {
+    const row=input as unknown as Record<string,unknown>;const provider=['twilio','aws','mojo'].includes(String(row.provider))?String(row.provider) as PhoneConfigRow['provider']:'twilio';
+    return {id:Number(row.id),created:Number(row.created??0),modified:Number(row.modified??0),group:relation(row.group),name:String(row.name??''),is_active:Boolean(row.is_active),provider,twilio_from_number:text(row.twilio_from_number),aws_region:text(row.aws_region),aws_sender_id:text(row.aws_sender_id),mojo_remote_url:text(row.mojo_remote_url),lookup_enabled:Boolean(row.lookup_enabled),lookup_cache_days:Number(row.lookup_cache_days??90),test_mode:Boolean(row.test_mode)};
+}
+
+export const PhoneNumberModel=defineModel<PhoneNumberRow>({name:'phone-number',endpoint:'/api/phonehub/number',permissions:{view:PHONE_NUMBER_VIEW_PERMISSIONS,manage:PHONE_NUMBER_MANAGE_PERMISSIONS,delete:PHONE_NUMBER_DELETE_PERMISSIONS},normalizeListParams:p=>listParams(p,'default',[],['phone_number','carrier','line_type','lookup_count','last_lookup_at','created','modified'],'phone_number'),sanitizeRow:sanitizePhoneNumberRow});
+export const SmsModel=defineModel<SmsRow>({name:'sms-audit',endpoint:'/api/phonehub/sms',permissions:{view:SMS_VIEW_PERMISSIONS,manage:SMS_MANAGE_PERMISSIONS,delete:SMS_DELETE_PERMISSIONS},normalizeListParams:p=>listParams(p,'default',['direction','status','provider','group','user'],['created','direction','status','provider','sent_at','delivered_at'],'-created',true),sanitizeRow:sanitizeSmsRow});
+export const PhoneConfigModel=defineModel<PhoneConfigRow>({name:'phone-config',endpoint:'/api/phonehub/config',permissions:{view:PHONE_CONFIG_VIEW_PERMISSIONS,manage:PHONE_CONFIG_MANAGE_PERMISSIONS,delete:PHONE_CONFIG_DELETE_PERMISSIONS},normalizeListParams:p=>listParams(p,'default',['provider','is_active','group','test_mode'],['name','provider','is_active','created','modified'],'name'),sanitizeRow:sanitizePhoneConfigRow});

package/src/admin/rules/HandlerChainBuilder.tsx

@@ -0,0 +1,51 @@
+import { useEffect, useMemo, useState } from 'react';
+import { registerFieldType, type RegistryFieldProps } from '../../ui/field-registry';
+import {
+    HANDLER_DEFINITIONS, addHandlerStep, moveHandlerStep, parseHandlerChain, removeHandlerStep,
+    serializeHandlerChain, updateHandlerStep, validateHandlerChain, type HandlerChain, type HandlerScheme,
+} from './handler-dsl';
+
+export interface HandlerChainBuilderProps {
+    value: string;
+    onChange: (value: string) => void;
+    disabled?: boolean;
+    onValidationChange?: (valid: boolean, messages: string[]) => void;
+}
+
+function confirmLegacy(message: string): boolean {
+    return typeof window !== 'undefined' && window.confirm(`${message}\n\nThis can change which handlers django-mojo dispatches. Continue?`);
+}
+
+export function HandlerChainBuilder({ value, onChange, disabled = false, onValidationChange }: HandlerChainBuilderProps) {
+    const [chain, setChain] = useState<HandlerChain>(() => parseHandlerChain(value));
+    useEffect(() => { if (serializeHandlerChain(chain) !== value) setChain(parseHandlerChain(value)); }, [value]); // eslint-disable-line react-hooks/exhaustive-deps
+    const issues = useMemo(() => validateHandlerChain(chain), [chain]);
+    useEffect(() => onValidationChange?.(!issues.some((issue) => issue.level === 'error'), issues.map((issue) => issue.message)), [issues, onValidationChange]);
+    const commit = (next: HandlerChain) => { setChain(next); onChange(serializeHandlerChain(next)); };
+    const guarded = (indexes: number[], operation: (confirm: boolean) => HandlerChain, message: string) => {
+        const legacy = indexes.some((index) => chain.steps[index]?.runtime !== 'effective');
+        if (!legacy) return commit(operation(false));
+        if (confirmLegacy(message)) commit(operation(true));
+    };
+    return <div className="handler-chain-builder">
+        <div className="handler-chain-heading"><div><strong>Dispatch chain</strong><small>Order controls publication order; async completion may differ.</small></div><select className="input input-compact" aria-label="Add handler" disabled={disabled} value="" onChange={(event) => { if (event.target.value) commit(addHandlerStep(chain, event.target.value as HandlerScheme)); }}><option value="">Add handler…</option>{HANDLER_DEFINITIONS.map((definition) => <option key={definition.scheme} value={definition.scheme}>{definition.label}</option>)}</select></div>
+        {!chain.steps.length && <div className="handler-chain-empty">No handler: matching events are recorded without dispatching an action.</div>}
+        {chain.steps.map((step, index) => {
+            const definition = HANDLER_DEFINITIONS.find((item) => item.scheme === step.scheme);
+            const stepIssues = issues.filter((issue) => issue.step === index);
+            return <section className={`handler-step${step.runtime !== 'effective' ? ' handler-step-warning' : ''}`} key={`${index}:${step.raw}`}>
+                <header><span className="handler-order">{index + 1}</span><div><strong>{definition?.label ?? `${step.scheme ?? 'Malformed'} handler`}</strong><small>{step.runtime === 'effective' ? 'Runtime effective' : step.runtime === 'swallowed' ? `Swallowed into step ${(step.runtimeOwner ?? 0) + 1}` : 'Skipped by runtime'}</small></div><div className="handler-order-controls"><button type="button" className="btn btn-compact" disabled={disabled || index === 0} aria-label={`Move handler ${index + 1} up`} onClick={() => guarded([index, index - 1], (confirmed) => moveHandlerStep(chain, index, index - 1, { confirmBehaviorChange: confirmed }), 'Move legacy content?')}>↑</button><button type="button" className="btn btn-compact" disabled={disabled || index === chain.steps.length - 1} aria-label={`Move handler ${index + 1} down`} onClick={() => guarded([index, index + 1], (confirmed) => moveHandlerStep(chain, index, index + 1, { confirmBehaviorChange: confirmed }), 'Move legacy content?')}>↓</button><button type="button" className="btn btn-compact btn-danger" disabled={disabled} onClick={() => guarded([index], (confirmed) => removeHandlerStep(chain, index, { confirmBehaviorChange: confirmed }), 'Remove legacy content?')}>Remove</button></div></header>
+                {step.supported && <div className="handler-step-fields"><label className="field"><span className="field-label">Type</span><select className="input" disabled={disabled} value={step.scheme ?? ''} onChange={(event) => commit(updateHandlerStep(chain, index, { scheme: event.target.value as HandlerScheme }))}>{HANDLER_DEFINITIONS.map((item) => <option key={item.scheme} value={item.scheme}>{item.label}</option>)}</select></label>{definition?.target !== 'none' && <label className="field"><span className="field-label">{definition?.target === 'targets' ? 'Targets (comma separated)' : 'Module path'}</span><input className="input" disabled={disabled} defaultValue={step.target} onBlur={(event) => { if (event.target.value !== step.target) commit(updateHandlerStep(chain, index, { target: event.target.value })); }} /></label>}</div>}
+                {step.supported && <details className="handler-advanced"><summary>Advanced ordered parameters</summary>{step.params.length ? step.params.map((param, paramIndex) => <div className="handler-param" key={`${paramIndex}:${param.key}`}><code>{param.key || '(blank key)'}</code><input className="input input-compact" disabled={disabled} defaultValue={param.value} onBlur={(event) => { if (event.target.value !== param.value) commit(updateHandlerStep(chain, index, { param: { key: param.key, value: event.target.value } })); }} /><button type="button" className="btn btn-compact" disabled={disabled} onClick={() => commit(updateHandlerStep(chain, index, { removeParam: param.key }))}>Remove</button></div>) : <p className="dim">No query parameters.</p>}<button type="button" className="btn btn-compact" disabled={disabled} onClick={() => { const key = window.prompt('Parameter name'); if (key != null) commit(updateHandlerStep(chain, index, { param: { key, value: '' } })); }}>Add parameter</button></details>}
+                <pre className="handler-raw">{step.raw}</pre>
+                {stepIssues.map((issue, issueIndex) => <div className={`handler-issue handler-issue-${issue.level}`} key={issueIndex}>{issue.message}</div>)}
+            </section>;
+        })}
+    </div>;
+}
+
+export function IncidentHandlerChainField({ value, disabled, commit }: RegistryFieldProps) {
+    return <HandlerChainBuilder value={typeof value === 'string' ? value : ''} disabled={disabled} onChange={commit} />;
+}
+
+registerFieldType('incident-handler-chain', IncidentHandlerChainField);

package/src/admin/rules/RuleSetDetailPage.tsx

@@ -0,0 +1,33 @@
+import { useMemo } from 'react';
+import { useCan } from '../../client';
+import { Badge, DetailView, FlatRow, JsonBlock, ModelTable, fmt, modal, toast, type BatchAction, type Column } from '../../ui';
+import { HandlerChainBuilder } from './HandlerChainBuilder';
+import { parseHandlerChain, runtimeEffectiveHandlerChain, validateHandlerChain } from './handler-dsl';
+import { confirmCatchAllEnable, openHandlerChainEditor, openRuleEditor, openRuleSetEditor } from './editors';
+import { BUNDLE_BY_OPTIONS, RULESET_MANAGE_PERMS, RuleModel, RuleSetModel, type RuleRow } from './models';
+
+export function RuleSetDetail({ id, onClose }: { id: number; onClose: () => void }) {
+    const { can: canManage } = useCan(RULESET_MANAGE_PERMS); const query = RuleSetModel.useOne(Number.isFinite(id) ? id : null);
+    const rules = RuleModel.useList({ parent: id, size: 250, sort: 'index' }); const save = RuleSetModel.useSave(); const destroy = RuleSetModel.useDelete(); const destroyRule = RuleModel.useDelete();
+    const duplicateIndexes = useMemo(() => { const counts = new Map<number, number>(); for (const row of rules.data?.rows ?? []) counts.set(row.index, (counts.get(row.index) ?? 0) + 1); return [...counts].filter(([, count]) => count > 1).map(([index]) => index); }, [rules.data]);
+    if (!Number.isFinite(id)) return <div className="modal-pad text-bad">Invalid rule-set id. <button type="button" className="btn" onClick={onClose}>Close</button></div>;
+    if (query.isPending || !query.data) return <div className="modal-pad dim">Loading rule set… <button type="button" className="btn" onClick={onClose}>Close</button></div>;
+    const row = query.data; const chain = parseHandlerChain(row.handler); const handlerIssues = validateHandlerChain(chain); const nextIndex = Math.max(-1, ...(rules.data?.rows ?? []).map((rule) => rule.index)) + 1;
+    const ruleColumns: Column<RuleRow>[] = [
+        { key: 'index', label: 'Index', sortable: true, align: 'center', render: (rule) => <Badge tone={duplicateIndexes.includes(rule.index) ? 'warning' : 'muted'}>{rule.index}</Badge> },
+        { key: 'name', label: 'Condition', sortable: true, hideable: false }, { key: 'field_name', label: 'Field', render: (rule) => <code>{rule.field_name}</code> },
+        { key: 'comparator', label: 'Comparator', render: (rule) => <code>{rule.comparator}</code> }, { key: 'value', label: 'Value', render: (rule) => <code>{rule.value_type}:{rule.value}</code> },
+        { key: 'is_required', label: 'Required', render: (rule) => rule.is_required ? 'Yes' : 'No' },
+    ];
+    const ruleActions: BatchAction<RuleRow>[] = canManage ? [{ key: 'delete', label: 'Delete conditions', icon: 'bi-trash', danger: true, confirm: 'Delete the selected conditions? This cannot be undone.', run: (rule) => destroyRule.mutateAsync({ id: rule.id }) }] : [];
+    const setActive = async (next: boolean) => { if (next && !(await confirmCatchAllEnable(row, rules.data?.count ?? 0))) return; try { await save.mutateAsync({ id, changes: { is_active: next } }); toast.success(next ? 'Rule set enabled' : 'Rule set disabled'); } catch (error) { toast.error(error instanceof Error ? error.message : 'State change failed'); } };
+    const bundleLabel = BUNDLE_BY_OPTIONS.find((option) => Number(option.value) === row.bundle_by)?.label ?? `Unknown (${row.bundle_by})`;
+    return <DetailView icon="bi-diagram-3" title={row.name || `Rule set #${row.id}`} subtitle={`${row.category} · priority ${row.priority} · first active match wins`} chips={[{ text: row.is_active ? 'ACTIVE' : 'INACTIVE', tone: row.is_active ? 'success' : 'muted' }, { text: `${rules.data?.count ?? 0} CONDITIONS`, tone: duplicateIndexes.length ? 'warning' : 'info' }]} active={canManage ? { value: row.is_active, onChange: (next) => void setActive(next) } : undefined} onClose={onClose} menuContext={row} contextMenu={canManage ? [{ label: 'Edit rule set', onSelect: () => void openRuleSetEditor(row) }, { label: 'Edit handler chain', onSelect: () => void openHandlerChainEditor(row) }, { divider: true }, { label: 'Delete rule set and conditions', danger: true, onSelect: async () => { if (!(await modal.confirm({ title: 'Delete rule set?', message: `Delete “${row.name}” and all ${rules.data?.count ?? 0} conditions?`, confirmText: 'Delete rule set', danger: true }))) return; await destroy.mutateAsync({ id }); onClose(); } }] : []} sections={[
+        { key: 'overview', label: 'Overview', icon: 'bi-info-circle', render: () => <div className="detail-stack"><FlatRow label="State">{row.is_active ? 'Active' : 'Inactive'}</FlatRow><FlatRow label="Category"><code>{row.category}</code></FlatRow><FlatRow label="Priority">{row.priority} (lower is evaluated first within this category)</FlatRow><FlatRow label="Matching">{row.match_by === 0 ? 'All conditions' : row.match_by === 1 ? 'Any condition' : `Unknown (${row.match_by})`}</FlatRow><FlatRow label="Created">{fmt.datetime(row.created)}</FlatRow></div> },
+        { key: 'conditions', label: 'Conditions', icon: 'bi-funnel', render: () => <div>{duplicateIndexes.length > 0 && <div className="rule-priority-warning">Duplicate condition indexes {duplicateIndexes.join(', ')} have undefined tie order.</div>}<ModelTable model={RuleModel} title="Conditions" columns={ruleColumns} searchable={false} defaultParams={{ parent: id, sort: 'index' }} onRowClick={canManage ? (rule) => void openRuleEditor(id, rule, nextIndex) : undefined} {...(canManage ? { addLabel: 'Add condition', onAdd: () => void openRuleEditor(id, undefined, nextIndex), selectable: true, batchActions: ruleActions } : {})} /></div> },
+        { key: 'triggering', label: 'Triggering', icon: 'bi-lightning', render: () => <div className="detail-stack"><FlatRow label="Bundle by">{bundleLabel}</FlatRow><FlatRow label="Bundle window">{row.bundle_minutes == null ? 'Unbounded' : row.bundle_minutes === 0 ? 'Disabled (no time bundling)' : `${row.bundle_minutes} minutes`}</FlatRow><FlatRow label="Trigger">{row.trigger_count == null ? 'Immediately on first event' : `${row.trigger_count} events${row.trigger_window == null ? '' : ` within ${row.trigger_window} minutes`}`}</FlatRow><FlatRow label="Re-trigger">{row.retrigger_every == null ? 'Once per incident' : `Every ${row.retrigger_every} additional events`}</FlatRow></div> },
+        { key: 'handler', label: 'Handler', icon: 'bi-diagram-3', render: () => <div><div className="handler-section-actions"><p>{runtimeEffectiveHandlerChain(chain).length} runtime-effective dispatch step(s). Publication follows the order below; completion is asynchronous.</p>{canManage && <button type="button" className="btn btn-primary" onClick={() => void openHandlerChainEditor(row)}>Edit chain</button>}</div><HandlerChainBuilder value={row.handler ?? ''} onChange={() => undefined} disabled />{handlerIssues.length > 0 && <p className="dim">Legacy warnings remain visible and byte-preserved until explicitly changed.</p>}</div> },
+        { key: 'agent', label: 'Agent prompt', icon: 'bi-stars', render: () => <div className="detail-stack"><FlatRow label="Prompt">{typeof row.metadata.agent_prompt === 'string' ? row.metadata.agent_prompt : 'No agent prompt configured.'}</FlatRow><p className="dim">The prompt is stored in RuleSet metadata. General edits merge only targeted metadata keys.</p></div> },
+        { key: 'metadata', label: 'Metadata', icon: 'bi-braces', render: () => <JsonBlock value={row.metadata} /> },
+    ]} />;
+}

package/src/admin/rules/RuleSetsPage.tsx

@@ -0,0 +1,33 @@
+import { useMemo } from 'react';
+import { useCan } from '../../client';
+import { Badge, ModelTable, fmt, modal, type Column, type FilterDef } from '../../ui';
+import { parseHandlerChain } from './handler-dsl';
+import { openRuleSetEditor } from './editors';
+import { BUNDLE_BY_OPTIONS, RULESET_MANAGE_PERMS, RuleSetModel, type RuleSetRow } from './models';
+import { RuleSetDetail } from './RuleSetDetailPage';
+
+function handlerSummary(value: string | null) {
+    const chain = parseHandlerChain(value);
+    if (!chain.steps.length) return <span className="dim">Record only</span>;
+    return <span className="handler-chip-row">{chain.steps.map((step, index) => <Badge key={`${index}:${step.raw}`} tone={step.supported && step.runtime === 'effective' ? 'info' : 'warning'}>{step.scheme ?? 'malformed'}{step.runtime === 'effective' ? '' : ' ⚠'}</Badge>)}</span>;
+}
+
+export function RuleSetsPage() {
+    const { can: canManage } = useCan(RULESET_MANAGE_PERMS);
+    const inventory = RuleSetModel.useList({ size: 500, sort: 'priority' });
+    const ties = useMemo(() => {
+        const counts = new Map<string, number>();
+        for (const row of inventory.data?.rows ?? []) { const key = `${row.category}\u0000${row.priority}`; counts.set(key, (counts.get(key) ?? 0) + 1); }
+        return [...counts].filter(([, count]) => count > 1).map(([key]) => { const [category, priority] = key.split('\u0000'); return `${category} priority ${priority}`; });
+    }, [inventory.data]);
+    const columns: Column<RuleSetRow>[] = [
+        { key: 'priority', label: 'Priority', sortable: true, align: 'center', render: (row) => <Badge tone="primary">{row.priority}</Badge> },
+        { key: 'is_active', label: 'State', sortable: true, render: (row) => <Badge tone={row.is_active ? 'success' : 'muted'}>{row.is_active ? 'Active' : 'Inactive'}</Badge> },
+        { key: 'name', label: 'Rule set', sortable: true, hideable: false, render: (row) => <span><strong>{row.name || `Rule set #${row.id}`}</strong><small className="table-cell-subtitle"><code>{row.category}</code> · first active match wins</small></span> },
+        { key: 'bundle_by', label: 'Triggering', sortable: true, render: (row) => <span>{BUNDLE_BY_OPTIONS.find((option) => Number(option.value) === row.bundle_by)?.label ?? `Unknown (${row.bundle_by})`}<small className="table-cell-subtitle">{row.trigger_count == null ? 'Immediate' : `${row.trigger_count} events${row.trigger_window == null ? '' : ` / ${row.trigger_window}m`}`} · bundle {row.bundle_minutes == null ? 'unbounded' : `${row.bundle_minutes}m`}</small></span> },
+        { key: 'handler', label: 'Dispatch chain', render: (row) => handlerSummary(row.handler) },
+        { key: 'modified', label: 'Modified', sortable: true, render: (row) => fmt.datetime(row.modified) },
+    ];
+    const filters: FilterDef[] = [{ key: 'is_active', label: 'Active', type: 'boolean' }, { key: 'category', label: 'Category', type: 'text' }, { key: 'priority', label: 'Priority', type: 'number' }, { key: 'bundle_by', label: 'Bundle mode', type: 'select', options: BUNDLE_BY_OPTIONS.map((option) => ({ value: String(option.value), label: option.label })) }];
+    return <div className="admin-rules-page">{ties.length > 0 && <div className="rule-priority-warning"><strong>Undefined tie order:</strong> {ties.join(', ')}. Edit one priority; multi-row reorder is intentionally unavailable.</div>}<ModelTable model={RuleSetModel} title="Rule Engine" eyebrow="Security operations" columns={columns} filters={filters} searchable searchPlaceholder="Search rule-set names" defaultParams={{ sort: 'priority' }} presets={[{ key: 'all', label: 'All', params: {} }, { key: 'active', label: 'Active', params: { is_active: 'true' } }, { key: 'inactive', label: 'Inactive', params: { is_active: 'false' } }]} columnChooser persistState persistKey="admin-security-rules" onRowClick={(row) => void modal.detail((close) => <RuleSetDetail id={row.id} onClose={() => close(null)} />)} {...(canManage ? { addLabel: 'New inactive rule set', onAdd: () => void openRuleSetEditor() } : {})} /></div>;
+}

package/src/admin/rules/editors.tsx

@@ -0,0 +1,54 @@
+import { useCallback, useMemo, useState } from 'react';
+import { SchemaForm, modal, toast, type Field, type FormData } from '../../ui';
+import { HandlerChainBuilder } from './HandlerChainBuilder';
+import {
+    BUNDLE_BY_OPTIONS, COMPARATOR_OPTIONS, MATCH_BY_OPTIONS, RuleModel, RuleSetModel, VALUE_TYPE_OPTIONS,
+    optionsWithUnknownValue, ruleChanges, ruleSetChanges, type RuleRow, type RuleSetRow,
+} from './models';
+
+const RULESET_FIELDS = (row?: RuleSetRow): Field[] => [
+    { name: 'name', type: 'text', label: 'Name', required: true }, { name: 'category', type: 'text', label: 'Event category', required: true },
+    { name: 'priority', type: 'text', label: 'Priority', required: true, columns: 6 },
+    { name: 'match_by', type: 'select', label: 'Match mode', columns: 6, options: optionsWithUnknownValue(MATCH_BY_OPTIONS, row?.match_by) },
+    { name: 'bundle_by', type: 'select', label: 'Bundle by', columns: 6, options: optionsWithUnknownValue(BUNDLE_BY_OPTIONS, row?.bundle_by) },
+    { name: 'bundle_minutes', type: 'text', label: 'Bundle minutes (0 disables, blank is unbounded)', columns: 6 },
+    { name: 'trigger_count', type: 'text', label: 'Trigger count', columns: 6 }, { name: 'trigger_window', type: 'text', label: 'Trigger window (minutes)', columns: 6 },
+    { name: 'retrigger_every', type: 'text', label: 'Re-trigger every', columns: 6 }, { name: 'bundle_by_rule_set', type: 'switch', label: 'Include rule set in bundle key', columns: 6 },
+    { name: 'metadata.agent_prompt', type: 'textarea', label: 'Agent prompt', help: 'Merged into metadata without replacing unknown metadata keys.' },
+];
+
+function RuleSetEditor({ row, close }: { row?: RuleSetRow; close: (saved: boolean) => void }) {
+    const save = RuleSetModel.useSave(); const creating = !row;
+    const initial: FormData = row ? { name: row.name ?? '', category: row.category, priority: row.priority, match_by: row.match_by, bundle_by: row.bundle_by, bundle_minutes: row.bundle_minutes, trigger_count: row.trigger_count, trigger_window: row.trigger_window, retrigger_every: row.retrigger_every, bundle_by_rule_set: row.bundle_by_rule_set, 'metadata.agent_prompt': typeof row.metadata.agent_prompt === 'string' ? row.metadata.agent_prompt : '' } : { name: '', category: '', priority: 10, match_by: 0, bundle_by: 4, bundle_minutes: 30, trigger_count: null, trigger_window: null, retrigger_every: null, bundle_by_rule_set: true, 'metadata.agent_prompt': '' };
+    return <div className="modal-pad"><h2 className="modal-title">{creating ? 'Create inactive rule set' : 'Edit rule set'}</h2>{creating && <div className="form-alert form-alert-info">New rule sets are always inactive. Add conditions and review the handler before enabling.</div>}<SchemaForm fields={RULESET_FIELDS(row)} initial={initial} submitText={creating ? 'Create inactive rule set' : 'Save changes'} onCancel={() => close(false)} onSubmit={async (data) => { await save.mutateAsync({ id: row?.id ?? null, changes: ruleSetChanges(data, creating, row) }); toast.success(creating ? 'Inactive rule set created' : 'Rule set updated'); close(true); }} /></div>;
+}
+
+export async function openRuleSetEditor(row?: RuleSetRow): Promise<boolean> { return (await modal.open<boolean>((close) => <RuleSetEditor row={row} close={close} />, { size: 'lg' })) ?? false; }
+
+function RuleEditor({ parent, row, nextIndex, close }: { parent: number; row?: RuleRow; nextIndex: number; close: (saved: boolean) => void }) {
+    const save = RuleModel.useSave(); const creating = !row;
+    const fields: Field[] = [
+        { name: 'name', type: 'text', label: 'Condition name', required: true }, { name: 'index', type: 'text', label: 'Evaluation index', required: true, columns: 6 },
+        { name: 'field_name', type: 'text', label: 'Event or metadata field', required: true, columns: 6 },
+        { name: 'comparator', type: 'select', label: 'Comparator', options: optionsWithUnknownValue(COMPARATOR_OPTIONS, row?.comparator), columns: 6 },
+        { name: 'value_type', type: 'select', label: 'Value type', options: optionsWithUnknownValue(VALUE_TYPE_OPTIONS, row?.value_type), columns: 6, help: row?.value_type === 'bool' ? 'Legacy bool values are visible, but cannot be changed safely until the backend conversion is fixed.' : undefined },
+        { name: 'value', type: 'textarea', label: 'Comparison value', required: true }, { name: 'is_required', type: 'switch', label: 'Required condition' },
+    ];
+    const initial: FormData = row ? { name: row.name ?? '', index: row.index, field_name: row.field_name ?? '', comparator: row.comparator, value_type: row.value_type, value: row.value, is_required: row.is_required === 1 } : { name: '', index: nextIndex, field_name: '', comparator: '==', value_type: 'str', value: '', is_required: false };
+    return <div className="modal-pad"><h2 className="modal-title">{creating ? 'Add condition' : 'Edit condition'}</h2><SchemaForm fields={fields} initial={initial} onCancel={() => close(false)} onSubmit={async (data) => { await save.mutateAsync({ id: row?.id ?? null, changes: ruleChanges({ ...data, parent }, creating, row) }); toast.success(creating ? 'Condition added' : 'Condition updated'); close(true); }} /></div>;
+}
+export async function openRuleEditor(parent: number, row?: RuleRow, nextIndex = 0): Promise<boolean> { return (await modal.open<boolean>((close) => <RuleEditor parent={parent} row={row} nextIndex={nextIndex} close={close} />, { size: 'lg' })) ?? false; }
+
+function HandlerEditor({ row, close }: { row: RuleSetRow; close: (saved: boolean) => void }) {
+    const save = RuleSetModel.useSave(); const [value, setValue] = useState(row.handler ?? ''); const [valid, setValid] = useState(true); const [messages, setMessages] = useState<string[]>([]);
+    const changed = value !== (row.handler ?? '');
+    const summary = useMemo(() => [...new Set(messages)], [messages]);
+    const validationChanged = useCallback((next: boolean, nextMessages: string[]) => { setValid(next); setMessages(nextMessages); }, []);
+    return <form className="modal-pad" onSubmit={async (event) => { event.preventDefault(); if (!valid || !changed) return; try { await save.mutateAsync({ id: row.id, changes: { handler: value } }); toast.success('Handler chain updated'); close(true); } catch (error) { toast.error(error instanceof Error ? error.message : 'Handler save failed'); } }}><h2 className="modal-title">Edit handler dispatch chain</h2><HandlerChainBuilder value={value} onChange={setValue} onValidationChange={validationChanged} />{summary.length > 0 && <p className="dim">{summary.length} validation note{summary.length === 1 ? '' : 's'} shown inline. Structural errors must be resolved before save.</p>}<div className="modal-actions"><button type="button" className="btn" onClick={() => close(false)}>Cancel</button><button type="submit" className="btn btn-primary" disabled={!changed || !valid || save.isPending}>{save.isPending ? 'Saving…' : 'Save handler chain'}</button></div></form>;
+}
+export async function openHandlerChainEditor(row: RuleSetRow): Promise<boolean> { return (await modal.open<boolean>((close) => <HandlerEditor row={row} close={close} />, { size: 'lg' })) ?? false; }
+
+export async function confirmCatchAllEnable(row: RuleSetRow, conditionCount: number): Promise<boolean> {
+    if (conditionCount > 0) return window.confirm(`Enable “${row.name}” in category ${row.category} at priority ${row.priority}?`);
+    return window.confirm(`PREEMPTION WARNING\n\n“${row.name}” has zero conditions. Enabling it creates a catch-all for category “${row.category}” at priority ${row.priority}; it can preempt every later active rule set. Enable anyway?`);
+}